UTIL.A Documentation
Holger Weets

Last Change:  03.04.92

This library was written under and for SOZOBON-C, and is Shareware.  It
can be freely copied with this documentation, but people should send
DM20 if they use the functions in the library.

Updates: 

      - The GEM_name() function should now work without errors.
      - The get_key() function now waits until a key is pressed.
      - The get_key(), xinkey(), sinkey(), chrdel() and strdel() functions
        are now implemented in assembler.
      - The input() function is now described in the documentation.
      - The exinkey(), dtostr(), and strtod() functions have been revised.
 
Function Descriptions:

   void chrdel(char *string, int pos) 

      This function will allow you to easily delete a character from a
      string.

      string -- The string that is to be deleted.
      pos    -- Index of the character to start deleting at.
 
   void chrins(char *string, int pos, char c) 
      
      This function allows you to easily insert a character into a string.
 
      string -- The string to insert the character into.
      pos    -- The position in the string at which to insert the character.
      c      -- The character to insert.
 
   void strins(char *src, char *string_to_insert) 

      This function allows a string to be inserted into another string.  To
      set the position at which the string should be inserted, use the
      following method:

         strins(string + offset, string_to_insert); 

      src              -- The string to insert the string into.
      string_to_insert -- The string to insert (obviously).
 
   void strdel(char *str, int number)

      This function will allow you to easily truncate a string.  To determine
      what position the string should be truncated at, use the following
      method:

         strdel(string + offset, number) 

      str    -- The string from which the characters should be deleted.
      number -- The number of characters that should be deleted.
 
   void get_key(char *c, int *scan) 

      This function waits until a key is pressed, and then returns the ASCII
      value of the key and the scancode.

      c    -- ASCII-Code of the character.
      scan -- The modified scancode of the character.
 
   void inkey(char *c, int *scan) 

      This function waits for a keypress and returns the ASCII value and the
      scancode of the key pressed.
 
   char ainkey() 

      This function, if a keypress is available, will return the ASCII value
      of the key pressed.  If no keypress is available, 0 is returned.

   int sinkey()
      
      This function, if a keypress is available, will return the scancode of
      the key pressed.  If not keypress is available, 0 is returned.
 
   int xinkey()

      This function, if a keypress is available, will return an integer
      from the keyboard buffer containing the scancode of the key pressed
      (bits 0-7) and the status of the control keys (bits 9-15).  This
      function CAN tell the difference between the left shift key and
      the right shift key.  If no keypress is available, 0 is returned.
 
   int exinkey() 
      This function, if a keypress is available, will return an integer from
      the keyboard buffer containing the scancode of the ke pressed (bits 0-7)
      and the status of the control keys (bits 9-15).  Unlike the xinkey()
      function described above, this function makes no distinction between
      the left shift key and the right shift key.

   int input(int number, char *set, char *buf, int flag) 

      This function is a convenient single line editor.

      number -- This is the size of the string to input (maximum=80).
         set -- The set of characters which are allowed (template).  If
                the template is empty, all characters are allowed.
         buf -- The default string shown on the edit line.
        flag -- Can input be aborted?

      If this function is exited by pressing RETURN/ENTER, 0 is returned.

      <<untranslatable information about the "flag" variable>>

      The following keys are supported:

      - LEFT/RIGHT ARROW
      - BACKSPACE 
      - DELETE 
      - ESC (erases the input line) 
 
   unsigned int strtod(char *str) 

      This function will convert a date string to the date in DOS format.
      The string must have the following format (though the periods can
      be replaced with slashes or any other single character):

      DD.MM.YYYY 

      str  -- The string containing the date.
 
      unsigned int strtot(char *str) 

      This function will convert a time string to the time in DOS format.
      The string must have the following format (though the colons can be
      replaced by any single character):

      HH:MM

      str -- The string containing the time.
 
   void ttostr(char *str, unsigned int systime, char *delim) 

      This function will convert the system time (DOS format) to a string
      of the following format (hyphenated by the character in the "delim"
      parameter):

      HH<hyphenation>MM

      systime -- The system time in DOS format.
      str     -- The destination string.
      delim   -- The hyphenation to be used in the new string.
 
      Example: "01:13" 
 
 
   void dtostr(char *str, unsigned int sysdate, char *delim) 

      This function will convert the system date (DOS format) to a string of
      the following format (hyphenated by the character in the "delim"
      parameter):

      DD<hyphenation>MM<hyphenation>YYYY

      sysdate -- The system date in DOS format.
      str     -- The destination string.
      delim   -- The hyphenation to be used in the new string.
 
      Example: "01.04.1990" 

   unsigned long drv_free(int drive) 

      This function checks the free space of the specified disk drive.

      drive -- The index of the disk drive to check the free space of.
 
   void zerlege(char *name, char *path) 

      <<untranslatable function description>>

   int copy(char *src, char *dest) 
 
      This function will copy the file "src" to a destination file "dst".

      src  -- Full name of the source file.
      dest -- Full name of the destiantion file.
 
      Example: copy("A:\Test.C", "C:\")         /*  INVALID!              */
               copy("A:\Test.C", "C:\Test.D")   /*  This is fine, even    */
                                                /*  though the names are  */ 
                                                /*  different.            */

      This function returns 0, or a GEMDOS error number.

      This function is fast because it allocates memory; the most memory it
      will use is the total ammount of free memory, minus eight kilobytes.

   void chsuf(char *dest, char *src, char *EXT) 

      This function changes the extension of a file, and copies the new name
      of the file into the "dest" parameter.

      dest -- The string that will contain the new name.
      src  -- The name of the file to change the extension of.
      EXT  -- The new extension.
 
      Example: chsuf(new, "A:\TEST.C", "PRG")  /*  Writes A:\TEST.PRG in  */
                                               /*  <new>.                 */ 
 
   void GEM_name(char *dest, char *src, int flag) 

      This function will convert a TOS-Format string ("TEST.C") to a
      GEM-Format string, shown below:

      If the output string is meant to be used in a text field (flag != 0)
      this function will generate "TEST    C".  If the output is meant to
      be used in a directory window (flag == 0), this function will generate
      "TEST     C".  In either case, the result is written to the "dest"
      parameter.
 
   void TOS_name(char *dest, char *src) 

      This function is the opposite of the GEM_name() function.  It will
      convert a GEM-Format string to a TOS-Format string, and write the
      resulting string to the "dest" parameter.

      Example:  "TEST    C" --> "TEST.C"

   int wild(char *test, char *pattern) 

      This function implements a complex pattern matching algorithm, much
      like UNIX regular expressions.  The following wildcards are allowed:

      *    - Skip any sequence of characters, including "." (unlike TOS).
      ?    - Skip any one character, including "." (unlike TOS).
      []   - Allow any one character matching the expression within brackets.
      !    - Disallow any one character, or disallow any one expression
             within square brackets.
      \    - Treat one of the above special characters as a character
             instead of an operator.
      \nnn - Octal Character Value (033=ESCAPE)

      Example: Fr*d                     = Fred, Fraud, Fried
               Jo?n                     = John, Join
               L[ai]p                   = Lip, Lap (but NOT Lop)
               L[!ai]p                  = Lop (but NOT Lip or Lap)
               Fr\*d                    = Fr*d
               This \[is\] bracketed\!  = This [is] bracketed!

   char *xfgets(char *buffer, int len, File *file)
      <<untranslatable>>

