{ File: [22,320]STRING.PKG Last edit: 6-APR-1989 14:30:03 PASCAL-3 STRING PACKAGE Version: V3.2 Author: Jim Bostwick 26-Aug-83 History: Converted to Package from OMSI Sources. Bug Fixes to original source: JMB 3-Jul-83 to correct INSERT procedure. JMB 4-Jul-83 to correct SUBSTRING procedure. 19-Oct-83 Added SSubstr. 21-Nov-83 JMB convert fill char to blank vs null 18-Mar-84 JMB -- add routine SVAssign 14-Mar-88 PTH -- add SAdr, SSend and SRecv routines Note: The original string routines supplied by Oregon Software was a simple Pascal source file STRING.PAS, to be included in user tasks. The Package version implements different procedure names, and comprises external procedures in several object modules. } {*PACKAGE* The String package implements various character string manipulation routines for Pascal-3 programs. It will handle any character array or string constant (see "STRING TYPES" below), interchangably. In addition, a procedure is included for assigning a single character to a string. Since these procedures all use conformant array parameters, they can handle strings of any reasonable size without modification. This package was modeled after STRING.PAS supplied by OMSI. .hl 2 STRING TYPES The String package accepts two types of string, as well as string constants where circumstances permit. The external routines will accept strings of any length, and different length strings may be freely intermixed in the same call. However, from the standpoint of the main program, each string variable must be declared with a fixed size. Of course, the main program may declare any number of different sized string variables. Type "0" strings are declared with type declarations of the form "packed array [0..n] of char", where n >= 1. The length of the string is stored in element 0, elements 1 to n are the characters of the string. Note that element 0 specifies the 'length in use' -- the actual variable remains fixed at the size declared at compile time. Because it includes a 'length used' value, this type "0" string is the only type which allows the user to manipulate 'variable' length strings. The maximum length of a type "0" string is 255., since the string length is stored in a byte. The size of this maximum string would then be ([0..255]) 256. bytes. Type "1" strings are declared as "packed array [1..n] of char", in which case "n" is considered to be the length of the string. In particular, quoted strings in Pascal are considered to be of this type, and may be intermixed with string variables when used as value parameters (quoted strings will obviously not work with "VAR" parameters). The length of a type 1 string is the upper bound of the array (n) or the position just before the first occuring null character (chr(0)) in the array (ie. ASCIZ string), whichever is smaller. Although the OMSI string package would not allow type "1" strings in VAR parameters, this restriction has been removed at the Grain Lab. In particular, the string package may be used to manipulate the standard CHx data types. Type "1" strings are truncated during string assignment to the length of the output string, or padded with nulls as required. The package will also accept string constants as value parameters. These appear to the package as type "1" strings. In particular, one may now do the following: .nf p := SPos(str,'Hi'); SAssign(str,'Hello!'); < set str equal to "Hello!"> .f .hl 2 Character operations Although one may define single-character arrays (packed array [1..1] of char), several procedures are provided which accept parameters of type char. In addition, one may often simply manipulate a string element directly. .hl 2 General rules All string package calls begin with a capital "S". The procedure names are frequently more than 6 characters in length, but are unique to the first 6 characters. The external code is contained in several small object modules. .hl 2 Search versus Pos Procedures Both Search and Pos procedures are included. Search procedures accept a starting point, and return this value if if the target is not found. This is useful for parsing. Pos functions take no start parameter (the first element of the string is used), and return zero if the target is not found. The capabilities provided are: SClear(S) - initializes string S to empty. For Type "0" strings, this simply sets ORD(S[0])=0, with the remainder of the string undefined. For Type "1" strings, the string is filled with blanks. SRead(F,S) - reads a value for string S from the text file F. The string is terminated by Eoln(F) and a Readln(F) is performed. String overflow (input data contains more characters than the target array can hold) results in truncation. For Type "1" strings, input underflow results in padding with blanks. SWrite(F,S) - writes the string S to the text file F. SConcat(T,S) - appends string S to the target string T. The resulting value is string T. Overflow results in truncation to StringMax characters. SSearch(S,T,Start) - searches string S for the first occurrence of string T to the right of position Start (characters are numbered beginning with one). The function Search() returns the position of the first character in the matching substring, or the value zero if the string T does not appear. SInsert(T,S,Start) - inserts the string S into the target string T at position Start. Characters are shifted to the right as necessary. Overflow produces a truncated target string; a Start position which would produce a string which was not contiguous has no effect. SAssign(T,S) - Assign string S to the target string T. Especially useful for assigning a literal string to a variable string. SVAssign(T,S) - Assign string S to target string T. Identical to SAssign, except both S and T are VAR parameters. This allows a procedure to call SVAssign, passing one of it's own value parameters on in "S", something you can't do with SAssign. SVAssign cannot be used with quoted strings or other string constants, however. SChAssign(T,C) - Assign character C to the target string T. Especially useful for assigning a single character to a variable string. SEqual(T,S) - Function Equal returns TRUE when T=S, returns FALSE otherwise. The Start and Span parameters in the following procedures define a substring beginning at position Start (between characters Start-1 and Start) with a length of Abs(Span). If Span is positive, the substring is to the right of Start; if negative, the substring is to the left. SDelete(S,Start,Span) - deletes the substring defined by Start, Span from the string S. SSubstr(T,S,Start,Span) - the substring of string S defined by Start, Span is assigned to the target string T. SSearch(S,T,Start) - searches target string T for substring S and returns 0 if no match or first position that substring occurs in target string. Strunc(S) - replaces trailing blanks of string S with nulls. Spad(S,Chzap,Chpad) - takes string S and replaces Chzap characters with Chpad characters. Schconcat(S,C) - concatenates character C to string S. Supper(S) - converts string S to all upper case. Snice(s) - converts first character of string S to upper case and following characters to lower case. } { The following 'includes' provide external definitions for the string package modules. Note that only those modules actually called from the user program will be loaded in the task image. Thus, it does no harm (aside from slightly longer compile time) to always define all of the externals. } %Include 'PAS$EXT:SADR.EXT'; %Include 'PAS$EXT:SASSIGN.EXT'; %Include 'PAS$EXT:SCHASSIGN.EXT'; %Include 'PAS$EXT:SCLEAR.EXT'; %Include 'PAS$EXT:SCONCAT.EXT'; %Include 'PAS$EXT:SDELETE.EXT'; %Include 'PAS$EXT:SEQUAL.EXT'; %Include 'PAS$EXT:SINSERT.EXT'; %Include 'PAS$EXT:SLEN.EXT'; %Include 'PAS$EXT:SREAD.EXT'; %Include 'PAS$EXT:SRECV.EXT'; %Include 'PAS$EXT:SSEND.EXT'; %Include 'PAS$EXT:SWRITE.EXT'; %Include 'PAS$EXT:SSUBSTR.EXT'; %Include 'PAS$EXT:SVASSIGN.EXT'; %Include 'PAS$EXT:SSEARCH.EXT'; %Include 'PAS$EXT:STRUNC.EXT'; %Include 'PAS$EXT:SPAD.EXT'; %Include 'PAS$EXT:SCHCONCAT.EXT'; %Include 'PAS$EXT:SUPPER.EXT'; {SNICE source cannot be found - will have to redone some day. See PASCAL DISTRIBUTION WORKDISK [22,310]HELP.HLP for more details. %Include 'PAS$EXT:SNICE.EXT';}