Programmer 7500/MAX_PROGRAMMERS.iso/PASCAL/TOTDOC.ZIP/CHAPT14.TXT

Text File | 1991-02-11 | 28.3 KB | 757 lines

                                                                          String
                                                                        Handling





         "Guests, like fish, begin to smell after three days."

                                                               Benjamin Franklin





         The totSTR unit provides a set of routines for converting data to and
         from string format. Although the unit includes the object FmtNumberOBJ,
         the majority of the routines are good ol' functions.



String Functions

         These functions are grouped into the following categories reflecting
         their primary purpose: string adjustment, string searching, word man-
         agement and number conversion.



String Adjustment

Squeeze

         Squeeze(L:char;Str:string;Width:byte);

         Returns a string that has been squeezed (or expanded) to a specific
         length. If the source string is too long, either the leftmost or right-
         most characters are removed. The function is passed three parameters; a
         character to indicate which side of the string to truncate ('L' or
         'R'), the source string, and the desired string width. If the source
         string is shorter than the desired width, the string is padded with
         spaces. For example:

                  TIGHT :=SQUEEZE('L','ARKANSAS',6);

         Assigns the value 'KANSAS' to TIGHT.



PadLeft

         Padleft(Str:string;Size:byte;ChPad:char):string;

         Expands and left justifies a string to a specified width. The function
         is passed three parameters; the source string, the length of the
         expanded string, and the character used to pad the string. For example:

                  MyString := PadLeft('LOAD FILE',20,' ');

         Assigns the value 'LOAD FILE          ' to MyString.

14-2                                                                User's Guide

--------------------------------------------------------------------------------

PadRight

         PadRight(Str:string;Size:byte;ChPad:char):string;

         Expands and right justifies a string to a specified width. The function
         is passed three parameters; the source string, the length of the
         expanded string, and the character used to pad the string. For example:

                  MyString := PadRight('RIGHT',10,'*');

         Assigns the value '*****RIGHT' to MyString.



PadCenter

         PadCenter(Str:string;Size:byte;ChPad:char):string;

         Expands and centers a string to a specified width. The function is
         passed three parameters; the source string, the length of the expanded
         string, and the character used to pad the string. For example:

                  Bored := PadCenter('Middle',14,'-');

         Assigns the value '----Middle----' to Bored.



Pad

         Pad(PadJust:tJust;Str:string;Size:byte;ChPad:char):string;

         This function combines the features of PadLeft, PadRight and PadCenter
         into a single function. The totSTR unit includes the declaration of an
         enumerated type tJust, with the following members: JustLeft, Just-
         Center, and JustRight. The function is passed four parameters; a member
         of tJust to indicate the required justification, the source string, the
         length of the expanded string, and the character used to pad the
         string. For example:

                  PadStr := Pad(JustCenter,'Middle',14,'-');

         Assigns the value '----Middle----' to PadStr.



SetUpper

         SetUpper(Str:string):string;

         Returns a string with all the alpha characters converted to upper case.
         The string is passed one parameter; the source string. For example:

                  MyString := SetUpper('123abc456dEf');

         Assigns the value '123ABC456DEF' to MyString.

String Handling                                                             14-3

--------------------------------------------------------------------------------

SetLower

         SetLower(Str:string):string;

         Returns a string with the alpha characters converted to lower case. The
         string is passed one parameter; the source string. For example:

                  MyString := SetLower('123ABC456DeF');

         Assigns the value '123abc456def' to MyString.



SetProper

         SetProper(Str:string):string;

         Returns a string with the first character of each word converted to
         upper case. The string is passed one parameter; the source string. For
         example:

                  MyString := SetProper('eeny meeny miny mo');

         Assigns the value 'Eeny Meeny Miny Mo' to MyString.



AdjCase

         AdjCase(NewCase:tCase; Str:string): string;

         This function combines the features of SetUpper, SetLower and SetProper
         into a single function. The totSTR unit includes the declaration of an
         enumerated type tCase, with the following members: Lower, Upper,
         Proper, and Leave. If the member Leave is specified, the string will
         not be adjusted. The function is passed two parameters; a member of
         tCase to indicate the required capitalization, and the source string.
         For example:

                  PStr := AdjCase(Proper,'tracy chapman');

         Assigns the value 'Tracy Chapman' to PStr.



Last

         Last(N:byte; Str:string):string;

         Returns the last part of a string. The function is passed two parame-
         ters; the number of characters to extract, and the source string. For
         example:

                  NewString := Last(11,'Never take drugs!');

         Assigns the value 'take drugs!' to NewString.

14-4                                                                User's Guide

--------------------------------------------------------------------------------

First

         First(N:byte; Str:string):string;

         Returns the first part of a string. The function is passed two parame-
         ters; the number of characters to extract, and the source string. For
         example:

                  MyString := First(10,'I want sextuplets');

         Assigns the value 'I want sex' to MyString.



Strip

         Strip(L,C:char; Str:string): string;

         Returns the string with a specific character removed. The function is
         passed three parameters; a character to indicate which part of the
         string to strip, the character to strip, and the source string. The
         strip can be performed on the left of the string, the right of the
         string, the left and right, or all occurrences throughout the string.
         The first parameter would be the character 'L', 'R', 'B' or 'A',
         respectively. For example:

                  NoTees := Strip('A','T','THE TTT MAN');

         Assigns the value 'HE  MAN' to NoTees.



OverType

         OverType(N:byte; StrS,StrT:string):string;

         Places one string "on top of" another string and overlays the underly-
         ing characters. The function is passed three parameters; the character
         position in the target string to start the overtyping, the source
         string, and the target string. For example:

                  Result := Overtype(8,'TechnoJock','I love you');

         Assigns the value 'I love TechnoJock' to Result.



PicFormat

         PicFormat(Input,Picture:string;Pad:char):string;

         This function was specifically used to complement the PictureIOOBJ
         object used for obtaining formatted user input. The function returns a
         formatted string, and is passed three parameters; the source string,
         the picture string containing the format characters '!@*#', and the


String Handling                                                             14-5

--------------------------------------------------------------------------------

         character used to pad the string if the source is not long enough.
         Refer to chapter 11 for a full description of format characters. For
         example:

                  TelStr := PicFormat('713493635','(###) ###-####','*');

         Assigns the value '(713) 493-635*' to TelStr.



TruncFormat

         TruncFormat(Input:string; Start,Len:byte; Pad:char):string;

         Truncates (or expands) a string from a specified character position.
         The function is passed three parameters; the source string, the posi-
         tion of the first character to extract, and the total length of the
         returned string. For example:

                  NewStr := TruncFormat('Hidey Hidey Ho',9,10);

         Assigns the value 'dey Ho    ' to NewStr.



String Searching

FirstCapital

         FirstCapital(Str:string):char;

         Returns the first capital letter in a string. Note that this function
         returns type char. If a capital letter is not found, a null (#0) is
         returned. The function is passed one parameter; the source string. For
         example:

                  MyChar := FirstCapital('7 File Save');

         Assigns the value 'F' to MyChar.



FirstCapitalPos

         FirstCapitalPos(Str:string):byte;

         Returns the character position of the first capital letter in a string.
         Note that this function returns type byte. If a capital letter is not
         found, a zero is returned. The function is passed one parameter; the
         source string. For example:

                  ByteVar := FirstCapitalPos('how yer doin Bob');

         Assigns the value 14 to ByteVar.



14-6                                                                User's Guide

--------------------------------------------------------------------------------

LastPos

         LastPos(C:char;Str:string):byte;

         Returns a byte indicating the position of the last occurrence of a
         character in a string. If the character is not found, a zero is
         returned. The function is passed two parameters; a character to search
         for, and the source string. For example:

                  BytePos := LastPos('A','My Accommodation');

         Assigns the value 4 to BytePos.



LastPosBefore

         LastPosBefore(C:char;Str:string;Last:byte): byte;

         Returns a byte indicating the position of the last occurrence of a
         character, up to a specified part of the string. If the character is
         not found, a zero is returned. The function is passed three parameters;
         a character to search for, the source string, and the position of the
         last character to include in the search. For example:

                  SubPos := LastPosBefore('s','Mississippi',5);

         Assigns the value 4 to SubPos.



PosAfter

         PosAfter(C:char;Str:string;Start:byte):string;

         Returns a byte indicating the position of the first occurrence of a
         character, starting from a specified position in the string. If the
         character is not found, a zero is returned. The function is passed
         three parameters; a character to search for, the source string, and the
         position of the first character to include in the search. For example:

                  SubPos := PosAfter('s','Mississippi',5);

         Assigns the value 6 to SubPos.


Word Management

WordCnt

         WordCnt(Str:string):byte;

         Returns the number of words in a string. The procedure is passed one
         parameter; the source string. For example:

                  TotWords := WordCnt('eeny meeny miny mo');

String Handling                                                             14-7

--------------------------------------------------------------------------------

         Assigns the value 4 to TotWords.



PosWord

         PosWord(WordNo:byte; Str:string):byte;

         Returns the position of the first character of a specific word in a
         string. The function is passed two parameters; the word number, and the
         source string. If there are insufficient words in the string, a zero is
         returned. For example:

                  MyWord := PosWord(4,'What a stupid idea son!');

         Assigns the value 15 to MyWord.



ExtractWords

         ExtractWords(StartWord,NoWords:byte; Str:string):string;

         Returns a substring containing a specified number of words (real words,
         not computer words!) extracted from a source string. The function is
         passed three parameters; the number of the first word to extract, the
         total number of words to extract, and the source string. For example:

                  NewString := ExtractWords(5,3,'who the hell says
                                                 censorship is good');

         Assigns the value 'censorship is good' to NewString.



Number Conversions

ValidInt

         ValidInt(Str:string):boolean;

         This function returns true if the source string represents a valid
         integer, i.e. contains sensible numbers with no spaces or alpha charac-
         ters. The only passed parameter is the source string. For example:

                  OK := ValidInt('23xy45');

         Assigns the value false to OK.



ValidHEXInt

         ValidInt(Str:string):boolean;



14-8                                                                User's Guide

--------------------------------------------------------------------------------

         This function returns true if the source string represents a valid HEX
         notation integer, i.e. contains the numbers 0 through 9, or letters 'A"
         through 'F' with no spaces. The only passed parameter is the source
         string. For example:

                  OK := ValidHEXInt('2E4A');

         Assigns the value true to OK.



ValidReal

         ValidReal(Str:string):boolean;

         This function returns true if the source string represents a valid real
         number, i.e. contains numbers with no spaces or alpha characters. The
         only passed parameter is the source string. For example:

                  OK := ValidReal('89.95');

         Assigns the value true to OK.



StrtoInt

         StrToInt(Str:string):integer;

         Converts a number string and returns an integer. If the string is not a
         valid integer, a zero is returned. The function ValidInt can be used to
         check that the string is convertible. For example:

                  Salary := StrToInt('30000');

         Assigns the value 30000 to Salary.



StrtoLong

         StrToLong(Str:string):longint;

         Converts a number string and returns a longint. If the string is not a
         valid integer, a zero is returned. For example:

                  GoodSalary := StrToLong('300000');

         Assigns the value 300000 to GoodSalary.



StrToReal

         StrToReal(Str:string):extended;


String Handling                                                             14-9

--------------------------------------------------------------------------------

         Converts a number string and returns a real. If the string is not a
         valid real, a zero is returned. The function ValidReal can be used to
         determine whether the string is convertible. For example:

                  Taxes := StrToReal('15643.27');

         Assigns the value 15643.27 to Taxes.



HEXStrToLong

         HEXStrToLong(Str:string):longint;

         Converts a hexadecimal string and returns a longint. If the string is
         not a valid hex number, a zero is returned. The function ValidHEXInt
         can be used to determine whether the string is convertible. For exam-
         ple:

                  Val := HEXStrToLong('FF');

         Assigns the value 255 to Val.



IntToStr

         IntToStr(Number:longint):string;

         Returns a number converted to a string. The function is passed one
         parameter; the source number of type byte, word, shortint, integer or
         longint. For example:

                  NumStr := IntToStr(365);

         Assigns the value '365' to NumStr.



RealToStr

         RealToStr(Number:extended; Decimals:byte):string;

         Returns a real number converted to a string. The function is passed two
         parameters; the source real number, and the number of decimal places.
         If the number of decimal places is passed as FLOATING (a constant), the
         function will return only the significant digits. For example:

                  MeatPie := RealToStr(3.546000,FLOATING);

         Assigns the value '3.546' to MeatPie.


IntToHEXStr

         IntToHEXStr(Number:longint):string;

14-10                                                               User's Guide

--------------------------------------------------------------------------------

         Returns a hexadecimal string representing the value of a number. The
         function is passed one parameter; the source number, and it may be of
         type byte, word, shortint, integer or longint. For example:

                  SillyPower := IntToHexStr(255);

         Assigns the value 'FF' to SillyPower.



RealtoSciStr

         RealToSciStr(Number:extended; D:byte):string;

         Returns a real number converted to a scientific notation string. The
         function is passed two parameters; the source real number, and the
         number of decimal places. For example:

                  Velocity := RealToSciStr(45678.984564,8);

         Assigns the value '4.56789846E+04' to Velocity.



NthNumber

         NthNumber(Str:string; Nth:byte):char;

         This function is actually used internally by the Toolkit in the totDATE
         unit, but can be used if you can think of a reason! This function
         returns the character representing a number found in the string. The
         function is passed two parameters; the source string, and a byte indi-
         cating the position of the number to be returned. For example:

                  NumChar := NthNumber('02/20/48',5);

         Assigns the value '4' to NumChar.



Examples

         Listed below are the demo programs DEMST1.PAS and DEMST2.PAS, which
         illustrate how to use the string functions. Following each listing is a
         figure detailing the resultant output.

         program DemoStringOne;
         {demST1 - string functions}

         Uses DOS, CRT,
              totFAST, totSTR;

         Var
            DemoStr : string;



String Handling                                                            14-11

--------------------------------------------------------------------------------

         begin
            ClrScr;
            with Screen do
            begin
               DemoStr := '  TechnoJock''s Object Toolkit string demo   ';
               WriteAt(5,1,lightgray,'Source String: ');
               WriteAt(30,1,lightcyan,'"'+DemoStr+'"');
               WriteAt(1,4,lightgray,'SetUpper:');
               WriteAt(30,4,yellow,'"'+SetUpper(DemoStr)+'"');
               WriteAt(1,5,lightgray,'SetLower:');
               WriteAt(30,5,yellow,'"'+SetLower(DemoStr)+'"');
               WriteAt(1,6,lightgray,'SetProper:');
               WriteAt(30,6,yellow,'"'+SetProper(DemoStr)+'"');
               WriteAt(1,7,lightgray,'Total words:');
               WriteAt(30,7,lightgreen,IntToStr(WordCnt(DemoStr)));
               WriteAt(1,8,lightgray,'Posn. Word 3:');
               WriteAt(30,8,lightgreen,IntToStr(PosWord(3,DemoStr)));
               WriteAt(1,9,lightgray,'Words 2..5 are:');
               WriteAt(30,9,yellow,'"'+ExtractWords(2,4,DemoStr)+'"');
               WriteAt(1,10,lightgray,'Strip Leading spaces:');
               WriteAt(30,10,yellow,'"'+Strip('L',' ',DemoStr)+'"');
               WriteAt(1,11,lightgray,'Strip Trailing spaces:');
               WriteAt(30,11,yellow,'"'+Strip('R',' ',DemoStr)+'"');
               WriteAt(1,12,lightgray,'Strip Lng. & Tng. spaces:');
               WriteAt(30,12,yellow,'"'+Strip('B',' ',DemoStr)+'"');
               WriteAt(1,13,lightgray,'Strip All spaces:');
               WriteAt(30,13,yellow,'"'+Strip('A',' ',DemoStr)+'"');
            end;
            GotoXY(1,23);
         end.


Figure 14.1                                                             [SCREEN]
String
Functions



         program DemoStringTwo;
         {demST2 - more string functions}

         Uses DOS, CRT,
              totSTR;

         Const
             MyInt:integer = 4000;
             MyReal:real = 89.99;
             MyIntStr = '8000';
             MyRealStr = '89.95';
             MyHexStr = 'FFFF';



14-12                                                               User's Guide

--------------------------------------------------------------------------------

         begin
            ClrScr;
            writeln('Test number - ',MyInt);
            writeln;
            writeln('IntToStr:    ',IntToStr(MyInt));
            writeln('IntToHEXStr: ',IntToHEXStr(MyInt));
            writeln;
            writeln;
            writeln('Test number - ',MyReal:5:2);
            writeln;
            writeln('RealToStr: ',RealToStr(MyReal,5));
            writeln('RealToStr: ',RealToStr(MyReal,1));
            writeln('RealToStr: ',RealToStr(MyReal,FLOATING));
            writeln('RealToSciStr: ',RealToSciStr(MyReal,FLOATING));
            writeln;
            writeln;
            writeln('Test Strings: ',MyIntStr,' ',MyRealStr,' ',MyHEXStr);
            writeln;
            writeln('ValidInt: ',ValidInt(MyIntStr));
            writeln('ValidInt: ',ValidInt(MyHEXStr));
            writeln('ValidInt: ',ValidInt(MyRealStr));
            writeln('ValidReal: ',ValidReal(MyIntStr));
            writeln('ValidReal: ',ValidReal(MyRealStr));
            GotoXY(1,23);
         end.




Figure 14.2                                                             [SCREEN]
More String
Functions



FmtNumberOBJ

         The totSTR unit includes the object FmtNumberOBJ. This object includes
         function methods which accept numbers, and return them as formatted
         strings. The object is used to provide formatting capabilities to the
         number input fields in the totIO units (see page 11-21), but it may
         also be used independently to provide sophisticated number formatting
         control.

         The object can format both integer and real numbers, and the format
         options include the following:

         Prefix     The number can be preceded by a character or short string,
                    e.g. '$'.

         Suffix     The number can be succeeded by a character or short string,
                    e.g. 'FFr'


String Handling                                                            14-13

--------------------------------------------------------------------------------

         Sign       The number can be signed with + and/or -, parentheses on
                    negative numbers, or DB/CR to indicate debit and credit.

         Separators The number can have thousands separated by a character, e.g.
                    ','. Even the decimal place character and the character used
                    to pad the string can be specified.

         Justificat The number can be left, right or center justified in the
         ion        allotted space.



         To format numbers, you must initialize an instance of type FormatNum-
         berOBJ, specify the appropriate format options, and call a function
         method to return the number formatted as a string. The following
         methods are available:


         Init;

         This method initializes the object and must be called before the other
         methods.


         SetPrefixSuffix(P,S:string);

         Specifies the strings that will be used to precede and succeed the
         number. Pass a null string, i.e. '', to suppress either the prefix or
         suffix.


         SetSign(S:tSign);

         The totSTR unit includes the declaration of an enumerated type tSign
         with the following members: PlusMinus, Minus, Brackets, DbCr

         PlusMinus  Always precedes the number with a '+' or '-' to indicate the
                    sign of the number.

         Minus      Only displays a '-', i.e. if the number is positive, the '+'
                    is not displayed.

         Brackets   Negative numbers are enclosed in parentheses, e.g. (25.67).

         DbCr       If the number is negative it is succeeded with the string
                    'DB', otherwise it is succeeded with the string 'CR'.

         Use this method to specify how the sign of a number will be displayed.


         SetSeparators(P,T,D:char);

         Three different separators may be required to format a number, and this
         method identifies them. The first parameter is the character used to
         pad the string to the specified width, and common values are ' ' or
         '*'. The second parameter specifies the character used to separate each

14-14                                                               User's Guide

--------------------------------------------------------------------------------

         significant thousand, and typically has a value of ','. Specify #0, if
         you don't want a thousands separator. The last parameter specifies the
         character indicating the decimal place, e.g. '.'.


         SetJustification(J:tJust);

         When the number is formatted, it can be left, center, or right justi-
         fied. Pass a value of JustLeft, JustCenter or JustRight to identify the
         required justification.


         FormattedLong(Val:longint;Width:byte):string;

         Having set all the formatting options as required, call this method to
         return a formatted string. The method is passed two parameters; any
         whole number (i.e. byte, word, shortint, integer, longint), and the
         width of the string. If the formatted string is too long to fit in the
         specified width, an unformatted string is returned.


         FormattedReal(Val:extended;DP,Width:byte):string;

         This function method is similar to the method FormattedLong, except it
         is used to format real numbers. The method is passed three parameters;
         the real number, the number of decimal places, and the width of the
         returned string. The TotSTR unit includes a global constant FLOATING.
         When FLOATING is specified as the number of decimal places, the Toolkit
         will show all decimal places up to the last non-zero decimal.


         Done

         This method disposes of the memory used by the instance, and should be
         called when the object is no longer required.




           Note: the totIO2 unit includes a global instance FmtNumberTOT
           which is used to specify the default format for number input
           fields. Refer to page 11-22 for further details.




         Listed below is the demo program DEMST3.PAS, which illustrates how to
         use FmtNumberOBJ objects.

         program DemoStringThree;
         {demST3 - number formatting}

         Uses DOS, CRT,
              totFAST, totSTR;



String Handling                                                            14-15

--------------------------------------------------------------------------------

         Var
            Fmt: FmtNumberOBJ;

         begin
            ClrScr;
            with Fmt do
            begin
               Init;
               writeln(FormattedLong(2000,15));
               writeln(FormattedReal(2000,2,15));
               SetSign(PlusMinus);
               writeln(FormattedLong(2000,15));
               SetSign(DBCR);
               writeln(FormattedReal(2000,3,15));
               SetPrefixSuffix('$','');
               writeln(FormattedReal(2000,3,15));
               SetSeparators('*',',','.');
               writeln(FormattedReal(2000,3,15));
               SetJustification(JustRight);
               writeln(FormattedReal(2000,3,15));
               Done;
            end;
            GotoXY(1,23);
         end.


Figure 14.3                                                             [SCREEN]
Formatting
Numbers