home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 3 / Meeting_Pearls_III.iso / Pearls / dev / Libraries / Date / doc / TextEngine.doc < prev    next >
Encoding:
Text File  |  1995-07-31  |  12.5 KB  |  411 lines
  1. TABLE OF CONTENTS
  2.  
  3. TextEngine/--background--
  4. TextEngine/--compiling--
  5. TextEngine/--history--
  6. TextEngine/--todo--
  7. TextEngine/TextEngine
  8. TextEngine/TextEngineJD
  9. TextEngine/--background--                           TextEngine/--background--
  10.  
  11.    NAME
  12.     TextEngine -- This module helps you with text features (V33)
  13.  
  14.    FUNCTION
  15.     This module handles strings with different % commands
  16.  
  17.    NOTES
  18.     None.
  19.  
  20.    COPYRIGHT
  21.     This software is copyrighted 1994-95 by Kai Hofmann.
  22.     All rights reserved!
  23.  
  24.     - Permission for COMMERCIAL USE is only given by an extra available
  25.       commercial license that must be validated!
  26.       Contact me directly for this license, because it will be
  27.       individually handed out per your needs!
  28.  
  29.     - Permission is hereby granted, without written agreement and without
  30.       license, to USE this software and its documentation for any
  31.       NON-COMMERCIAL purpose, provided that the above copyright notice
  32.       and the following paragraph appear in all copies of this software
  33.       (Non-commercial includes Giftware and Shareware!).
  34.  
  35.       You *must* include the following notice in your product and in your
  36.       documentation:
  37.       "This software uses the textengine that is copyrighted 1994-95 by
  38.        Kai Hofmann"
  39.  
  40.       You "must" send me a full version of your product at no cost
  41.       including free updates!
  42.       Extra money is welcome (For Bank Account see below - but *ONLY*
  43.       send in DM to this Bank Account!).
  44.  
  45.     - THERE IS *NO PERMISSION* GIVEN TO MODIFY THIS SOFTWARE!
  46.  
  47.       If you need only parts of this software, you should not worry,
  48.       because it's the job of the optimizer from your C compiler to
  49.       include only the needed parts in your executable!
  50.  
  51.    DISCLAIMER
  52.     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
  53.     APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
  54.     HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
  55.     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
  56.     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  57.     A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
  58.     PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
  59.     DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
  60.     CORRECTION.
  61.  
  62.     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
  63.     WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE
  64.     THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
  65.     INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
  66.     ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING
  67.     BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
  68.     LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
  69.     TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
  70.     PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  71.  
  72.     THE AUTHOR HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT,
  73.     UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  74.  
  75.    DISTRIBUTION
  76.     Permission is hereby granted, without written agreement and without
  77.     license or royalty fees, to copy and distribute this software and its
  78.     documentation for any purpose, provided that the above copyright
  79.     notice and the following paragraphs appear in all copies of this
  80.     software, to:
  81.     - All who will distribute this software for free!
  82.     - All free accessible INTERNET servers and PHONE boxes!
  83.     - All Aminet sites
  84.     - All SimTel sites
  85.     - Fred Fish for his great Amiga-Software-Library
  86.     - The German SAAR AG PD-Library
  87.     - All others who do NOT take more than $5.- for one disk that
  88.       includes this software!
  89.     - ALL others who do NOT take more than $40.- for one CD that includes
  90.       this software!
  91.  
  92.    ADDITIONAL INFORMATIONS
  93.     I have tried to make portable/useful and I hope bugfree software
  94.     for eternity!
  95.     So I hope very much that to some extend I will be compensated for my
  96.     hard work - monetarily or otherwise:-)
  97.  
  98.     Kindly send US - dollars to a friend of mine in the USA who will
  99.     forward it to me in a timely manner.  Please send checks or money
  100.     orders only.
  101.     Contact me via email for more!
  102.  
  103.    AUTHOR
  104.     Kai Hofmann
  105.     Arberger Heerstraße 92
  106.     28307 Bremen
  107.     Germany
  108.  
  109.     Phone: (+49)-(0)421/480780
  110.            (Remember that my parents don't speak english!)
  111.     EMail: i07m@zfn.uni-bremen.de
  112.            i07m@informatik.uni-bremen.de
  113.     IRC  : PowerStat@#AmigaGer
  114.     WWW  : http://www.informatik.uni-bremen.de/~i07m
  115.  
  116.     Bank account : 1203 7503
  117.     Account owner: Kai Hofmann
  118.     Bank code    : 290 501 01
  119.     Bank name    : Sparkasse in Bremen/Germany
  120.  
  121.     THANKS
  122.     Thank you's are going to the following people:
  123.     Rita Reichl        - For correcting my bad english (very often)
  124.     Christian Schaefer    - For spending time on this code with his
  125.                   Borland C++ 4.5 compiler
  126.     Jacco van Weert &
  127.     Frans Slothouber    - For the 'Robodoc' utility
  128.  
  129. TextEngine/--compiling--                             TextEngine/--compiling--
  130.  
  131.    NAME
  132.     compiling -- Specials for compiling the textengine.
  133.  
  134.    COMPILING
  135.     - You could compile this code as normal C or as C++
  136.  
  137. TextEngine/--history--                                 TextEngine/--history--
  138.  
  139.    NAME
  140.     history -- TextEngine is a module to help with text features
  141.  
  142.    VERSION
  143.     $VER: TextEngine 33.071 (28.07.95)
  144.  
  145.    HISTORY
  146.     22.02.1994 -    DateString() initiated.
  147.     23.02.1994 -    Continuation of DateString(), making FormatStr() and
  148.             copying max from old Datum.mod
  149.             TimeString() Initiated.
  150.     24.02.1994 -    Inserting %w command in DateString()
  151.     04.03.1994 -    Starting translation into C
  152.     21.01.1995 -    Continuation of translation to C,
  153.             using new date library functions.
  154.             Internal procedures: FormatStr(), strdel(),
  155.             strinspos()
  156.             TimeString() completly rewritten.
  157.     04.02.1995 -    TimeString() completly rewritten.
  158.             Bug fixes in strinspos().
  159.     05.02.1995 -    DateString() completly rewritten.
  160.             Eliminating FormatStr(), because there is no need for
  161.             it, at the moment.
  162.             TextEngine(), TextEngineJD() initiated.
  163.     06.02.1995 -    Small changes in the autodocs
  164.     16.02.1995 -    Fixing bugs found with C++
  165.             Adding C++ overloading to TextEngine() &
  166.             TextEngineJD()
  167.     24.02.1995 -    Rita Reichl corrects my bad English - again.
  168.     16.03.1995 -    Corrections and changes in the autodocs.
  169.     22.03.1995 -    Introducing DiffDateString().
  170.             Changing interface!!!
  171.     02.04.1995 -    More C++ Support! Adding To-Do list.
  172.             Adding NOTES to autodocs. Fixing some things.
  173.             Introducing DiffTimeString(),StringString().
  174.     07.04.1995 -    Fixing two bugs.
  175.     17.04.1995 -    Integrating StringString()
  176.     22.04.1995 -    Rita Reichl corrects my bad English - again.
  177.     14.05.1995 -    New copyright notice!
  178.     16.05.1995 -    Fixing two small bugs.
  179.     19.05.1995 -    Rita corrects my English.
  180.     24.05.1995 -    Changing interface of TextEngine(), TextEngineJD(),
  181.             StringString()
  182.             Rewriting StringString() to support additional insert
  183.             strings.
  184.     25.05.1995 -    Writing test program
  185.     08.06.1995 -    Writing --compiling-- autodoc and some other small
  186.             fixes in the autodocs.
  187.     18.06.1995 -    Fixing C++ warnings/errors in textenginetest.c
  188.     18.07.1995 -    Replacing abs() with labs() to avoid problems!
  189.             Changing header from *strarr[] to **stararr
  190.     28.07.1995 -    Shortening the year of the version-string to 95,
  191.             because the Amiga 'version' command is buggy!
  192.  
  193. TextEngine/--todo--                                       TextEngine/--todo--
  194.  
  195.    NAME
  196.     todo -- This is the 'To-Do' list of the TextEngine module
  197.  
  198.    TODO
  199.     Find out about the Borland C++ 4.5 report about lines 140/150 in
  200.     textenginetest.c 'suspicious pointer conversion' / 'could not match
  201.     TextEngine()' :
  202.     void TextEngine(char *const string, double jd, const Languages lang,
  203.     double jd2, const char *const *const strarr);
  204.                 ----- (That's what the compiler does not like!)
  205.  
  206. TextEngine/TextEngine                                   TextEngine/TextEngine
  207.  
  208.    NAME
  209.     TextEngine -- Fills up %-commands (V33)
  210.  
  211.    SYNOPSIS
  212.     TextEngine(string,day,month,year,hour,min,sec,lang,day2,month2,
  213.         year2,hour2,min2,sec2,strarr);
  214.     TextEngine(string,jd,lang,jd2,strarr)
  215.  
  216.     void TextEngine(char *const string, const unsigned short day,
  217.         const unsigned short month, const int year = 0,
  218.         const unsigned short hour = 0, const unsigned short min = 0,
  219.         const unsigned short sec = 0, const Languages lang = English,
  220.         const unsigned short day2 = 0, const unsigned short month2 = 0,
  221.         const int year2 = 0, const unsigned short hour2 = 0,
  222.         const unsigned short min2 = 0, const unsigned short sec2 = 0,
  223.         const char *const *const strarr = NULL);
  224.  
  225.     void TextEngine(char *const string, double jd,
  226.         const Languages lang = English, double jd2 = 0.0.
  227.         const char *const *const strarr = NULL);
  228.  
  229.    FUNCTION
  230.     Finds and replaces % commands with real values.
  231.  
  232.    INPUTS
  233.     string  - String with % commands
  234.     day     - The day to fill in for % command
  235.     month   - The month to fill in for % command
  236.     year    - The year to fill in for % command, if this is 0 it will not
  237.           filled in!
  238.     hour    - The hour to use
  239.     min     - The minute to use
  240.     sec     - The sec to use
  241.     lang    - The language to use for texts
  242.     day2    - The diff. day
  243.     month2  - The diff. month
  244.     year2   - The diff. year, if you use 0, this will mean: use the same
  245.           as year!
  246.     hour2   - The diff. hour
  247.     min2    - The diff. minute
  248.     sec2    - The diff. second
  249.     strarr  - Stringarray with the strings to insert, terminated by NULL
  250.  
  251.    RESULT
  252.     string - String without % commands, but with real values
  253.  
  254.    EXAMPLE
  255.     ...
  256.     string = "Only a test!";
  257.     TextEngine(string,18,9,1970,14,44,0,English,22,3,1995,15,14,0,NULL);
  258.     ...
  259.  
  260.    SYNTAX
  261.     Syntax of % commands:
  262.       %%    : %
  263.       %+DTj : JD.JD  date+time
  264.       %+DTJ : MJD.JD date+time
  265.  
  266.       %D1[2][3]
  267.       1 : d : day
  268.           m : month
  269.           M : month text
  270.           y : year
  271.           w : weekday
  272.           W : week
  273.           s : scaliger year
  274.           j : JD
  275.           J : MJD
  276.       2 : v : variable length
  277.           f : fixed length
  278.           s : short text
  279.           l : long text
  280.       3 : 2 : short year
  281.           4 : full year
  282.  
  283.       %Ddv  - supported: d[d]
  284.       %Ddf  - supported: dd
  285.       %Dmv  - supported: m[m]
  286.       %Dmf  - supported: mm
  287.       %DMs  - supported: MMM
  288.       %DMl  - supported: M..M
  289.       %Dyv2 - supported: y[y]
  290.       %Dyv4 - supported: y[y[y[y]]]
  291.       %Dyf2 - supported: yy
  292.       %Dyf4 - supported: yyyy
  293.       %Dws  - supported: ww[w]
  294.       %Dwl  - supported: w..w
  295.       %DWv  - supported: W[W]
  296.       %DWf  - supported: WW
  297.       %Dsv  - supported: s[s[s[s]]]
  298.       %Dsf  - supported: ssss
  299.       %Dj   - supported: j..
  300.       %DJ   - supported: J..
  301.  
  302.       %T1[2]
  303.       T : time identifier
  304.       1 : h : hour 24h format
  305.           H : hour 12h format without "am/pm" text
  306.           M : "am/pm" text
  307.           m : minute
  308.           s : second
  309.           j : jd time
  310.       2 : v : variable length
  311.           f : fixed length
  312.  
  313.       %Thv - supported: h[h]
  314.       %Thf - supported: hh
  315.       %THv - supported: h[h]
  316.       %THf - supported: hh
  317.       %TM  - supported: am|pm
  318.       %Tmv - supported: m[m]
  319.       %Tmf - supported: mm
  320.       %Tsv - supported: s[s]
  321.       %Tsf - supported: ss
  322.       %Tj  - supported: j
  323.  
  324.       %AD1
  325.       1 : d : Difference from the given date to the actual date in days.
  326.           y : Difference from the given date to the actual date in years.
  327.  
  328.       %ADd - supported: d[d..]
  329.       %ADy - supported: y[y..]
  330.  
  331.       %AT1
  332.       1 : h : full hours
  333.           m : full minutes
  334.           s : full seconds
  335.           H : all in hours
  336.           M : all in minutes
  337.           S : all in seconds
  338.           j : as JD time difference
  339.  
  340.       %ATh - supported: h[h..]
  341.       %ATm - supported: m[m]
  342.       %ATs - supported: s[s]
  343.       %ATH - supported: h[h..][.h[h..]]
  344.       %ATM - supported: m[m..][.m[m..]]
  345.       %ATS - supported: s[s..]
  346.       %ATj - supported: j
  347.  
  348.       %S
  349.       S : string identifier
  350.  
  351.       %S - supported: s
  352.  
  353.    NOTES
  354.     If day2 and month2 are both 0 only year2-year will be calculated
  355.     for %ADy, don't use %ADd in this situation!
  356.     Think before using:
  357.       TextEngine(str,18,9,1970,0,0,0,English,18,9,1995,0,0,0) or
  358.       TextEngine(str,18,9,1995,0,0,0,English,18,9,1970,0,0,0)
  359.  
  360.    BUGS
  361.     Keep care that in string is enought space to expand it - if not
  362.     unknown effects may occur!
  363.  
  364.    SEE ALSO
  365.     DateString(), TimeString()
  366.  
  367. TextEngine/TextEngineJD                               TextEngine/TextEngineJD
  368.  
  369.    NAME
  370.     TextEngineJD -- Fills up %-commands (V33)
  371.  
  372.    SYNOPSIS
  373.     TextEngineJD(string,jd,lang,jd2,strarr);
  374.  
  375.     void TextEngineJD(char *const string, double jd,
  376.         const Languages lang = English, double jd2 = 0.0,
  377.         const char *const *const strarr);
  378.  
  379.    FUNCTION
  380.     Finds and replaces % commands with real values.
  381.  
  382.    INPUTS
  383.     string  - String with % commands.
  384.     jd      - The JD including time information.
  385.     lang    - The language to use for texts.
  386.     jd2     - The diff. JD.
  387.     strarr  - Stringarray with the strings to insert, terminated by NULL
  388.  
  389.    RESULT
  390.     string - String without % commands, but with real values.
  391.  
  392.    EXAMPLE
  393.     ...
  394.     string = "Only a test!";
  395.     TextEngineJD(string,2449754.630556,English,2449700,NULL);
  396.     ...
  397.  
  398.    SYNTAX
  399.     Syntax of % commands:
  400.       See TextEngine()
  401.  
  402.    NOTES
  403.     See TextEngine().
  404.  
  405.    BUGS
  406.     Unknown.
  407.  
  408.    SEE ALSO
  409.     TextEngine()
  410.  
  411.