Pascal String Package documentation                  85/10/18 C.B. Falconer
===================================

For the benefit of those who require a set of string operations with the
PASCALP system, here is one.  It is almost entirely written in STANDARD Pascal,
with the exception of the use of the "scanfor" standard procedure, and this
can easily be replaced by a Pascal procedure, at the cost of efficiency.

For the procedures/functions available, scan the STRINGS.INC file for the words
PROCEDURE or FUNCTION, or see below.  The usage should be obvious.  TESTER.PAS
file exercises each operation, and should further show usage.

Note that the input sequences (used in readstring, and in the TESTER module)
assume that the file system follows the ISO and ANSI standards (as originally
specified in Jensen & Wirth).  If you are using a system with non-standard
protocols (e.g. interactive files on UCSD) these areas must to be modified.

Strings "cleaned" by STRINGCLEAN can be compared directly, as in "IF s1 < s2"
and will collate in the ASCII character sequence.  Use of STRINGUPSHIFT can
eliminate character case differences.

The following is the slightly edited (blank lines have been added) output of
REFRENCE on the mini-file consisting of the first and last lines below.

Procedural Cross-Referencer - Version Y-01-02
=============================================

 Line   Program/procedure/function heading
-------------------------------------------

    0   PROGRAM temp(input,output); (*$i'strings.inc'*)

    9     PROCEDURE readstring(VAR f : text; VAR s : string)
   10     (* At exit, eoln(f) is true, and no readln(f) has been called *);

   27     PROCEDURE readlnstring(VAR f : text; VAR s : string)
   28     (* differs from readstring in that at exit readln has been called *);

   36     FUNCTION length(VAR s : string) : xstrindex;

   46     PROCEDURE writestring(VAR f : text; VAR s : string);

   57     PROCEDURE wrtfldstring(VAR f : text; VAR s : string; field : integer)
   58     (* Analog to the normal Pascal write(f, x : field). Rt. justifies *);

   73     PROCEDURE concat(s1, s2 : string; VAR sdest : string)
   74     (* Arguments may be the same string, correctly handled *);

   89     PROCEDURE stringdeblank(VAR s : string)
   90     (* remove trailing blanks, if any *);

  105     PROCEDURE stringextend(VAR s : string; ch : char; always : boolean)
  106     (* always false prevents extension if the terminal *)
  107     (* char is ch, or if the string is null (length=0) *);

  125     PROCEDURE substring(si : string; index : strindex; len : integer;
  126                         VAR sdest : string)
  127     (* if index outside of si, then return the null string *)
  128     (* if index + len > length of si, then truncate len    *);

  146     PROCEDURE stringclean(VAR s : string)
  147     (* This standardizes the portion beyond the eos marker. *);

  166     FUNCTION stringfind(VAR s, searchee : string; start : strindex)
  167                          : xstrindex
  168     (* returns the index in searchee (from start up) where    *)
  169     (* the substring s may be found.  Returns 0 if not found. *);

  202     PROCEDURE stringupshift(VAR s : string);

  218     FUNCTION stoi(VAR s : string; start : strindex;
  219                   VAR value : integer) : xstrindex
  220     (* returns 0 for no valid number, else index past number *);

  241     PROCEDURE itos(i : integer; VAR s : string)
  242     (* Creates a string with the left justified representation of i *);

  271     BEGIN END.