C02/doc/include/string.txt

Common String Handling Functions for C02

Strings are zero-terminated arrays of type char with a maximum length
of 128 characters. 

The first character in a string is at position 0, and the last character 
is at position length minus 1.

Since all of the routines stop processing at the 128th character, a 128
character string does not require a zero terminator, and any character
array with length[128] will not overflow.

Due to the limitations of parameter passing in C02, the argument lists of
most of these functions do not match those in standard C and C++. 

For functions that operate on two string, one of the strings is specified 
using the setdst() function from module stddef. Unless otherwise noted,
none of the functions change dstptr.

Usage: at the beginning of the program use the directives

  #include <stddef.h02>
  #include <string.h02>
  
The following functions are defined:

  n = strlen(s);      Returns length of string.
  
                      Note: Sets srcptr to &s.
                                         
  n = strchr(c, s);   Searches string s for character c. 
                      
                      Returns position of first occurance of character 
                      in string, or 255 if character was not found.
                      
                      Note: Sets srcptr to &s.
                      
  n = strrch(c, s);   Returns position of last occurance of character 
                      in string, or 255 if character was not found.
                      
                      Note: Sets srcptr to &s.
                      
  n = strcat(s);      Concatenates source string s onto the end of
                      destination string set by prior setdst() call.
                       
                      Returns total length of concatenated string.

                      Note: Sets srcptr to &s.
                  
  c = strcmp(s);      Compares source string s against destination 
                      string set by prior setdst() call.
                       
                      Returns 255 if destination < source, 0 if 
                      destination = source, and 1 if destination > source.

                      These results can be evaluated using the C02 
                      unary comparator ! or the test-operators :+ or :-.
                  
                      Note: Sets srcptr to &s.
                                    
  n = strcpy(s);      Copies wource string s into destination string set
                      by prior setdst() call, replacing previous contents.
                      
                      Returns number of characters copied.
                      
                      To copy the first n characters from string s to
                      string d, the following code can be used: 
                      
                      setdst(&d); strcpy(s); s[n]=0;

                      Note: Sets srcptr to &s.

  n = strstr(s);      Searches for string s in destination string set.
                      
                      Returns position of source string in destination
                      string, or 255 if character was not found.
                      
                      Note: calls strcmp(), leaving srcptr pointing to
                      the matched string in the destination string 
                      (or the end if not found).

These functions are not part of the standard C and C++ string libraries. 
They are included because they are more efficient than equivalent C02 code.

  strcpb(s)           Copies string s to the system buffer (sysbfr).
  
                      Note: sets srcptr to &s and dstptr to &sysbfr,
                      then calls strcpy().
                      
  n = strcut(n, s);   Copies from source string s, starting at position n,
                      into destination string set by prior setdst() call, 
                      replacing previous contents.
                      
                      Returns number of characters copied.

                      To copy a substring starting at position n with 
                      length i from string s to string d, the following
                      code can be used:
                      
                      setdst(&d); strcut(s, n); s[i] = 0;
                      
                      Note: Sets srcptr to the address of position n 
                      in s and calls strcpy().

Note: This library expects the following functions to be defined

  setdst(s);         Set destination pointer
  setsrc(s);         Set source pointer and initialize index

along with the zero page variable pairs
  
  srcptr              Source String Pointer 
  dstptr              Destination String Pointer

as well as the transient variables 

  temp0               Temporary storage
  temp1