home *** CD-ROM | disk | FTP | other *** search
/ Frostbyte's 1980s DOS Shareware Collection / floppyshareware.zip / floppyshareware / USCX / TURBO-04.ZIP / STRNGLIB.DOC < prev    next >
Text File  |  1985-02-23  |  13KB  |  340 lines
  1.  Suplementry String functions and procedures for Turbo Pascal
  2.  
  3.  
  4.        Written by: Tryg Helseth
  5.                    Minneapolis, Minnesota
  6.  
  7.     Last Revision: 1/4/85
  8.  
  9. USAGE NOTES:
  10.  
  11.   The following routines provide common string functions that are
  12.   not supplied with Turbo Pascal.  Many are patterned (and named)
  13.   after the General Electric Information Service COompany (GEISCO)
  14.   FORTRAN 77 string routines; others mimic SNOBOL primatives.
  15.  
  16.   The general calling sequence is:
  17.  
  18.      OutString := Func(InpString[,Parms])
  19.  
  20.   where:
  21.  
  22.      OutString = the output or target string,
  23.           Func = function name,
  24.         InpStr = Input String,
  25.        [Parms] = Additional parameter(s) used by some functions.
  26.  
  27. AVAILABLE FUNCTIONS:
  28.  
  29.     LoCase      Convert a single character to lower case.
  30.     LowerCase   Convert a string to lower case.
  31.     UpperCase   Convert a string to upper case.
  32.     TrimL       Trim Left: remove leading spaces from a string.
  33.     TrimR       Trim Right: remove trailing spaces from a string.
  34.     PadL        Pad Left: Add leading spaces to give desired field length.
  35.     PadR        Pad Right: Add trailing spaces to give desired field length.
  36.     JustL       Left Justify a string within a desired field length.
  37.     JustR       Right Justify a string within a desired field length.
  38.     Center      Center a string within a desired field length.
  39.     GetStr      Get String: Extracts a substring up to a specified delimiter.
  40.     Break       Extracts a substring up to the first of several delimters.
  41.     Span        Extracts a substring of delimiters up to a NON delimiter.
  42.  
  43.     Note: GetStr, Span, and Break, modify the input string.  The other
  44.           functions do not modify any parameters.
  45.  
  46. AVAILABLE PROCEDURES:
  47.  
  48.     GString     Get String: Used by Span and Break functions.  It performs
  49.                 both functions and allows more control by the programmer.
  50.  
  51.     RealStr     Convert a value of type REAL to a string representation in
  52.                 any base from 2 to 36.
  53.  
  54.     RealVal     Convert a string representation of a number to a REAL value.
  55.                 The number may be in any base from 2 to 36.
  56.  
  57. TYPE DECLARATION:
  58.  
  59.   All strings are of the type, LString, which should be declared in the main
  60.   program as:
  61.  
  62.       Type LString = string[n]
  63.  
  64.   where n is a constant in the range of 1 to 255.
  65.  
  66.   If you wish to use these functions with strings of different declared
  67.   lengths, then you must use the compiler option, $V-.  If you choose
  68.   to do this, be sure that the defined length of LString is greater than
  69.   or equal to the longest string you will be using.
  70.  
  71. FUNCTION DECLARATIONS:   
  72.  
  73. ===========================================
  74. function LoCase(InChar: char): char;
  75. ===========================================
  76.  
  77. Purpose:        Convert a single character to lower case.
  78.  
  79. Parameters:
  80.      Input:     InChar = character to be converted.
  81.     Output:     none
  82.  
  83. Function Value: LoCase = converted character.
  84.  
  85.  
  86. ====================================================
  87. function LowerCase(InpStr: LString): LString;
  88. ====================================================
  89.  
  90. Purpose:        Convert a string of characters to lower case.
  91.  
  92. Parameters:
  93.      Input:     InpStr = string to be converted.
  94.     Output:     none
  95.  
  96. Function Value: LowerCase = converted string.
  97.  
  98.  
  99. ====================================================
  100. function UpperCase(InpStr: LString): LString;
  101. ====================================================
  102.  
  103. Purpose:        Convert a string of characters to upper case.
  104.  
  105. Parameters:
  106.      Input:     InpStr = string to be converted.
  107.     Output:     none
  108.  
  109. Function Value: UpperCase = converted string.
  110.  
  111.  
  112. ================================================
  113. function TrimL(InpStr: LString): LString;
  114. ================================================
  115.  
  116. Purpose:        Trim Left: Remove leading spaces from a string.
  117.  
  118. Parameters:
  119.      Input:     InpStr = string to be trimmed.
  120.     Output:     none
  121.  
  122. Function Value: TrimL = trimmed string.
  123.  
  124.  
  125. ================================================
  126. function TrimR(InpStr: LString): LString;
  127. ================================================
  128.  
  129. Purpose:        Trim Right: Remove trailing spaces from a string.
  130.  
  131. Parameters:
  132.      Input:     InpStr = string to be trimmed.
  133.     Output:     none
  134.  
  135. Function Value: TrimR = trimmed string.
  136.  
  137.  
  138. ==================================================================
  139. function PadL(InpStr: LString; FieldLen: integer): LString;
  140. ==================================================================
  141.  
  142. Purpose:        Pad Left: Pad a string on the left with spaces to
  143.                 fill it to a desired field length.  Trailing spaces
  144.                 are not removed.
  145. Parameters:
  146.      Input:     InpStr = string to be padded.
  147.     Output:     none
  148.  
  149. Function Value: PadL = padded string.
  150.  
  151.  
  152. ==================================================================
  153. function PadR(InpStr: LString; FieldLen: integer): LString;
  154. ==================================================================
  155.  
  156. Purpose:        Pad Right: Pad a string on the right with spaces to
  157.                 fill it to a desired field length.  Leading spaces
  158.                 are not removed.
  159. Parameters:
  160.      Input:     InpStr = string to be padded.
  161.     Output:     none
  162.  
  163. Function Value: PadR = padded string.
  164.  
  165.  
  166. ===================================================================
  167. function JustL(InpStr: LString; FieldLen: integer): LString;
  168. ===================================================================
  169.  
  170. Purpose:        Left justify a string within a desired field length.
  171.                 First leading spaces are removed, then the string is
  172.                 padded with trailing spaces to the desired length.
  173. Parameters:
  174.      Input:     InpStr = string to be justified.
  175.     Output:     none
  176.  
  177. Function Value: JustL = justified string.
  178.  
  179.  
  180. ===================================================================
  181. function JustR(InpStr: LString; FieldLen: integer): LString;
  182. ===================================================================
  183.  
  184. Purpose:        Right justify a string within a desired field length.
  185.                 First trailing spaces are removed, then leading spaces
  186.                 are inserted fill to the desired length.
  187. Parameters:
  188.      Input:     InpStr = string to be justified.
  189.     Output:     none
  190.  
  191. Function Value: JustR = justified string.
  192.  
  193.  
  194. ====================================================================
  195. function Center(InpStr: LString; FieldLen: integer): LString;
  196. ====================================================================
  197.  
  198. Purpose:        Center a string within a desired field length.  First
  199.                 the string is stripped of leading and trailing spaces,
  200.                 then the resultant string is padded equally with
  201.                 leading and trailing spaces.
  202. Parameters:
  203.      Input:     InpStr = string to be justified.
  204.     Output:     none
  205.  
  206. Function Value: Center = centered string.
  207.  
  208.  
  209. ==================================================================
  210. function GetStr(InpStr: LString; Delim: Char): LString;
  211. ==================================================================
  212.  
  213. Purpose:       Strating at the first position of the input string,
  214.                return a substring containing all characters up to
  215.                (but not including) the fisrt occurence of the given
  216.                delimiter.  If the delimiter is not found, then the
  217.                entire input string is returned.  The substring and
  218.                delimiter are then deleted from the input string.
  219.  
  220. Parameters:
  221.      Input:     InpStr = string from which substring is removed.
  222.                 Delim  = delimiter to be used.
  223.     Output:     InStr  = remainder of input string.
  224.  
  225. Function Value: GetStr = Extracted substring.
  226.  
  227.  
  228. =====================================================================
  229. function Break(InpStr: LString; DelStr: LString): LString;
  230. =====================================================================
  231.  
  232. Purpose:       Emulates the SNOBOL BREAK function.  Operation is
  233.                similar to GetStr except that several delimiters
  234.                may be used.  The substring returns all characters
  235.                up to the first of any delimiter in DelStr.  Unlike
  236.                GetStr, the Delimiter found is NOT removed from
  237.                the input string.
  238.  
  239. Parameters:
  240.      Input:     InpStr = string from which substring is removed.
  241.                 DelStr = list of delimiters.
  242.     Output:     InStr  = remainder of input string.
  243.  
  244. Function Value: Break  = Extracted substring (Break on delimiter).
  245.  
  246.  
  247. ====================================================================
  248. function Span(InpStr: LString; DelStr: LString): LString;
  249. ====================================================================
  250.  
  251. Purpose:       Emulates the SNOBOL Span function.  Operation is
  252.                is the reverse of Break; The input string is scanned
  253.                for characters IN DelStr.  It returns a  substring
  254.                containing ONLY delimiters found starting at the
  255.                first position up the the first NON delimiter.  That
  256.                character is NOT removed from the input string.
  257.  
  258. Parameters:
  259.      Input:     InpStr = string from which substring is removed.
  260.                 DelStr = list of delimiters.
  261.     Output:     InStr  = remainder of input string.
  262.  
  263. Function Value: Span   = Extracted substring (Span of delimiters).
  264.  
  265.  
  266. =======================================================================
  267. procedure GString(InpStr, DelStr: LString; span: boolean;
  268.                   var cpos, dpos: integer; var OutStr: LString);
  269. =======================================================================
  270.  
  271. Purpose:       Emulates both the SPAN and BREAK functions of SNOBOL.
  272.  
  273.                SPAN:  If span is true, then starting from position, cpos,
  274.                the input string is scanned for characters in the string,
  275.                DelStr.  These characters are copied to the output string
  276.                until either a character NOT in DelStr is found or the end
  277.                of the string is reached.  Position pointer, cpos, is reset
  278.                to point at the break character.  If the end of the string
  279.                is reached, cpos is set to zero.
  280.  
  281.                BREAK: If span is false, then the input string is scanned
  282.                for characters NOT in the string, DelStr.  The output string
  283.                contains all characters up to the first delimiter.  Position
  284.                pointer, cpos, is set to point at the delimiter found.  If a
  285.                delimiter was not found, cpos is set to zero.
  286.  
  287.                Dpos is set to position in DelStr of the delimiter found.  If
  288.                none found, dpos is set to zero.
  289.  
  290. Parameters:
  291.      Input:     InpStr = string from which subs9ring is Copied.
  292.                 DelStr = delimiters to be used.
  293.                 span   = true = span, false = break.
  294.                 cpos   = starting position in input string.
  295.  
  296.     Output:     cpos   = position past found delimiter.
  297.                 dpos   = which delimiter was found.
  298.                 OutStr = substring copied from the input string.
  299.  
  300.  
  301. =================================================
  302. Procedure RealStr(Valu: Real; Base, Trail: integer;
  303.                   var OutStr: LString);
  304. =================================================
  305.  
  306. Purpose:        Convert a real value to an equivalent string representation.
  307.                 The value can be represented in any base from 1 to 36 with
  308.                 a specified number of digits to the right of the radix point.
  309.                 Digits 10 thru 35 are represeted by the letters A thru Z.
  310.  
  311. Parameters:
  312.  
  313.      Input:     Valu   = Real value to be converted to a string.
  314.                 Base   = Desired base.
  315.                 Trail  = number of digits to the right of the radix point.
  316.  
  317.     Output:     OutStr = string representation.
  318.  
  319.  
  320. ===========================================================
  321. Procedure RealVal(InpStr: LString; Base: integer;
  322.                   Var Err: integer; Var Valu: real);
  323. ===========================================================
  324.  
  325. Purpose:        Convert a string representation of a number to a real value.
  326.                 The value can be represented in any base from 1 to 36 and
  327.                 can have a fractional part.  Digits 10 thru 35 are represeted
  328.                 by the letters A thru Z respectively.  If an illegial
  329.                 character is encounterd, conversion halts and the error
  330.                 postion is reported through the variable, Err.
  331.  
  332. Parameters:
  333.  
  334.      Input:     InpStr = String representation to be converted to a real value.
  335.                 Base   = Base the value is represented in.
  336.  
  337.     Output:     Err    = position of illegial character; set to zero
  338.                          if no error is encountered.
  339.                 Valu   = converted value.
  340.