ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

home *** CD-ROM | disk | FTP | other *** search

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / PROG / PASCAL / STRG57.ZIP / STRGREF.DOC < prev next >

Wrap

Text File | 1991-01-23 | 88.1 KB | 1,961 lines

STRG UTILITIES REFERENCE GUIDE Version 5.7 January 23, 1991 Copyright (C) 1989-1991 Eagle Performance Software All Rights Reserved. _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER STRG Utilities Reference Guide, Version 5.7 T A B L E O F C O N T E N T S 1. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . 4 Purpose . . . . . . . . . . . . . . . . . . . . . . . 4 Parameters . . . . . . . . . . . . . . . . . . . . . 4 Code Size . . . . . . . . . . . . . . . . . . . . . . 5 Speed . . . . . . . . . . . . . . . . . . . . . . . . 5 2. PROCEDURES AND FUNCTIONS . . . . . . . . . . . . . . . 6 AscStr . . . . . . . . . . . . . . . . . . . . . . . 6 ChrDel* . . . . . . . . . . . . . . . . . . . . . . . 6 ChrFill . . . . . . . . . . . . . . . . . . . . . . . 7 ChrPad* . . . . . . . . . . . . . . . . . . . . . . . 7 ChrPos* . . . . . . . . . . . . . . . . . . . . . . . 7 ChrQty* . . . . . . . . . . . . . . . . . . . . . . . 8 ChrRepl* . . . . . . . . . . . . . . . . . . . . . . 8 Copy . . . . . . . . . . . . . . . . . . . . . . . . 9 Delete . . . . . . . . . . . . . . . . . . . . . . . 9 Is* . . . . . . . . . . . . . . . . . . . . . . . . . 9 LnStr . . . . . . . . . . . . . . . . . . . . . . . . 10 LoCase . . . . . . . . . . . . . . . . . . . . . . . 11 Pos . . . . . . . . . . . . . . . . . . . . . . . . . 11 StrAsc . . . . . . . . . . . . . . . . . . . . . . . 11 StrLn . . . . . . . . . . . . . . . . . . . . . . . . 12 Str* . . . . . . . . . . . . . . . . . . . . . . . . 12 StrBin . . . . . . . . . . . . . . . . . . . . . . . 13 StrBrk . . . . . . . . . . . . . . . . . . . . . . . 13 StrCat* . . . . . . . . . . . . . . . . . . . . . . . 13 StrCmp* . . . . . . . . . . . . . . . . . . . . . . . 14 StrCopy . . . . . . . . . . . . . . . . . . . . . . . 14 StrCut . . . . . . . . . . . . . . . . . . . . . . . 15 StrDeTab . . . . . . . . . . . . . . . . . . . . . . 15 StrEnum . . . . . . . . . . . . . . . . . . . . . . . 15 StrFill . . . . . . . . . . . . . . . . . . . . . . . 15 StrHex . . . . . . . . . . . . . . . . . . . . . . . 16 StrIns . . . . . . . . . . . . . . . . . . . . . . . 16 StrJ* . . . . . . . . . . . . . . . . . . . . . . . . 17 StrLwr . . . . . . . . . . . . . . . . . . . . . . . 17 StrMemb . . . . . . . . . . . . . . . . . . . . . . . 17 StrMove . . . . . . . . . . . . . . . . . . . . . . . 18 StrOvr . . . . . . . . . . . . . . . . . . . . . . . 18 StrPeek . . . . . . . . . . . . . . . . . . . . . . . 18 StrPoke . . . . . . . . . . . . . . . . . . . . . . . 19 StrPos* . . . . . . . . . . . . . . . . . . . . . . . 19 StrQty* . . . . . . . . . . . . . . . . . . . . . . . 19 StrRepl* . . . . . . . . . . . . . . . . . . . . . . 20 StrReTab . . . . . . . . . . . . . . . . . . . . . . 21 StrRev . . . . . . . . . . . . . . . . . . . . . . . 21 StrRoll . . . . . . . . . . . . . . . . . . . . . . . 21 StrSort . . . . . . . . . . . . . . . . . . . . . . . 21 StrSpn . . . . . . . . . . . . . . . . . . . . . . . 22 StrUpr . . . . . . . . . . . . . . . . . . . . . . . 22 UpCase . . . . . . . . . . . . . . . . . . . . . . . 23 2 STRG Utilities Reference Guide, Version 5.7 ValBin . . . . . . . . . . . . . . . . . . . . . . . 23 ValHex . . . . . . . . . . . . . . . . . . . . . . . 23 Wrd* . . . . . . . . . . . . . . . . . . . . . . . . 24 WrdParse . . . . . . . . . . . . . . . . . . . . . . 24 WrdPos* . . . . . . . . . . . . . . . . . . . . . . . 25 WrdQty . . . . . . . . . . . . . . . . . . . . . . . 26 WrdToken . . . . . . . . . . . . . . . . . . . . . . 26 3. VARIABLES . . . . . . . . . . . . . . . . . . . . . . . 28 Global . . . . . . . . . . . . . . . . . . . . . . . 28 Local . . . . . . . . . . . . . . . . . . . . . . . . 29 4. ACCESSIBLE MEMORY . . . . . . . . . . . . . . . . . . . 30 5. QUICK REFERENCE . . . . . . . . . . . . . . . . . . . . 31 3 STRG Utilities Reference Guide, Version 5.7 1. I N T R O D U C T I O N PURPOSE This document is a STRG technical reference manual describing each routine and variable in detail in a format similar to the Borland manual. The routines are described in alphabetical order. Since this manual is on disk, you can find your interest easily with a search utility. Application - All STRG procedures process strings with high-speed optimized assembly code. To be as fast as possible, almost all routines are procedures rather than functions to increase speed 2 to 3 times. PARAMETERS Common Parameters - Most procedures use the same parameters. Rather than repeating them for each routine, detailed descriptions for those parameters are listed below. Count - number of characters or substrings to copy. Decimals - number of digits to the right of the decimal. Dest - Pascal destination string (as opposed to source). Field - number of digits in the field. Find - a character or substring to find in a source string. Index - the starting offset in the Pascal source string. MaxLen - the maximum length permitted for the resulting string to prevent overwriting memory. Nth - process until the "Nth" occurrence. Repl - replacement character or substring. S - Pascal source string. Source - Pascal source string (as opposed to destination). Order of Parameters - Of course not all of these parameters may be used, but the order of the parameters is consistent throughout the routines. Here is the general order: 1. Destination - such as Dest 2. Source - such as S and Source 3. Substrings - such as Find, Repl, Fill, First, and Last 4. Index - always of the source 5. Count - such as Count, Field, Nth and Qty 6. Maximum - maximum length of destination string This arrangement matches that of C. For procedures, if there is a destination, it is always the first parameter; just like the assignment, (":=") the destination is always on the left. Index - All index parameters are 1-based. If a zero is entered, it is converted to 1. The Delete procedure is the only exception to this, but it is part of standard Pascal. Chapter 1, Introduction Page 4 STRG Utilities Reference Guide, Version 5.7 CODE SIZE Unit Size - If you use a STRG procedure, only the corresponding object file containing that procedure will be linked and thereby optimizing the code. | Even if all 111 procedures are used, STRG is still quite small at a total | of about 6.3k bytes. In all, there are 78 object files used to create the | unit which is about 5900 lines of assembly or 250k of code. Code Usage - This Shareware unit has been released with the $N+ and $E+ compiler directives set. This means that an additional 12k of code is included for the IEEE reals library inserted by the compiler. The IEEE reals are used in the Str* numeric formatting functions and are enabled for your testing. Should you not want to use these functions and are a registered user, you can turn off these directives at the beginning of the STRG unit. This will drop the IEEE library from the executable code. SPEED Speed Bench - How fast is fast? To have a basis for comparison, a unit of strings-per-second (str/sec) is used for a relative measure of speed. To get this rating, a routine is repeated with a FOR loop to operate on a given string and any "reset" of the original string is subtracted out as overhead. The RATE57.PAS program can duplicate this for you so you can bench test your own routines for actual speed. Overall, if you use STRG for your application, your speeds will easily be 3 times faster or more. Relative Speed - The ratings mentioned in the Reference Manual are speeds obtained from actual bench test on an 80386 / 20 MHz machine. Granted, that this may be faster than most units, but the important aspect of these ratings is relative speed. By comparing ratings with other routines in this unit, you can judge how to best assemble a program technique that can suit your needs. Processing Rating - Not only can machines vary in speed, but the string values in your program are complete variables. When given a routine like StrPosL, the test performed is on an 80-character string with a 5-letter word at the end of the string. So the test forces the routine to search the entire string. This provides a worst case scenario to give you a feel for the length of time for an operation. Similarly, StrPosR is tested with the 5-letter word at the beginning of the string and so the ratings for both routines are about the same. But one of these routines may be much better for your program from a strategic standpoint. So, the rating provided gives one of processing performance and not from the perspective that a better rating means faster speed for your application. Chapter 1, Introduction Page 5 STRG Utilities Reference Guide, Version 5.7 2. P R O C E D U R E S A N D F U N C T I O N S In this section, a detailed description is provided for each procedure and function. --------------------------------------------------------------------------- AscStr procedure Strg --------------------------------------------------------------------------- Function Creates ASCIIZ strings from Pascal-type strings. Declaration AscStr (VAR AscDest; S: string) Remarks After AscStr is executed, the global variable AscDestPtr is updated to point to the next destination address just after the null. Source and destination can be the same. As in all move-type procedures, it is important to make sure the destination size is sufficient to fit the source. Rating 42,900 str/sec See also LnStr, StrAsc and the variable AscDestPtr. Example Pack three Pascal strings into an array of ASCIIZ strings. uses strg; var S: array[0..4] of string; A: array[0..26] of char; i: byte; begin S[1] := 'Eagle'; S[2] := 'Performance'; S[3] := 'Software'; AscDestPtr := @A; for i:=1 to 3 do AscStr (AscDestPtr^,S[i]); end. The resulting array A would look like: 'Eagle'#00'Performance'#00'Software'#00 --------------------------------------------------------------------------- ChrDel* procedure Strg --------------------------------------------------------------------------- Function Operates on a string to delete a given character. Declaration ChrDel (VAR S: string; Find: char) ChrDelL (VAR S: string; Find: char) ChrDelR (VAR S: string; Find: char) Remarks ChrDel deletes all finds in the entire string. ChrDelL deletes only left (or leading) finds. ChrDelR deletes only right (or trailing) finds. Rating ChrDel: 9,400 str/sec ChrDelL: 39,000 str/sec ChrDelR: 132,000 str/sec See also StrCut Example Try these examples: Chapter 2, Procedures and Functions Page 6 STRG Utilities Reference Guide, Version 5.7 MyString := ' more info '; MyNumStr := '1,234,567'; ChrDel (MyNumStr,','); { MyNumStr='1234567' } ChrDelL (MyString,' '); { MyString='more info ' } ChrDelR (MyString,' '); { MyString=' more info' } --------------------------------------------------------------------------- ChrFill procedure Strg --------------------------------------------------------------------------- Function Fills a string with multiple copies of a character. Declaration ChrFill (VAR S: string; Fill: char; Count: byte) Remarks The fill overwrites S with Count number of repetitions of Fill and automatically sets the length byte. Be sure the destination is large enough. Up to twice as fast as using system.fillchar. Rating 53,400 str/sec See also StrEnum, StrFill Example Try the following example: ChrFill (S,'a',5); { S='aaaaa' } --------------------------------------------------------------------------- ChrPad* procedure Strg --------------------------------------------------------------------------- Function Pads a string on the left, right, or to center with a given character to fill a field. Declaration ChrPadC (VAR S: string; Fill: char; Field: byte) ChrPadL (VAR S: string; Fill: char; Field: byte) ChrPadR (VAR S: string; Fill: char; Field: byte) Remarks ChrPadC pads left and right to center the field. ChrPadL pads on the left (or leading) fill. ChrPadR pads on the right (or trailing) fill. Rating ChrPadC: 36,500 str/sec ChrPadL: 42,900 str/sec ChrPadR: 52,000 str/sec See also ChrDel, StrCut, StrJ* Example Try these examples: MyStr := 'abcdefgh'; { 12345678901 } ChrPadC (MyStr,'*',11); { MyStr='*abcdefgh**' } ChrPadL (MyStr,'=',11); { MyStr='===abcdefgh' } ChrPadR (MyStr,' ',11); { MyStr='abcdefgh ' } --------------------------------------------------------------------------- ChrPos* function Strg --------------------------------------------------------------------------- Function Finds the position of a given character with match/ignore case. Declaration ChrPosL (S: string; Find: char; Nth: byte) ChrPosLI (S: string; Find: char; Nth: byte) ChrPosR (S: string; Find: char; Nth: byte) ChrPosRI (S: string; Find: char; Nth: byte) ChrPosX (S: string; Find: char; indeX: byte) ChrPosXI (S: string; Find: char; indeX: byte) Chapter 2, Procedures and Functions Page 7 STRG Utilities Reference Guide, Version 5.7 Result type byte Remarks Using suffixes, -L routine searches from the left while the -R searches from the right for the Nth occurrence. The -X routine starts at the given index and searches right for the first occurrence. These routines match case, while those with the added -I suffix will Ignore case. Rating ChrPos?: 25,400 str/sec ChrPos?I: 22,500 str/sec (non-alphabetic Find) ChrPos?I: 10,200 str/sec (alphabetic Find) See also StrBrk, StrPos* Example Try the following examples: S1 := 'C:\MySubDir\SubDir#2\myfile'; S2 := 'Eagle Performance Software'; MyByte := ChrPosR (S1,'\',1); { MyByte=21 } MyByte := ChrPosLI (S2,'e',3); { MyByte= 8 } MyByte := ChrPosXI (S2,'s',8); { MyByte=19 } --------------------------------------------------------------------------- ChrQty* function Strg --------------------------------------------------------------------------- Function Counts the occurrences of a given character in a string with match/ignore case. Declaration ChrQty (S: string; Find: char) ChrQtyI (S: string; Find: char) Result type byte Remarks ChrQty matches case while ChrQtyI ignores case. Rating ChrQty: 23,100 str/sec ChrQtyI: 22,500 str/sec (non-alphabetic Find) ChrQtyI: 10,200 str/sec (alphabetic Find) See also StrQty*, WrdQty Example Given a string, S:='Eagle Performance Software', try the following examples: MyByte := ChrQty (S,'a'); { MyByte=3 } MyByte := ChrQtyI (S,'e'); { MyByte=5 } --------------------------------------------------------------------------- ChrRepl* procedure Strg --------------------------------------------------------------------------- Function Finds and replaces a character from a given index for Qty number of replacements with match/ignore case. Declaration ChrRepl (VAR S: string; Find,Repl: char; Index,Qty: byte) ChrReplI (VAR S: string; Find,Repl: char; Index,Qty: byte) Remarks The operation starts from Index and goes to the right. It will stop if the index is beyond the end of string or it has replaced as many as it can. ChrRepl matches case while ChrReplI ignores case. Rating ChrRepl: 21,300 str/sec ChrReplI: 20,300 str/sec (non-alphabetic Find) ChrReplI: 10,000 str/sec (alphabetic Find) See also ChrDel*, StrRepl* Example Try the following example: Chapter 2, Procedures and Functions Page 8 STRG Utilities Reference Guide, Version 5.7 S := '/s -12 -cga /off'; ChrRepl (S,'-','/',1,255); { S='/s /12 /cga /off' } --------------------------------------------------------------------------- Copy function Strg --------------------------------------------------------------------------- Function Returns a substring of a string. Declaration Copy (S: string; Index,Count: integer) Result type string Remarks Exact replacement of the System.Copy function, but automatically replaces it with one that is up to 34% faster. Rating 21,500 str/sec See also StrCopy, StrOvr, Compiler reference manual --------------------------------------------------------------------------- Delete procedure Strg --------------------------------------------------------------------------- Function Deletes a substring from a string. Declaration Delete (VAR S: string; Index,Count: integer) Remarks Exact replacement of the System.Delete procedure, but automatically replaces it with one that is up to 5 times faster. Rating 39,300 str/sec See also ChrDel*, StrCut, Compiler reference manual --------------------------------------------------------------------------- Is* function Strg --------------------------------------------------------------------------- Function Character classification function. Declaration IsAlNum (C: char) { Alpha-numeric } IsAlpha (C: char) { Upper and lower case letters } IsASCII (C: char) { Lower ASCII table } IsCntrl (C: char) { Print control characters } IsDigit (C: char) { 0 through 9 } IsDOS (C: char) { Valid DOS directory & wildcards } IsFile (C: char) { Valid DOS file name } IsGraph (C: char) { Black characters } IsLower (C: char) { Lower case letters } IsPath (C: char) { Valid DOS path & drive & subdirs } IsPrint (C: char) { Printable characters } IsPunct (C: char) { Punctuation marks } IsReal (C: char) { Real numbers } IsSigned (C: char) { Signed integers } IsSpace (C: char) { Space or line control } IsUpper (C: char) { Upper case letters } IsXDigit (C: char) { Hex digits } Result type boolean Remarks These exactly duplicate the C implementation of character classification, but a few are unique to STRG. The best balance of speed and code is used for each one and they are more efficient than the use of sets. All functions only consider characters in the lower ASCII table (<#128). The function will return TRUE if the following characters are passed (the "-" means through): Chapter 2, Procedures and Functions Page 9 STRG Utilities Reference Guide, Version 5.7 IsAlNum: 0-9 A-Z a-z IsAlpha: A-Z a-z IsASCII: Less than #128 IsCntrl: #00-#31 #127 IsDigit: 0-9 IsDOS: ! #-* #45 #46 0-: ?-Z \ ^-{ }-~ IsFile: ! #-) #45 #46 0-9 @-Z ^-{ }-~ IsGraph: #33-#126 IsLower: a-z IsPath: ! #-) #45 #46 0-: @-Z \ ^-{ }-~ IsPrint: #32-#126 IsPunct: IsGraph but not IsAlNum IsReal: 0-9 + Minus . e E IsSigned: 0-9 + Minus IsSpace: Space #09-#13 IsUpper: A-Z IsXDigit: 0-9 A-F a-f IsDos checks for characters that are valid when asking for a directory at the DOS command prompt such as: C:\MySubDir\Subdir#2\All?.* IsPath is the same as IsDos except it doesn't accept the wildcards '*' and '?'. IsFile is the the same as IsPath except it will not accept the drive and path characters ':' and '\'. See also StrMemb Example Create a membership string containing only valid Real number characters: S := ''; for MyChar:='+' to 'e' do if IsReal (MyChar) then StrCat (S,MyChar,255); { S='+-.1234567890Ee' } --------------------------------------------------------------------------- LnStr procedure Strg --------------------------------------------------------------------------- Function Creates ASCII TEXT strings from Pascal-type strings. Declaration LnStr (VAR LnDest; S: string) Remarks LnStr copies the characters of string S to the line destination Ln and terminates the line with a CR/LF (#13/#10). After StrLn is executed, the global variable LnDestPtr points to the next destination after the CR/LF. As in all move-type procedures, it is important to make sure the destination size is sufficient to fit the source. Suggestions The use of WriteLn for text files is disk intensive. LnStr can be used together with BlockWrite for extremely fast text file operations. Rating 42,200 str/sec See also AscStr, StrLn, and variable LnDestPtr Example Similar to the example in StrAsc. Chapter 2, Procedures and Functions Page 10 STRG Utilities Reference Guide, Version 5.7 --------------------------------------------------------------------------- LoCase function Strg --------------------------------------------------------------------------- Function Converts characters to lower case. Declaration LoCase (C: char) Result type char Remarks As the complement of UpCase, this routine converts characters in the range A..Z to lower case. See also ChrReplI, StrLwr, StrUpr, UpCase --------------------------------------------------------------------------- Pos function Strg --------------------------------------------------------------------------- Function Finds the position of a substring in a string. Declaration Pos (Find,S: string) Result type integer Remarks Exact replacement of the System.Pos procedure, but automatically replaces it with one that is up to 340% faster. Rating 24,100 str/sec See also ChrPos*, StrBrk, StrPos*, Compiler reference manual. --------------------------------------------------------------------------- StrAsc procedure Strg --------------------------------------------------------------------------- Function Creates Pascal strings from ASCIIZ-type strings. Declaration StrAsc (VAR Dest: string; VAR AscSrc; MaxLen: byte) Remarks After StrAsc is executed, the global variable AscSrcPtr points to the next ASCIIZ string skipping over any null character. Should the conversion be truncated with MaxLen, StrAsc makes sure that AscSrcPtr points to the next string and not a null. Source and destination can be the same. As in all move-type procedures, it is important to make sure the destination size is sufficient to fit the source. Rating 17,000 str/sec See also StrLn, AscStr Example Disassemble a sequential array of ASCIIZ strings into three Pascal strings: uses strg; const A: array[0..26] of char = 'Eagle'#00'Performance'#00'Software'#00; var S: array[0..4] of string; i: byte; begin AscSrcPtr := @A; for i:=1 to 3 do StrAsc (S[i],AscSrcPtr^,255); end. The resulting strings would look like: Chapter 2, Procedures and Functions Page 11 STRG Utilities Reference Guide, Version 5.7 S[1] := 'Eagle'; S[2] := 'Performance'; S[3] := 'Software'; --------------------------------------------------------------------------- StrLn procedure Strg --------------------------------------------------------------------------- Function Creates Pascal strings from ASCII TEXT strings. Declaration StrLn (VAR Dest: string; VAR LnSrc; MaxLen: byte) Remarks ASCII text file lines by definition end with a CR (#13) or a CR/LF (#13/#10). StrLn searches for the CR and copies the string prior to that character. After StrLn is executed, the global variable LnSrcPtr points to the next line skipping over any CR or LF even if the string is truncated with MaxLen. Source and destination can be the same for non-sequential conversions. As in all move-type procedures, it is important to make sure the destination size is sufficient to fit the source. Suggestions The use of ReadLn for text files is disk intensive. StrLn can be used together with BlockRead for extremely fast text file operations. Rating 16,800 str/sec See also AscStr, LnStr, and variable LnSrcPtr Example Similar to the example in AscStr. --------------------------------------------------------------------------- Str* function Strg --------------------------------------------------------------------------- Function Converts numbers to a string representation. Declaration StrC (C: comp): StrCF (C: comp; Field: integer) StrCFD (C: comp; Field,Decimals: integer) StrD (D: double) StrDF (D: double; Field: integer) StrDFD (D: double; Field,Decimals: integer) StrE (E: extended) StrEF (E: extended; Field: integer) StrEFD (E: extended; Field,Decimals: integer) StrL (L: longint) StrLF (L: longint; Field: integer) StrR (R: real) StrRF (R: real; Field: integer) StrRFD (R: real; Field,Decimals: integer) StrS (S: single) StrSF (S: single; Field: integer) StrSFD (S: single; Field,Decimals: integer) Result type string Remarks These functions use the System.Str procedure, but have been converted to a function form for convenience. Although they are a fraction slower, they save code in the long run. The IEEE reals are included only if the N/E compiler directives are appropriately set for your use. Rating Varies: uses System.Str. Chapter 2, Procedures and Functions Page 12 STRG Utilities Reference Guide, Version 5.7 See also StrBin, StrHex --------------------------------------------------------------------------- StrBin function Strg --------------------------------------------------------------------------- Function Converts numbers to binary strings. Declaration StrBin (Num: longint; Field: byte) Result type string Remarks If the field is larger than the resulting string, the field is balanced with leading zeros. If no leading zeros are desired, set Field to 0. Maximum field is 32. Rating 13,300 str/sec See also StrHex, ValBin, ValHex Example In the following examples, the results will be String1= '0000111111' and String2='111111'. MyByte := 63; String1 := StrBin (MyByte,10); String2 := StrBin (MyByte,3); --------------------------------------------------------------------------- StrBrk function Strg --------------------------------------------------------------------------- Function Finds first character that is a member of a group of chars. Declaration StrBrk (S,Breaks: string; Index: byte) Result type byte Remarks Breaks (Brk) is a group of characters. The function returns the index of the first character found to be a member of Breaks moving RIGHT from the given index. Routine has fully scanned when resulting index is zero. This routine is usually used to parse a string. For greater speed, place the most commonly used members early in Breaks. Rating 1-char Breaks: 23,700 str/sec 5-char Breaks: 5,400 str/sec See also ChrPos*, StrMemb, StrPosX, StrSpn Example Find the position of the number in the string S: var S,Numbers: string; Position: byte; begin S := 'Balance $24567.00'; StrEnum (Numbers,'0','9'); Position := StrBrk (S,Numbers,1); { Position=10 } end. --------------------------------------------------------------------------- StrCat* procedure Strg --------------------------------------------------------------------------- Function Appends one string or substring to the end of another. Declaration StrCat (VAR Dest: string; S: string; MaxLen: byte) StrCatX (VAR Dest: string; S: string; indeX,Count,MaxLen: byte) Remarks This procedure appends the end of string Dest with S for a Chapter 2, Procedures and Functions Page 13 STRG Utilities Reference Guide, Version 5.7 maximum length limit of MaxLen. StrCat concatenates a full string while StrCatX does a substring. This greatly speeds up concatenation. Usually the SizeOf function is used for MaxLen, or 255 can be used if there is no concern. Like Concat, but up to 5 times faster. Rating 44,100 str/sec See also StrCopy, StrMove, StrOvr Example Given S1='Eagle ' and S2='Performance', try the following: StrCatX (S1,S2,7,3,255); ( S1='Eagle man' } StrCut (S1,6); { S1='Eagle ' } StrCat (S1,S2,255); { S1='Eagle Performance' } --------------------------------------------------------------------------- StrCmp* function Strg --------------------------------------------------------------------------- Function Compares one substring to another. Declaration StrCmp (S1,S2: string; Index1,Index2,MaxLen: byte) StrCmpI (S1,S2: string; Index1,Index2,MaxLen: byte) Result type shortint Result value After comparison, here are the possible values: -1: S1<S2 0: S1=S2 +1: S1>S2 Remarks This routine compares (Cmp) two strings and determines Less Than, Equal, or Greater Than. The comparison is made between the resulting substrings starting at each corresponding index and moving to the right. The indexes are not adjusted should they extend beyond the end of string at which the substring is considered null. The indexes of difference are saved in the global variables CmpIndex1 and CmpIndex2 which are 0 if the two substrings are equal. StrCmp matches case while StrCmpI ignores case. Rating StrCmp: 27,800 str/sec StrCmpI: 4,600 str/sec Example The following comparison of dates yields -1, CmpIndex1=13 and CmpIndex2=19. S1 := 'MyEvent 90-04-23'; S2 := 'Second event: 90-05-17'; MyShortInt := StrCmp (S1,S2,9,15,8); --------------------------------------------------------------------------- StrCopy procedure Strg --------------------------------------------------------------------------- Function Directly copies a substring to create a new string. Declaration StrCopy (VAR Dest: string; S: string; Index,Count: byte) Remarks This is a move procedure for strings. Being a procedure rather than a function, it is up to 3.3 times faster than System.Copy. But be sure the Dest is large enough. Rating 47,000 str/sec See also Copy, StrCat, StrOvr Example The following example extracts the substring 'target'. Chapter 2, Procedures and Functions Page 14 STRG Utilities Reference Guide, Version 5.7 S1 := 'This is the target word'; StrCopy (S2,S1,13,6); { S2='target' } --------------------------------------------------------------------------- StrCut procedure Strg --------------------------------------------------------------------------- Function Truncates a string above a maximum size. Declaration StrCut (VAR S: string; MaxLen: byte) Rating 430,000 str/sec See also ChrDel* Example Try the following code: S := 'Eagle Performance Software'; StrCut (S,17); { S='Eagle Performance' } --------------------------------------------------------------------------- StrDeTab procedure Strg --------------------------------------------------------------------------- Function Expands all tabs to spaces at a given tab spacing. Declaration StrDeTab (VAR Dest: string; S: string; TabSpaces: byte) Remarks This routine expands all tabs to spaces given the tab spacing. Source and Dest can be the same address. Position 1 is the first tab setting. Be sure Dest can handle the expansion. Strings are truncated at 255. Rating 7,700 str/sec See also StrReTab Example Expand the tabs (#9) in the following string: S := #9'Col 9'#9'Col 17'; StrReTab (S,S,8); { S=' Col 9 Col 17' } { 1234567890123456789012 } --------------------------------------------------------------------------- StrEnum procedure Strg --------------------------------------------------------------------------- Function Enumerates a string of characters from First to Last. Declaration StrEnum (VAR S: string; First,Last: char) Remarks Enumeration can be increasing or decreasing, but do not wrap through #00. Be sure the destination is large enough. Strings are truncated at 255. Rating 13,300 str/sec See also StrFill, StrRev, StrSort Example Try the following examples: StrEnum (S,'a','f'); { S='abcdeg' } StrEnum (T,'f','a'); { T='fedcba' } --------------------------------------------------------------------------- StrFill procedure Strg --------------------------------------------------------------------------- Function Fills a string with multiple copies of a substring. Declaration StrFill (VAR S: string; Fill: string; Count,MaxLen: byte) Remarks The fill overwrites S with concatenated copies of Fill. A special option is built in for single character fills to be Chapter 2, Procedures and Functions Page 15 STRG Utilities Reference Guide, Version 5.7 extremely fast. Source and destination can be the same. Strings are truncated by MaxLen. Rating 1-char fill: 44,400 str/sec 5-char fill: 13,300 str/sec See also ChrFill, StrEnum Example Try the following examples: StrFill (S,'a',5,255); { S='aaaaa' } StrFill (T,'Fast',3,11); { T='FastFastFas' } --------------------------------------------------------------------------- StrHex procedure Strg --------------------------------------------------------------------------- Function Converts numbers to hex strings. Declaration StrHex (Num: longint; Field: byte) Remarks If the field is larger than the resulting string, the field is balanced with leading zeros. If no leading zeros are desired, set Field to 0. Maximum field is 8. No leading '$' character is inserted. Rating 25,100 str/sec See also StrBin, ValBin, ValHex Example Try the following examples: MyWord := 4095; String1 := StrHex (MyWord,5); { String1='00FFF' } String2 := StrHex (MyWord,1); { String2='FFF' } String3 := StrHex (MyWord,15); { String3='00000FFF' } --------------------------------------------------------------------------- StrIns procedure Strg --------------------------------------------------------------------------- Function Inserts a substring at a given index. Declaration StrIns (VAR Dest: string; S: string; DestIndex,MaxLen: byte) Remarks The routine is processed as if the insertion was done and the resulting string truncated after MaxLen. DestIndex is adjusted to the minimum of DestIndex and Dest[0]. The operation is skipped if MaxLen<DestIndex or S[0]=0. Up to 5 times faster than System.Insert. Rating 31,900 str/sec See also StrCat, StrCopy Example Try the following examples: S := 'Hello friends'; J := 'Jim'; Index := 7; { 123456789012345678 } StrIns (S,'my ',Index,255); { S='Hello my friends' } Since StrIns lets you control MaxLen, the following line of code: StrIns (S,J,Index,pred(Index)+length(J)); Is the same as the following two lines: Chapter 2, Procedures and Functions Page 16 STRG Utilities Reference Guide, Version 5.7 StrCut (S,pred(Index)); { 123456789 } StrCat (S,J,255); { S='Hello Jim' } --------------------------------------------------------------------------- StrJ* function Strg --------------------------------------------------------------------------- Function Left, center, or right justifies a string in a field of spaces. Declaration StrJC (S: string; Field: byte) { Justify center } StrJL (S: string; Field: byte) { Justify left } StrJR (S: string; Field: byte) { Justify right } Result type string Remarks If the field is smaller than the source string, the string is simply returned unaltered. These routines save from recopying the string in the stack making it faster. Rating 17,500 str/sec See also ChrPad*, StrOvr Example Try the following examples: S := StrJC ('test',7); { S=' test ' } S := StrJL ('test',7); { S='test ' } S := StrJR ('test',7); { S=' test' } --------------------------------------------------------------------------- StrLwr procedure Strg --------------------------------------------------------------------------- Function Converts strings to lower case. Declaration StrLwr (VAR S: string) Remarks The operation works on the entire string. Rating 8,900 str/sec See also ChrReplI, LoCase, StrUpr, UpCase --------------------------------------------------------------------------- StrMemb procedure Strg --------------------------------------------------------------------------- Function Reduces a string to its membership in ascending order. Declaration StrMemb (VAR Dest: string; S: string) Remarks Membership is the list of characters that occur in a string. Only one character is listed in the destination string for any number of the same character in the source string. Source and destination may be the same. This is useful when repeated scans are used on the same string for speed. Rating 4,500 str/sec See also Is*, StrBrk, StrSort, StrSpn Example Try the following example: var S1,S2: string; begin S1 := 'Eagle Performance Software 321'; StrMemb (S2,S1); { S2=' 123EPSacefglmnortw' } end. Chapter 2, Procedures and Functions Page 17 STRG Utilities Reference Guide, Version 5.7 --------------------------------------------------------------------------- StrMove procedure Strg --------------------------------------------------------------------------- Function Moves a string to another location WITH the length byte. Declaration StrMove (VAR Dest: string; S: string) Remarks Up to 70% faster than using and assignment (":="). Use when speed is essential. Be sure Dest is large enough. Rating 53,400 str/sec See also StrCat, StrCopy, StrOvr, StrPeek Example Assign a string to another: S1 := 'Now is the time'; StrMove (S2,S1); { S2='Now is the time' } --------------------------------------------------------------------------- StrOvr procedure Strg --------------------------------------------------------------------------- Function Overwrites a string at a given index. Declaration StrOvr (VAR Dest: string; S: string; Index: byte) Remarks The length of the original string is increased if the substring makes it longer. Any gap between the two strings is filled with spaces. This is a move-type procedure, so be sure the destination is large enough. However, resulting strings are truncated at 255. Suggestions This is a popular routine. Use it when strings need to be aligned for formatting or displayed in columns. Rating 44,100 str/sec See also Copy, StrCat, StrCopy, StrJ*, StrMove, StrPoke Example Try the following examples: S := 'Hello world'; StrOvr (S,'friends',7); { S='Hello friends' } T := 'First'; { 123456789012345678 } StrOvr (T,'MI' , 9); { T='First MI' } StrOvr (T,'Last',15); { T='First MI Last' } --------------------------------------------------------------------------- StrPeek procedure Strg --------------------------------------------------------------------------- Function Grabs an array in memory and converts it to a string. Declaration StrPeek (VAR Dest: string; VAR Source; Count: byte) Remarks Takes an array in memory at Source and converts it to a string at Dest. Dest[0] cannot overlap Source. This allows arrays to be handled as strings. Rating 42,100 str/sec See also StrMove, StrPoke Example Try the following example: Chapter 2, Procedures and Functions Page 18 STRG Utilities Reference Guide, Version 5.7 const { 12345678901234567890123 } A: array[1..23] of char = 'Eagle Performance, Inc.'; var S: string; begin StrPeek (S,A[7],11); { S='Performance' } end. --------------------------------------------------------------------------- StrPoke procedure Strg --------------------------------------------------------------------------- Function Pokes the characters of a string into memory. Declaration StrPoke (VAR Dest; S: string) Remarks Pokes the characters of S as an array into memory NOT including the length byte. This allows strings to be handled as arrays. Dest[0] cannot overlap S. Rating 43,600 str/sec See also StrOvr, StrPeek Example Try the following example: const { 12345678901234567890123 } A: array[1..23] of char = 'Eagle , Inc.'; S: string = 'Performance'; begin { 12345678901234567890123 } StrPoke (A[7],S); { A='Eagle Performance, Inc.' } end. --------------------------------------------------------------------------- StrPos* function Strg --------------------------------------------------------------------------- Function Finds the position of a given string with match/ignore case. Declaration StrPosL (S,Find: string; Nth: byte) StrPosLI (S,Find: string; Nth: byte) StrPosR (S,Find: string; Nth: byte) StrPosRI (S,Find: string; Nth: byte) StrPosX (S,Find: string; indeX: byte) StrPosXI (S,Find: string; indeX: byte) Result type byte Remarks Using suffixes, -L routine searches from the left while the -R searches from the right for the Nth occurrence. The -X routine starts at the given index and searches right for the first occurrence. These routines match case, while those with the added -I suffix will Ignore case. Rating StrPos? 1-char: 23,900 str/sec StrPos? 5-char: 18,200 str/sec StrPos?I 1-char: 6,800 str/sec StrPos?I 5-char: 5,900 str/sec See also ChrPos*, StrBrk --------------------------------------------------------------------------- StrQty* function Strg --------------------------------------------------------------------------- Function Counts the occurrences of a given substring in a string with match/ignore case. Chapter 2, Procedures and Functions Page 19 STRG Utilities Reference Guide, Version 5.7 Declaration StrQty (S,Find: string) StrQtyI (S,Find: string) Result type byte Remarks StrQty matches case while StrQtyI ignores case. Rating StrQty 1-char: 23,900 str/sec StrQty 5-char: 18,200 str/sec StrQtyI 1-char: 6,800 str/sec StrQtyI 5-char: 5,900 str/sec See also ChrQty*, WrdQty --------------------------------------------------------------------------- StrRepl* procedure Strg --------------------------------------------------------------------------- Function Finds and replaces a substring from a given index for Qty number of replacements with match/ignore case. Declaration StrRepl (VAR S: string; Find,Repl: char; Index,Qty,MaxLen: byte) StrReplI (VAR S: string; Find,Repl: char; Index,Qty,MaxLen: byte) Remarks The operation starts from Index and goes to the right. It will stop if the index is beyond the end of string or it has replaced as many as it can. StrRepl matches case while StrReplI ignores case. The global variable ReplToDo is the result of Qty less the number of replacements that were done on the string. MaxLen is used for the special case when the length of Repl is greater than Find. The routine will replace as many as it can. If one more replacement would cause the string length to be greater than MaxLen, the routine will stop at that find and report the index as ReplIndex and will set ReplOverFlow=true. Otherwise, ReplIndex=0 and ReplOverFlow is false. Rating StrRepl: 8,800 str/sec StrReplI: 4,600 str/sec See also ChrDel*, ChrRepl* Example Try the following example: var S: string; begin { 1234567890123456789012345678901234 } S := 'Fast TEST String, FAST test string'; StrReplI (S,'st','---',1,255,38); end. The results will be ReplOverFlow=true, ReplIndex=30, and ReplToDo=251 with S as follows: { 12345678901234567890123456789012345678 } S := 'Fa--- TE--- ---ring, FA--- test String'; Chapter 2, Procedures and Functions Page 20 STRG Utilities Reference Guide, Version 5.7 --------------------------------------------------------------------------- StrReTab procedure Strg --------------------------------------------------------------------------- Function Reduces spaces to tabs. Declaration StrReTab (VAR Dest: string; S: string; TabSpaces: byte) Remarks This routine reduces spaces with tabs given the tab spacing. Embedded tabs are accounted for. Tab spacing is a minimum of one and zero values are forced to 1. Position 1 is considered column 1. Source and Dest can be the same address. Rating 6,000 str/sec See also StrDeTab Example Reduce spaces in the following string: { 1234567890123456789012 } S := ' Col 9 Col 17'; StrDeTab (S,S,8); { S=#9'Col 9'#9'Col 17' } --------------------------------------------------------------------------- StrRev procedure Strg --------------------------------------------------------------------------- Function Reverses the order of the characters in a string. Declaration StrRev (VAR S: string) Rating 16,600 str/sec See also StrEnum, StrSort Example Try the following: S := 'abcdefg'; StrRev (S); { S='gfedcba' } --------------------------------------------------------------------------- StrRoll procedure Strg --------------------------------------------------------------------------- Function Rolls the characters in a string forward or backward. Declaration StrRoll (VAR S: string; Count: integer) Remarks A forward roll moves characters from right to left and appends the rolled out characters on the right end. A backward roll (a negative value) does the reverse. If Count is greater than S[0], the Count is adjusted by mod. Rating 27,800 str/sec See also StrRev, StrSort Example Try the following: S1 := '1234567890'; S2:=S1; StrRoll (S1,2); { S1='3456789012' } StrRoll (S2,-2); { S2='9012345678' } --------------------------------------------------------------------------- StrSort procedure Strg --------------------------------------------------------------------------- Function Operates on a string by sorting it in ascending order. Declaration StrSort (VAR S: string) Remarks Two algorithms are used for this routine for speed. For strings up to 22 chars long, the classic Quick Sort is used. Chapter 2, Procedures and Functions Page 21 STRG Utilities Reference Guide, Version 5.7 After 22 chars, the Tally Sort is used which is up to 10 times faster than Quick Sort, because the Tally Sort does it in only two passes. Rating 3,600 str/sec See also StrEnum, StrMemb, StrRev Suggestions This routine is so efficient, you can even use it to sort any byte arrays by using an absolute variable at the address you want to sort or you can use StrPeek/StrPoke for arrays up to 255 bytes. Example Try the following: S := 'fgb1edca'; StrSort (S); { S='1abcdefg' } --------------------------------------------------------------------------- StrSpn function Strg --------------------------------------------------------------------------- Function Counts the number of consecutive characters that are all members of a group of chars. Declaration StrSpn (S,Members: string; Index: byte) Result type byte Remarks The function scans the string S starting at Index and scans RIGHT. Members is any group of characters. As long as the scanned character is in Members, it will continue to scan for the next one until it finds a non-member of Members. The result is the span (Spn) of the substring that are all members. This routine is usually used to parse a string. For greater speed, place the most commonly used members early in Members. Rating 1-char Members: 23,600 str/sec 5-char Members: 3,600 str/sec See also StrBrk, StrMemb, Wrd*, WrdParse, WrdToken Example Find the length of the number in string S: var S,Numbers: string; Size: byte; begin S := 'Balance $24,567.00 in credits.'; StrEnum (Numbers,'0','9'); StrCat (Numbers,'+-.,',255); Size := StrSpn (S,Numbers,10); { Size=9 } end. --------------------------------------------------------------------------- StrUpr procedure Strg --------------------------------------------------------------------------- Function Converts strings to upper case. Declaration StrUpr (VAR S: string) Remarks The operation works on the entire string. Rating 8,900 str/sec See also ChrReplI, LoCase, StrLwr, UpCase Chapter 2, Procedures and Functions Page 22 STRG Utilities Reference Guide, Version 5.7 --------------------------------------------------------------------------- UpCase function Strg --------------------------------------------------------------------------- Function Converts characters to upper case. Declaration UpCase (C: char) Result type char Remarks About 3 times faster than System.UpCase producing identical results. See also ChrReplI, LoCase, StrLwr, StrUpr --------------------------------------------------------------------------- ValBin function Strg --------------------------------------------------------------------------- Function Converts binary strings to longint. Declaration ValBin (S: string; VAR Code: integer) Result type longint (but smaller types are permissible) Remarks ValBin has these superior features: - Leading spaces are permitted but not trailing ones. - Leading zeros are also permitted. - A non-zero error code points to the invalid character in the string. - Numbers larger than $FFFFFFFF produce an error. - ValBin salvages a value even if there is an error! - Routine is more flexible as a function rather than being similar to the Val procedure which is compiler dependent on the number type. Rating 25,500 str/sec See also StrBin, StrHex, ValHex Example In the last example, Code=9. The others set Code=0. LongInt1 := ValBin ('001100100',Code); { LontInt1=100 } LongInt2 := ValBin ('111110100',Code); { LongInt2=500 } LongInt3 := ValBin (' 101101b',Code); { LongInt3=45 } --------------------------------------------------------------------------- ValHex function Strg --------------------------------------------------------------------------- Function Converts hex strings to longint. Declaration ValHex (S: string; VAR Code: integer) Result type longint (but smaller types are permissible) Remarks ValHex has these superior features: - Leading spaces are permitted but not trailing ones. - Leading zeros are also permitted. - The leading '$' is optional! - A non-zero error code points to the invalid character in the string. - Numbers larger than $FFFFFFFF produce an error. - ValHex salvages a value even if there is an error! - Twice as fast as Val and uses much less code. - Routine is more flexible as a function rather than the Val procedure which is compiler dependent on the number Chapter 2, Procedures and Functions Page 23 STRG Utilities Reference Guide, Version 5.7 type. Rating 27,200 str/sec See also StrBin, StrHex, ValBin Example In the last example, Code=5. The others set Code=0. LongInt1 := ValHex (' 0064',Code); { LongInt1=100 } LongInt2 := ValHex (' $1f4',Code); { LongInt1=500 } LongInt3 := ValHex (' 2Dh',Code); { LongInt1=45 } --------------------------------------------------------------------------- Wrd* procedure Strg --------------------------------------------------------------------------- Function Parses words separated by spaces. Declaration WrdL (VAR Dest: string; S: string; Nth: byte) WrdR (VAR Dest: string; S: string; Nth: byte) WrdLX (VAR Dest: string; S: string; indeX: byte) WrdRX (VAR Dest: string; S: string; indeX: byte) Remarks A word at the beginning or end of a string is considered a word even though it does not have spaces on both ends. The procedures apply as follows: WrdL - parses Nth word from the Left WrdR - parses Nth word from the Right WrdLX - parses first word from Left starting at indeX. WrdRX - parses first word from Right starting at indeX. WrdLX and WrdRX parses the first word with its first letter found in the direction of search even if it starts at indeX. Rating Wrd?: 16,400 str/sec Wrd?X: 25,100 str/sec See also StrBrk, StrSpn, WrdPos*, WrdParse, WrdToken Example Try the following parsing: var S,W1,W2,W3,W4: string; begin S := 'Eagle Performance Software Products'; WrdL (W1,S,2); { W1='Performance'} WrdR (W2,S,2); { W2='Software' } WrdLX (W3,S,2); { W3='Performance'} WrdRX (W4,S,255); { W1='Products' } end. --------------------------------------------------------------------------- WrdParse procedure Strg --------------------------------------------------------------------------- Function Generic parsing routine. Declaration WrdParse (VAR Dest: string; S,Delims: string; VAR Index: byte) Remarks Delims is a group of characters considered delimiters. (Place the most used delimiters early in the string for faster performance.) WrdParse extracts the next delimited word RIGHT from the given Index and does not search Chapter 2, Procedures and Functions Page 24 STRG Utilities Reference Guide, Version 5.7 backwards. WrdParse adjusts Index so it marks where to start the next parse on the next call. Routine has fully scanned when resulting indeX is set to zero. Different from WrdToken, nulls are significant; i.e., two delimiters in sequence is considered a null parse. So, if a delimiter is at the end of a string, the final parse returned is null. Rating 1-char Delims: 28,500 str/sec 5-char Delims: 6,500 str/sec See also StrBrk, StrSpn, Wrd*, WrdPos*, WrdToken Example Parse the following string S into the string array: uses strg; var A: array[0..4] of string; i,j,Index: byte; D,S: string; begin S := 'Faster, yet better'; D := ' ,.'; { These are the delimiters. } i := 0; { First parse will be in Sarray[0] } Index := 1; { Start at first character } while Index<>0 do begin WrdParse (A[i],S,D,Index); inc (i); end; end. Program will end with i=4 which is the number of parses found. The results are A[0]='Faster', A[1]='', A[2]='yet', and A[3]='better'. A[1] is null because a null string was parsed between the comma and space which is useful for parsing command line entries that are null. --------------------------------------------------------------------------- WrdPos* function Strg --------------------------------------------------------------------------- Function Returns position of word delimited by spaces. Declaration WrdPosL (S: string; Nth: byte) WrdPosR (S: string; Nth: byte) WrdPosLX (S: string; indeX: byte) WrdPosRX (S: string; indeX: byte) Result type byte Remarks A word at the beginning or end of a string is considered a word even though it does not have spaces on both ends. The procedures apply as follows: WrdPosL - find Nth word from the Left WrdPosR - find Nth word from the Right WrdPosLX - find first word from Left starting at indeX. WrdPosRX - find first word from Right starting at indeX. If the index is not located on the first letter of a word, WrdPosLX and WrdPosRX will continue scanning for the next Chapter 2, Procedures and Functions Page 25 STRG Utilities Reference Guide, Version 5.7 word. Rating WrdPos?: 17,700 str/sec WrdPos?X: 26,400 str/sec See also StrBrk, StrSpn, Wrd*, WrdParse, WrdToken Example Try the following examples: { 12345678901234567890123456789012345678 } S := 'Now is the time for all good programs.'; MyByte := WrdPosR (S,1); { MyByte=30 } MyByte := WrdPosL (S,3); { MyByte= 8 } MyByte := WrdPosLX (S,9); { MyByte=12 } MyByte := WrdPosRX (S,9); { MyByte= 8 } --------------------------------------------------------------------------- WrdQty function Strg --------------------------------------------------------------------------- Function Counts the number of words in a string delimited by spaces. Declaration WrdQty (S: string) Result type byte Remarks A word at the beginning or end of a string is considered a word even though it does not have spaces on both ends. Rating 18,400 str/sec See also ChrQty*, StrQty* Example Try the following example: S := 'Now is the time for all good programs.'; MyByte := WrdQty (S); { MyByte=8 } --------------------------------------------------------------------------- WrdToken procedure Strg --------------------------------------------------------------------------- Function Generic token parsing routine. Declaration WrdToken (VAR Dest: string; S,Delims: string; VAR indeX: byte) Remarks Delims is a group of characters considered delimiters. (Place the most used delimiters early in the string for faster performance.) WrdToken extracts the next delimited word RIGHT from the given indeX and does not search backwards. WrdToken adjusts indeX so it marks where to start the next parse on the next call. Routine has fully scanned when resulting indeX is set to zero. Different from WrdParse, nulls are NOT significant; i.e., all delimiters are passed over until the next token is found. But, if a delimiter is at the end of a string, the final token returned is still null. Rating 1-char Delims: 28,500 str/sec 5-char Delims: 6,500 str/sec See also StrBrk, StrSpn, Wrd*, WrdPos*, WrdParse Example Parse the following S into the string array: Chapter 2, Procedures and Functions Page 26 STRG Utilities Reference Guide, Version 5.7 uses strg; var A: array[0..4] of string; i,j,Index: byte; D,S: string; begin S := 'Faster, yet better'; D := ' ,.'; { These are the delimiters. } i := 0; { First parse will be in A[0] } Index := 1; { Start at first character } while Index<>0 do begin WrdToken (A[i],S,D,Index); inc (i); end; end. Program will end with i=3 which is the number of tokens found. The results are A[0]='Faster', A[1]='yet', and A[2]='better'. Chapter 2, Procedures and Functions Page 27 STRG Utilities Reference Guide, Version 5.7 3. V A R I A B L E S There are only a few variables to consider in the STRG unit. Some can be accessed for global use and just one is local. GLOBAL Global Variables - These variables can be used to assist your programs more efficiently: Variable Description ------------ ----------------------------------------------------------- AscDestPtr (Type: Pointer) After AscStr is executed, this pointer points to the next ASCIIZ destination after the end-of- string null. This is very useful for sequential conversions to save space with ASCIIZ strings. AscSrcPtr (Type: Pointer) After StrAsc is executed, this pointer points to the next ASCIIZ source after the end-of-string null or the next valid character if the conversion is limited by MaxLen. This is very useful for sequential conversions from contiguous ASCIIZ strings. CmpIndex1 (Type: Integer) After strings are compared with StrCmp*, the index of difference for S1 is saved in this variable. The integer type is used in lieu of byte for the case of difference at column 256 (Index1+MaxLen>255). If you do not use strings out to S1[255], then it is permissible to use byte assignments to this variable. CmpIndex2 (Type: Integer) Same as CmpIndex1 except it applies to S2. LnDestPtr (Type: Pointer) After LnStr is executed, this pointer points to the next ASCII text file destination after the end-of-string CR/LF. This is very useful for sequential conversions to an ASCII text file for a block write. LnSrcPtr (Type: Pointer) After StrLn is executed, this pointer points to the next ASCII text file source after the end-of- string CR/LF, CR, or the next valid character if the conversion is limited by MaxLen. This is very useful for sequential conversions from a block read of an ASCII text file. ReplIndex (Type: Byte) After using StrRepl* and there is an overflow, this variable provides the index where the operation was halted. ReplOverFlow (Type: Boolean) After using StrRepl* when the replacement string is longer than the find string and the resulting string would be longer than MaxLen permits, this value is set to TRUE. This means the operation went as far as it could go before overflowing the length. Chapter 3, Variables Page 28 STRG Utilities Reference Guide, Version 5.7 ReplToDo (Type: Byte) After using StrRepl*, this variable indicates how many replacements are still needed to fulfill the original request. If it is zero, then all replacements were done. LOCAL Local Constant - There is only one local constant to STRG: Constant Description ------------ ----------------------------------------------------------- ChrClass (Type: array of char) Several of the more complicated Is* functions use this 128 char array to quickly classify characters by testing individual bits in the array. Simpler Is* functions do not use this array and it is optimized out of the program. Chapter 3, Variables Page 29 STRG Utilities Reference Guide, Version 5.7 4. A C C E S S I B L E M E M O R Y Many of the routines in STRG use 16-bit transfers to increase string processing. As as you program to normally to RAM, these routines will work fine. Just remember that certain hardware other than RAM can have limitations. The only one of which we are aware is trying to use these routines for direct manipulation of the EGA/VGA bit plane memory for video graphics, which would indeed be a bizarre application for these routines. For graphics programming, either stick to the BGI drivers, or use routines that only have 8-bit transfers. For more info on this limitation on video hardware, check out page 114 of Richard Wilton's book "Programmer's Guide to PC & PS/2 Video Systems". Chapter 4, Accessible Memory Page 30 STRG Utilities Reference Guide, Version 5.7 5. Q U I C K R E F E R E N C E For a quick reference for all of the declarations contained in this unit, the following are all the routines listed in alphabetical order. procedure AscStr (VAR AscDest; S: string); procedure ChrDel (VAR S: string; Find: char); procedure ChrDelL (VAR S: string; Find: char); procedure ChrDelR (VAR S: string; Find: char); procedure ChrFill (VAR S: string; Fill: char; Count: byte); procedure ChrPadC (VAR S: string; Find: char; Field: byte); procedure ChrPadL (VAR S: string; Find: char; Field: byte); procedure ChrPadR (VAR S: string; Find: char; Field: byte); function ChrPosL (S: string; Find: char; Nth: byte): byte; function ChrPosLI (S: string; Find: char; Nth: byte): byte; function ChrPosR (S: string; Find: char; Nth: byte): byte; function ChrPosRI (S: string; Find: char; Nth: byte): byte; function ChrPosX (S: string; Find: char; indeX: byte): byte; function ChrPosXI (S: string; Find: char; indeX: byte): byte; function ChrQty (S: string; Find: char): byte; function ChrQtyI (S: string; Find: char): byte; procedure ChrRepl (VAR S: string; Find,Repl: char; Index,Qty: byte); procedure ChrReplI (VAR S: string; Find,Repl: char; Index,Qty: byte); function Copy ( S: string; Index,Count: integer): string; procedure Delete (VAR S: string; Index,Count: integer); function IsAlNum (C: char): boolean; function IsAlpha (C: char): boolean; function IsASCII (C: char): boolean; function IsCntrl (C: char): boolean; function IsDigit (C: char): boolean; function IsDOS (C: char): boolean; function IsFile (C: char): boolean; function IsGraph (C: char): boolean; function IsLower (C: char): boolean; function IsPath (C: char): boolean; function IsPrint (C: char): boolean; function IsPunct (C: char): boolean; function IsReal (C: char): boolean; function IsSigned (C: char): boolean; function IsSpace (C: char): boolean; function IsUpper (C: char): boolean; function IsXDigit (C: char): boolean; procedure LnStr (VAR LnDest; S: string); function LoCase (C: char): char; function Pos (Find,S: string): byte; procedure StrAsc (VAR Dest: string; VAR AscSrc; MaxLen: byte); function StrBin (Num: longint; Field: byte): string; function StrBrk (S,Breaks: string; Index: byte): byte; function StrC (C: comp): string; procedure StrCat (VAR Dest: string; S: string; MaxLen: byte); procedure StrCatX (VAR Dest: string; S: string; indeX,Count,MaxLen: byte); function StrCF (C: comp; Field: integer): string; function StrCFD (C: comp; Field,Decimals: integer): string; function StrCmp (S1,S2: string; Index1,Index2,MaxLen: byte): shortint; Chapter 5, Quick Reference Page 31 STRG Utilities Reference Guide, Version 5.7 function StrCmpI (S1,S2: string; Index1,Index2,MaxLen: byte): shortint; procedure StrCopy (VAR Dest: string; S: string; Index,Count: byte); procedure StrCut (VAR S: string; MaxLen: byte); function StrD (D: double): string; procedure StrDeTab (VAR Dest: string; S: string; TabSpaces: byte); function StrDF (D: double; Field: integer): string; function StrDFD (D: double; Field,Decimals: integer): string; function StrE (E: extended): string; function StrEF (E: extended; Field: integer): string; function StrEFD (E: extended; Field,Decimals: integer): string; procedure StrEnum (VAR S: string; First,Last: char); procedure StrFill (VAR S: string; Fill: string; Count,MaxLen: byte); function StrHex (Num: longint; Field: byte): string; procedure StrIns (VAR Dest: string; S: string; DestIndex,MaxLen: byte); function StrJC (S: string; Field: byte): string; function StrJL (S: string; Field: byte): string; function StrJR (S: string; Field: byte): string; function StrL (L: longint): string; function StrLF (L: longint; Field: integer): string; procedure StrLn (VAR Dest: string; VAR LnSrc; MaxLen: byte); procedure StrLwr (VAR S: string); procedure StrMemb (VAR Dest: string; S: string); procedure StrMove (VAR Dest: string; S: string); procedure StrOvr (VAR Dest: string; S: string; DestIndex: byte); procedure StrPeek (VAR Dest: string; VAR Source; Count: byte); procedure StrPoke (VAR Dest; S: string); function StrPosL (S,Find: string; Nth: byte): byte; function StrPosLI (S,Find: string; Nth: byte): byte; function StrPosR (S,Find: string; Nth: byte): byte; function StrPosRI (S,Find: string; Nth: byte): byte; function StrPosX (S,Find: string; indeX: byte): byte; function StrPosXI (S,Find: string; indeX: byte): byte; function StrQty (S,Find: string): byte; function StrQtyI (S,Find: string): byte; function StrR (R: real): string; procedure StrRepl (VAR S: string; Find,Repl: string; Index,Qty,MaxLen: byte); procedure StrReplI (VAR S: string; Find,Repl: string; Index,Qty,MaxLen: byte); procedure StrReTab (VAR Dest: string; S: string; TabSpaces: byte); procedure StrRev (VAR S: string); function StrRF (R: real; Field: integer): string; function StrRFD (R: real; Field,Decimals: integer): string; procedure StrRoll (VAR S: string; Count: integer); function StrS (S: single): string; function StrSF (S: single; Field: integer): string; function StrSFD (S: single; Field,Decimals: integer): string; procedure StrSort (VAR S: string); function StrSpn (S,Members: string; Index: byte): byte; procedure StrUpr (VAR S: string); function UpCase (C: char): char; function ValBin (S: string; VAR Code: integer): longint; function ValHex (S: string; VAR Code: integer): longint; procedure WrdL (VAR Dest: string; S: string; Nth: byte); procedure WrdLX (VAR Dest: string; S: string; indeX: byte); procedure WrdParse (VAR Dest: string; S,Delims: string; VAR Index: byte); Chapter 5, Quick Reference Page 32 STRG Utilities Reference Guide, Version 5.7 function WrdPosL (S: string; Nth: byte): byte; function WrdPosLX (S: string; indeX: byte): byte; function WrdPosR (S: string; Nth: byte): byte; function WrdPosRX (S: string; indeX: byte): byte; function WrdQty (S: string): byte; procedure WrdR (VAR Dest: string; S: string; Nth: byte); procedure WrdRX (VAR Dest: string; S: string; indeX: byte); procedure WrdToken (VAR Dest: string; S,Delims: string; VAR Index: byte); Chapter 5, Quick Reference Page 33