home *** CD-ROM | disk | FTP | other *** search
/ Share Gallery 1 / share_gal_1.zip / share_gal_1 / LA / LA018.ZIP / STRG55.ARC / STRG55.DOC < prev    next >
Text File  |  1990-01-02  |  36KB  |  1,140 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.                               STRG STRING UTILITIES
  21.                                   USER'S GUIDE
  22.  
  23.                                    Version 5.5
  24.                                  January 2, 1989
  25.  
  26.  
  27.                Copyright (C) 1989-1990 Eagle Performance Software
  28.                               All Rights Reserved.
  29.  
  30.  
  31.  
  32.                                _______                     
  33.                           ____| _     |               (tm) 
  34.                        --|       |    |------------------- 
  35.                          |   ____|__  |  Association of    
  36.                          |  |       |_|  Shareware         
  37.                          |__|   o   |    Professionals     
  38.                        -----|   |   |--------------------- 
  39.                             |___|___|    MEMBER            
  40.  
  41.  
  42.    STRG String Utilities                            User's Guide, Version 5.5
  43.  
  44.  
  45.  
  46.                        T A B L E   O F   C O N T E N T S
  47.  
  48.         1. INTRODUCTION  . . . . . . . . . . . . . . . . . . . . . 3
  49.              Features .  . . . . . . . . . . . . . . . . . . . . . 3
  50.              Using the Manuals . . . . . . . . . . . . . . . . . . 3
  51.              Licensing . . . . . . . . . . . . . . . . . . . . . . 4
  52.              Customer Service  . . . . . . . . . . . . . . . . . . 4
  53.              ASP . . . . . . . . . . . . . . . . . . . . . . . . . 5
  54.  
  55.         2. GETTING STARTED . . . . . . . . . . . . . . . . . . . . 6
  56.              Distribution Files  . . . . . . . . . . . . . . . . . 6
  57.              Simple Programming  . . . . . . . . . . . . . . . . . 6
  58.              Procedures and Functions  . . . . . . . . . . . . . . 6
  59.  
  60.         3. PHILOSOPHY  . . . . . . . . . . . . . . . . . . . . . . 11
  61.              Unit Design . . . . . . . . . . . . . . . . . . . . . 11
  62.              Program Design  . . . . . . . . . . . . . . . . . . . 11
  63.              Number to String Conversion . . . . . . . . . . . . . 14
  64.  
  65.         APPENDIX A: Other Products . . . . . . . . . . . . . . . . 15
  66.  
  67.         APPENDIX B: Revision History . . . . . . . . . . . . . . . 18
  68.  
  69.         APPENDIX C: References . . . . . . . . . . . . . . . . . . 19
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.                                        2
  103.    STRG String Utilities                            User's Guide, Version 5.5
  104.  
  105.  
  106.    1.  I N T R O D U C T I O N
  107.  
  108.  
  109.    FEATURES
  110.  
  111.    Welcome to STRG Screen Utilities!  
  112.  
  113.    You have just obtained a copy of the highest performance string processing 
  114.    routines available today for Turbo Pascal 5.5 (TP55).  Both novice and 
  115.    professional programmers will appreciate these simple and very powerful 
  116.    utilities that gives you ultimate speed for string-intensive programs.
  117.    
  118.    Here are some of the features you will discover:
  119.  
  120.      . Extremely-high speed techniques have been used to create 
  121.        the fastest processing possible.
  122.      . 108 routines process strings, characters, and all types of 
  123.        numbers.  Several combinations of operations have been 
  124.        provided that are extremely fast for case, classification, 
  125.        comparison, conversions, copy, count, delete, format, 
  126.        justification, membership, parse, replace, search, sort, 
  127.        tabbing, ASCIIZ, many with match/ignore case and many 
  128.        more.
  129.      . Uses many of the same identifiers as C standard routines.
  130.      . Much faster than Pascal and C standard routines.
  131.      . Easy to remember routine identifiers.
  132.      . Source code compiles in either Turbo Pascal or 
  133.        QuickPascal.
  134.      . Only 6.3k bytes of code if all 108 routines are used.
  135.      . Optimized by the compiler and drops unused code.
  136.      . Used in all other Eagle products.
  137.  
  138.  
  139.    USING THE MANUALS
  140.  
  141.    Disk Based Guides - The manuals for STRG are on disk so that you can 
  142.    conveniently scan for the topic you are seeking.  You can do this with any 
  143.    list or search utility with a search function.  You can also make a printed 
  144.    copy.  If you have not already printed this manual, refer to the READ.ME 
  145.    file for instructions.  At the present time, no bound manuals are being 
  146.    offered with registration.
  147.  
  148.    User's Guide - This manual, the one your are reading now, assumes that as a 
  149.    programmer you are already familiar with Pascal and that you have a working 
  150.    knowledge of your disk operating system (DOS).  It will provide you the 
  151.    judgment and techniques for faster text processing.
  152.  
  153.    Reference Guide - This manual describes in detail all procedures, functions 
  154.    and variables used in STRG.  It is alphabetically arranged for easy access 
  155.    in a format similar to the compiler reference manual.  Use this manual when 
  156.    you have become familiar with the basic principles in the user's guide.
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.    Chapter 1, Introduction                                             Page 3
  164.    STRG String Utilities                            User's Guide, Version 5.5
  165.  
  166.  
  167.    LICENSING
  168.  
  169.    Registration - These utilities and the documentation have been released for 
  170.    distribution as Shareware.  You have been given the chance to sample the 
  171.    full capability of STRG without risk!  If you find that STRG is a valuable 
  172.    tool, then you are expected to register.  You will find a reasonable 
  173.    licensing schedule found in LICENSE.ARC to meet private or commercial 
  174.    needs.  When registering, be sure to specify the compiler and version you 
  175.    you are using.
  176.  
  177.    Source Code - All registered users will receive source code when the signed 
  178.    license agreement is returned with the registration.
  179.  
  180.  
  181.    CUSTOMER SERVICE
  182.  
  183.    If you have questions, comments, or suggestions, the Eagle can be contacted 
  184.    by four means - (1) CompuServe, (2) telephone, (3) The Eagle BBS, or 
  185.    (4) mail.
  186.  
  187.    CompuServe - The most dependable way to contact the Eagle is through 
  188.    CompuServe.  James (Jim) H. LeMay has written this version of STRG, but the 
  189.    person to reach is Jordan Gallagher who can be contacted on the Borland 
  190.    Forum by typing GO BPROGA from the CompuServe main menu.  You will enter 
  191.    the Forum for Turbo Pascal.  You can contact Jordan with his PPN number of 
  192.    73557,2342.  Messages can also be left through EasyPlex.
  193.  
  194.    Telephone - Jordan can also be reached by phone at (214) 539-7855 on 
  195.    weekdays and Saturday from 9:00 a.m. to 8:00 p.m CST.
  196.  
  197.    The Eagle BBS - You can also contact us on our 24-hour BBS at (214) 539-
  198.    9878, 1200/2400 N81.
  199.  
  200.    Mail - For registration or problems, please write:
  201.  
  202.        Eagle Performance Software
  203.        P.O. Box 292786
  204.        Lewisville, TX  75029-2786
  205.  
  206.    In your written request for resolving problems, be sure to include:
  207.  
  208.      . A 5 1/4 inch diskette of compilable source code of the problem.
  209.      . The Eagle product and version number.
  210.      . The computer make and model.
  211.      . The type of video card, video monitor and keyboard.
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.    Chapter 1, Introduction                                             Page 4
  225.    STRG String Utilities                            User's Guide, Version 5.5
  226.  
  227.  
  228.    ASP
  229.  
  230.    STRG is a shareware program conforming to the standards of the Association 
  231.    of Shareware Professionals (ASP).  You can get more information about ASP 
  232.    by writing to:
  233.     
  234.      Association of Shareware Professionals
  235.      P.O. Box 5786
  236.      Bellevue,WA 98006
  237.  
  238.    This program is produced by a member of the Association of Shareware 
  239.    Professionals (ASP).  ASP wants to make sure that the shareware principle 
  240.    works for you.  If you are unable to resolve a shareware-related problem 
  241.    with an ASP member by contacting the member directly, ASP may be able to 
  242.    help.  The ASP Ombudsman can help you resolve a dispute or problem with an 
  243.    ASP member, but does not provide technical support for member's products.  
  244.    Please write to:
  245.  
  246.      ASP Ombudsman
  247.      P.O. Box 5786
  248.      Bellevue,WA 98006
  249.  
  250.    or send a CompuServe message via EasyPlex to ASP Ombudsman 7007,3536.
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.    Chapter 1, Introduction                                             Page 5
  286.    STRG String Utilities                            User's Guide, Version 5.5
  287.  
  288.  
  289.    2.  G E T T I N G   S T A R T E D
  290.  
  291.    This section will acquaint you with the files on disk and show you a 
  292.    brief demonstration.  You will also run your first program with STRG and 
  293.    then become familiar with all of the utilities.
  294.  
  295.  
  296.    DISTRIBUTION FILES
  297.  
  298.    In this version, STRG55.ARC contains:
  299.  
  300.      Strg55  .tpu:  Compiled unit of 5800 lines of assembly for TP55.
  301.      Strg55- .pas:  Partial source code for STRG55.TPU.  (MASM source 
  302.                     code and object files are not included.)
  303.      Strg55  .doc:  This document - a user's guide to STRG.
  304.      StrgRef .doc:  STRG Reference Guide document covering each 
  305.                     procedure and variable in detail.
  306.      Rate55  .pas:  High-precision timer to test speed of routines.
  307.      License .arc:  ARC file containing license agreements.
  308.  
  309.  
  310.    SIMPLE PROGRAMMING
  311.  
  312.    First Program - Let's write a short program to see how simple it is to 
  313.    write with STRG.  First, do the following steps:
  314.  
  315.      1. Copy STRG55.TPU to STRG.TPU for the compiler.
  316.      2. While in the compiler editor, enter the following code:
  317.  
  318.         {$E+,N+}
  319.         uses Crt,Strg;
  320.         var s1,s2: string;
  321.         begin
  322.           s1 := '(c)1989 Eagle Performance Software';
  323.           StrUpr (s1);
  324.         end.
  325.  
  326.    Assuming you have already copied STRG55.TPU to STRG.TPU, compile and run 
  327.    the code.  Using the watch window, check out the value of s1 and see that 
  328.    it is now completely upper case which is what the StrUpr procedure does.  
  329.    The StrUpr identifier may already be familiar to you - it is the same one 
  330.    used in C.  Many of the identifiers used in the STRG unit use identifiers 
  331.    that are similar in C, and using the same principles, other names were also 
  332.    created.
  333.  
  334.  
  335.    PROCEDURES AND FUNCTIONS
  336.  
  337.    STRG has many routines and are all described in detail in the reference 
  338.    manual.  But to get a full scope of the routines available, here is a 
  339.    brief survey of all the utilities arranged by application:
  340.  
  341.    Operations - These procedures operate directly on the characters in the 
  342.    string:
  343.  
  344.  
  345.  
  346.    Chapter 2, Getting Started                                          Page 6
  347.    STRG String Utilities                            User's Guide, Version 5.5
  348.  
  349.  
  350.       StrLwr    - convert to lower case.
  351.       StrUpr    - convert to upper case.
  352.       StrRev    - reverses order of characters.
  353.       StrRoll   - rolls characters left or right.
  354.       StrSort   - sorts characters in ascending order.
  355.  
  356.    Insert and Delete - These procedures provide different methods for 
  357.    inserting or delete substrings or characters:
  358.  
  359.       ChrDel    - deletes all occurrences of a given character.
  360.       ChrDelL   - deletes all leading (Left) characters.
  361.       ChrDelR   - deletes all trailing (Right) characters.
  362.       ChrPadC   - pads characters left and right to center the field.
  363.       ChrPadL   - pads leading (Left) characters to fit in a field.
  364.       ChrPadR   - pads trailing (Right) characters to fit in a field.
  365.       StrCut    - truncates strings over a given length.
  366.       StrIns    - inserts a substring.
  367.  
  368.    Placement - These procedures efficiently place strings in memory with a 
  369.    single copy.
  370.  
  371.       StrCat    - appends one string with another.
  372.       StrCatX   - appends one string with a substring of another.
  373.       StrCopy   - copies a substring to create a new string.
  374.       StrMove   - simple string move.
  375.       StrOver   - overwrites a string at a given index with another substring 
  376.                   and fills any gap with spaces.
  377.       StrPeek   - copies an array from memory into a string.
  378.       StrPoke   - copies a string as an array without the length byte.
  379.  
  380.    Patterns - These procedures create strings with repetitive patterns:
  381.  
  382.       StrFill   - fills a string with duplicate copies of a substring or 
  383.                   character.
  384.       ChrFill   - fills a string with duplicate copies of a character.
  385.       StrEnum   - enumerates a string of characters in ascending or descending 
  386.                   order.
  387.  
  388.    Position - These procedures find the position of a character using 
  389.    different strategies:
  390.  
  391.       ChrPosL   - finds the Nth occurrence from the LEFT.
  392.       ChrPosLI  - finds the Nth occurrence from the LEFT ignoring case.
  393.       ChrPosR   - finds the Nth occurrence from the RIGHT.
  394.       ChrPosRI  - finds the Nth occurrence from the RIGHT ignoring case.
  395.       ChrPosX   - finds the first occurrence from the LEFT starting at indeX.
  396.       ChrPosXI  - finds the first occurrence from the LEFT starting at indeX 
  397.                   and ignoring case.
  398.  
  399.    Similar to the above procedures, these find the position of a substring or 
  400.    character using different strategies:
  401.  
  402.       StrPosL   - finds the Nth occurrence from the LEFT.
  403.       StrPosLI  - finds the Nth occurrence from the LEFT ignoring case.
  404.       StrPosR   - finds the Nth occurrence from the RIGHT.
  405.  
  406.  
  407.    Chapter 2, Getting Started                                          Page 7
  408.    STRG String Utilities                            User's Guide, Version 5.5
  409.  
  410.  
  411.       StrPosRI  - finds the Nth occurrence from the RIGHT ignoring case.
  412.       StrPosX   - finds the first occurrence from the LEFT starting at indeX.
  413.       StrPosXI  - finds the first occurrence from the LEFT starting at indeX 
  414.                   and ignoring case.
  415.  
  416.    Quantity - These procedures find the total count of a given character or 
  417.    substring in a string:
  418.  
  419.       ChrQty    - count of a given character.
  420.       ChrQtyI   - count of a given character ignoring case.
  421.       StrQty    - count of a given substring.
  422.       StrQtyI   - count of a given substring ignoring case.
  423.  
  424.    Comparison - These procedures compare two substrings for greater than, less 
  425.    than, or equal result.  The optional indexes can also be obtained:
  426.  
  427.       StrCmp  - compares two substrings matching case.
  428.       StrCmpI - compares two substrings ignoring case.
  429.  
  430.    Find and Replace - These procedures find a given character or substring in 
  431.    a string and replace it with another.
  432.  
  433.       ChrRepl  - find and replace a character matching case.
  434.       ChrReplI - find and replace a character ignoring case.
  435.       StrRepl  - find and replace a character or substring matching case.
  436.       StrReplI - find and replace a character or substring ignoring case.
  437.  
  438.    Membership - These procedures search membership or non-membership in a 
  439.    string:
  440.  
  441.       StrBrk    - finds the first character that is a member.
  442.       StrSpn    - finds the first character that is not a member and returns 
  443.                   the span of membership.
  444.       StrMemb   - reduces a string to individual membership in ascending 
  445.                   order.
  446.  
  447.    Parsing - These routines find words separated by spaces:
  448.  
  449.       WrdQty    - counts the number of words in a string.
  450.       WrdPosL   - finds the Nth word from the LEFT.
  451.       WrdPosR   - finds the Nth word from the RIGHT.
  452.       WrdPosLX  - finds the Nth word from the LEFT starting at indeX.
  453.       WrdPosRX  - finds the Nth word from the RIGHT starting at indeX.
  454.       WrdL      - parses the Nth word from the LEFT.                   
  455.       WrdR      - parses the Nth word from the RIGHT.                  
  456.       WrdLX     - parses the Nth word from the LEFT starting at indeX. 
  457.       WrdRX     - parses the Nth word from the RIGHT starting at indeX.
  458.       WrdParse  - generic parsing routine parses a word between any two 
  459.                   delimiters.
  460.       WrdToken  - generic parsing routine parses a word between any two groups 
  461.                   of delimiters.
  462.  
  463.    Conversion - These routines convert numbers and strings into other common 
  464.    forms:
  465.  
  466.  
  467.  
  468.    Chapter 2, Getting Started                                          Page 8
  469.    STRG String Utilities                            User's Guide, Version 5.5
  470.  
  471.  
  472.       StrHex    - converts scalars into hex strings.
  473.       StrBin    - converts scalars into binary strings.
  474.       ValBin    - converts binary strings into scalars.
  475.       ValHex    - converts hex strings into scalars.
  476.       StrDeTab  - expands tabs into spaces.
  477.       StrReTab  - reduces spaces into tabs.
  478.       AscStr    - converts strings into ASCIIZ strings.
  479.       LnStr     - converts strings into ASCII text strings.
  480.       StrAsc    - converts ASCIIZ strings into Pascal strings.
  481.       StrLn     - converts ASCII text strings into Pascal strings.
  482.  
  483.    Justification - These functions justify strings with spaces:
  484.  
  485.       StrJC     - Center justification
  486.       StrJL     - Left   justification
  487.       StrJR     - Right  justification
  488.  
  489.    Classification - These boolean functions classify characters within a given 
  490.    group in the lower ASCII table (<#128):
  491.  
  492.       IsAlNum   - alpha-numeric
  493.       IsAlpha   - alphabetic
  494.       IsASCII   - lower ASCII table
  495.       IsCntrl   - printer control character
  496.       IsDigit   - numbers zero through nine
  497.       IsDOS     - DOS directory character
  498.       IsFile    - DOS file name character
  499.       IsGraph   - a "black" printable character
  500.       IsLower   - lower case
  501.       IsPath    - DOS drive, path, and file name character
  502.       IsPrint   - printable character
  503.       IsPunct   - punctuation character
  504.       IsReal    - real number character
  505.       IsSigned  - signed number
  506.       IsSpace   - non-printing paper-movement character
  507.       IsUpper   - upper case
  508.       IsXDigit  - hex digit
  509.  
  510.    Standard - As a bonus, automatic replacements of the Pascal standard 
  511.    routines are included:
  512.  
  513.       Copy      - copies a substring up to 25% faster.
  514.       Delete    - deletes a substring up to 5 times faster.
  515.  
  516.    Str Function Forms - As another bonus, function forms of the standard Str 
  517.    procedure are provided for convenience:
  518.  
  519.       StrC      - converts Comp to string
  520.       StrCF     - converts Comp to string in a fixed Field
  521.       StrCFD    - converts Comp to string in a fixed Field with a specified 
  522.                   number of Decimals
  523.       StrD      - converts Double to string
  524.       StrDF     - converts Double to string in a fixed Field
  525.       StrDFD    - converts Double to string in a fixed Field with a specified 
  526.                   number of Decimals
  527.  
  528.  
  529.    Chapter 2, Getting Started                                          Page 9
  530.    STRG String Utilities                            User's Guide, Version 5.5
  531.  
  532.  
  533.       StrE      - converts Extended to string
  534.       StrEF     - converts Extended to string in a fixed Field
  535.       StrEFD    - converts Extended to string in a fixed Field with a 
  536.                   specified number of Decimals
  537.       StrL      - converts LongInt to string
  538.       StrLF     - converts LongInt to string in a fixed Field
  539.       StrR      - converts Real to string
  540.       StrRF     - converts Real to string in a fixed Field
  541.       StrRFD    - converts Real to string in a fixed Field with a specified 
  542.                   number of Decimals
  543.       StrS      - converts Single to string
  544.       StrSF     - converts Single to string in a fixed Field
  545.       StrSFD    - converts Single to string in a fixed Field with a specified 
  546.                   number of Decimals
  547.  
  548.    For a full description of each routine with its parameters, please refer to 
  549.    STRGREF.DOC for a summary of details and examples.
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.    Chapter 2, Getting Started                                          Page 10
  591.    STRG String Utilities                            User's Guide, Version 5.5
  592.  
  593.  
  594.    3.  P H I L O S O P H Y
  595.  
  596.    In this section, you will learn the philosophy behind the development of 
  597.    STRG and how to plan your programming for the highest speeds in string 
  598.    processing.
  599.  
  600.  
  601.    UNIT DESIGN
  602.  
  603.    Identifiers - Since there is an abundance of routines in this unit, 
  604.    remembering the right identifier could be a problem.  But the unit was 
  605.    designed to make it easy with common letters and phrases that are already 
  606.    familiar to you.  All identifiers will have one of the following mnemonics:
  607.  
  608.       Str - for routines that can process both characters and 
  609.             substrings.  The majority of routines have this one to help 
  610.             you correlate the routine with the STRG unit.
  611.       Chr - for an alternative to a Str- routine for processing 
  612.             characters only.
  613.       Wrd - for word parsing routines.
  614.       Is  - for character classification routines.
  615.       Val - for string-to-number conversion routines.
  616.  
  617.    To save space, the documentation will refer to a group of routines using 
  618.    the DOS wildcard characters "*" or "?".  For example, Is* would mean any 
  619.    character classification routine.  In addition, some identifiers also have 
  620.    some common suffixes:
  621.  
  622.       C - means "to center".
  623.       I - means "ignore case".
  624.       L - means "from the left".
  625.       R - means "from the right".
  626.       X - means "indeX".
  627.  
  628.    and if two of them appear together, they will always appear in the order of 
  629.    C-L-R-X-I.
  630.  
  631.    Speed - This unit was specifically designed for speed and every routine has 
  632.    been written in assembly.  These routines easily out perform any similar 
  633.    routines in the Pascal standard library or code written in Pascal.  
  634.    Special techniques have been included to increase speed as much as 
  635.    possible.  The longer the strings, the greater the results can be seen.  
  636.    When you use STRG, a speed increase of 300% would be typical.
  637.  
  638.    Optimization - Almost all routines were placed in separate object files so 
  639.    that the compiler will optimize the code size of your programs.  This may 
  640.    take a second or two longer to compile, but the results are worth it.
  641.  
  642.  
  643.    PROGRAM DESIGN
  644.  
  645.    Procedures vs. Functions - One of the advantages of using a string function 
  646.    is the legibility that it gives the source code.  However, it also comes 
  647.    with the disadvantage of reduced speed from having to make temporary copies 
  648.    in the stack.  The only reason for this is just to make sure that the final 
  649.  
  650.  
  651.    Chapter 3, Philosophy                                               Page 11
  652.    STRG String Utilities                            User's Guide, Version 5.5
  653.  
  654.  
  655.    destination can handle the final string length.  For long strings, a lot of 
  656.    processing is going on just to check for length limits. 
  657.  
  658.    However, procedures can write directly to the destination and overcome the 
  659.    need for temporary copies.  Most of the routines in STRG are procedures for 
  660.    this reason. 
  661.  
  662.    Writing Code - If you write your code carefully, you can easily increase 
  663.    your speed by avoiding functions.  For instance, the following code looks 
  664.    very simple:
  665.  
  666.       string1 := string1 + string2;
  667.  
  668.    but in fact it uses functions to achieve the result.  If you use the 
  669.    following code:
  670.  
  671.       StrCat (string1,string2,SizeOf(string1));
  672.  
  673.    you will get the same results, but over 3 times faster!  So, where speed is 
  674.    important, avoid the use of string functions.
  675.  
  676.    Formatting Functions - Yet, there are a few routines that are string 
  677.    functions such as StrJ* and StrHex.  These are final formatting routines 
  678.    that are usually used to provide a final output to screen or disk after 
  679.    most string-intensive processing has been completed.  The resulting strings 
  680.    are usually short as well, so there is not much of a speed reduction 
  681.    making them functions rather than procedures.
  682.  
  683.    Str vs. Chr - Several of the Str* routines like StrQty have built-in 
  684.    routines for processing the special case of a single character just like 
  685.    its counterpart ChrQty.  So there is no need to use both routines.  
  686.    However, if you know that your routines only process characters, then 
  687.    certainly use the Chr* routines as they have a definite speed and code 
  688.    advantage.  This is especially true for ignoring case.  The Chr*I routines 
  689.    analyze each character while Str*I converts the entire string or substring 
  690.    before processing.
  691.  
  692.    Membership vs. Classification - The membership routines are quite fast when 
  693.    the membership substring is relatively short (<15 chars).  If the substring 
  694.    is longer, then it may be faster to consider using the Is* routines or 
  695.    creating your own sets.  Using the rate timer program, RATE55.PAS, included 
  696.    in this package is the best way to tell which one is better for you.
  697.  
  698.    Case Conversion - If you repeatedly use the same string for ignore-case 
  699.    processing, then it would be best to create a temporary string with its 
  700.    case fully converted.  The matching-case routines would then give you a 
  701.    much faster result.  When using either StrLwr or StrUpr, use the one that 
  702.    requires the least amount of conversion in your string.  For example, if 
  703.    your strings are mostly lower case, use the StrLwr routine.  This will 
  704.    increase your speed a few percent.
  705.  
  706.    Pascal vs. C - Although C has the advantage of long length ASCIIZ strings 
  707.    for data storage space, the performance doesn't even come close to Pascal 
  708.    strings with it's calculated length byte.  With STRG and its ASCIIZ 
  709.    conversion routines, you can now have the advantage of both speed and data 
  710.  
  711.  
  712.    Chapter 3, Philosophy                                               Page 12
  713.    STRG String Utilities                            User's Guide, Version 5.5
  714.  
  715.  
  716.    storage savings.
  717.  
  718.    Alignment - STRG does the most possible to speed up odd-byte alignment of 
  719.    data, but statistically in string moves, some odd-byte alignment will occur 
  720.    which just slows the processing down by a few percent.  However, it is 
  721.    strongly recommended that all string variables are aligned using the $A+ 
  722.    compiler directive.  This can improve your speed about 30%.  If you cannot 
  723.    do this, at least place all of your "even" sized data first in your VAR 
  724.    list and then manually match up the byte size variables with odd size ones 
  725.    so they will self-align.
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.    Chapter 3, Philosophy                                               Page 13
  774.    STRG String Utilities                            User's Guide, Version 5.5
  775.  
  776.  
  777.    NUMBER TO STRING CONVERSION
  778.  
  779.    Convenience - The Str* number formatting routines such as StrRFD have been 
  780.    provided as a convenience and not for speed improvement.  When you want to 
  781.    knock out code in a hurry and are not concerned with speed, these 
  782.    formatting routines can provide better legibility in your code.  In the 
  783.    long run, they can also save code.  Pascal handily converts numbers into 
  784.    strings with the Str procedure.  For example:
  785.  
  786.      var MyNumber: integer;
  787.          MyString: string;
  788.      begin
  789.        Str (MyNumber:7,MyString);
  790.        Qwik.Qwrite ( 1, 1,SameAttr,MyString);
  791.      end.
  792.  
  793.    But this means that a data area must be reserved and the code isn't as 
  794.    readable as it could be.
  795.  
  796.    Str* Functions - Instead, STRG lets you use a function form of Str:
  797.  
  798.      uses Qwik, Strg;
  799.      var MyNumber: integer;
  800.      begin
  801.        Qwik.Qwrite ( 1, 1,SameAttr,StrLF(MyNumber,7));
  802.      end.
  803.  
  804.    Just like WriteLn, this lets the number remain in the Qwrite statement.  
  805.    The Str* functions actually use the System.Str procedure from to do the 
  806.    conversion.  But these functions were made so that they don't recopy the 
  807.    intermediate string for the greatest speed.  The code usage is also 
  808.    reduced.
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.    Chapter 3, Philosophy                                               Page 14
  835.    STRG String Utilities                            User's Guide, Version 5.5
  836.  
  837.  
  838.    A P P E N D I X   A :  O T H E R   P R O D U C T S
  839.  
  840.  
  841.    Eagle Performance Software has developed identical products for Turbo C 
  842.    (TC), Turbo Pascal (TP), Quick C (QC), Microsoft C (MSC), and QuickPascal 
  843.    (QP).  Our pledge is to provide you quality products with unparalleled 
  844.    performance and ease of use.  All registered users receive the complete 
  845.    source code when a signed license agreement is returned.
  846.  
  847.  
  848.    QWIK
  849.  
  850.    QWIK - For direct screen video, QWIK is the highest performance screen 
  851.    writing tools available today for all text modes in any video 
  852.    configuration.  QWIK provides capabilities far beyond those in the 
  853.    unit/library that comes with your compiler.   Here are some of the 
  854.    features:
  855.                 
  856.      - Writes on all IBM compatible computers, displays and adapters 
  857.        including MDA, CGA, EGA, MCGA, VGA, 8514/A, Hercules and 3270 PC.
  858.      - Superior video detection routine.
  859.      - Eliminates snow and flicker.
  860.      - Writes directly to the screen in absolute rather than relative 
  861.        coordinates.
  862.      - Writes in all text modes and column modes.
  863.      - Writes on all video pages.
  864.      - Writes on virtual screens in RAM.
  865.      - Writes text and attribute, text only, or attribute only.
  866.      - Reads strings, characters and attributes.
  867.      - Uses End-Of-String (EOS) marker for quick string chaining.
  868.      - Provides standardized cursor shapes for all adapters.
  869.      - Enhanced cursor movement.
  870.      - Compatible with DESQview and similar multitasking environments.
  871.      - Over 650% faster than standard direct screen writing.
  872.      - Only 2.7k bytes of code if all 43 utilities are used.
  873.      - Optimized by the compiler and drops unused code.
  874.      - Used in all other Eagle products.
  875.      - Excellent documentation like this document.
  876.  
  877.    Here are the product versions:
  878.  
  879.       File name    CIS Name    Compiler 
  880.       -----------  ----------  ---------
  881.       QWIK55.ARC   QWIK55.ARC  TP       
  882.       QWIKQ10.ARC  QWKQ10.ARC  QP
  883.       QWIKC20.ARC  QWKC20.ARC  TC/QC/MSC
  884.  
  885.  
  886.    WNDW
  887.  
  888.    WNDW - For multi-level virtual windows, WNDW is the highest performance 
  889.    window utilities available today.  It offers very powerful utilities for 
  890.    full window control and management you probably never thought possible.   
  891.    They are simple and yet very powerful with high speed and tight code.  With 
  892.    WNDW, you can choose the absolute writing routines of QWIK, the window-
  893.  
  894.  
  895.    Appendix A: Other Products                                          Page 15
  896.    STRG String Utilities                            User's Guide, Version 5.5
  897.  
  898.  
  899.    relative writing routines of WNDW, and even customize your own.  Here are 
  900.    some of the features you will discover:
  901.  
  902.      - Uses the powerful direct screen writing routines of QWIK.           
  903.      - Up to 254 fixed or virtual windows can be on the screen at one 
  904.        time.
  905.      - Extremely high-speed virtual screens in RAM (up to 40 times 
  906.        faster).
  907.      - Virtual windows are fully updated on screen, even if covered.  
  908.        Screens can scroll underneath one another right on the screen at 
  909.        very high speeds!       
  910.      - Virtual windows have virtual titles.                                
  911.      - Fully supported hidden windows saved in RAM.                        
  912.      - Fully supports all video pages.                                     
  913.      - Adjustable-rate moving, resizing, and scrolling.                    
  914.      - All windows can be randomly accessed, not just stacked or tiled.    
  915.      - 28 window-relative writing routines.                                
  916.      - 15 different border styles with shadow and zoom effects.            
  917.      - Full line drawing procedures.                                       
  918.      - Full cursor mode control for each window.                           
  919.      - Writes in all text modes and column modes.                          
  920.      - Only 13k bytes of code if all 69 utilities are used.                
  921.      - Used in all other Eagle products.                                   
  922.      - Excellent documentation like this document.
  923.  
  924.    Here are the product versions:
  925.  
  926.       File name    CIS Name    Compiler  
  927.       -----------  ----------  --------  
  928.       WNDW55.ARC   WNDW55.ARC  TP       
  929.       WNDWQ10.ARC  WNDQ10.ARC  QP
  930.       WNDWC20.ARC  WNDC20.ARC  TC/QC/MSC
  931.  
  932.  
  933.    PULL
  934.  
  935.    PULL - For multi-level pull-down menus, PULL is fully featured and fully 
  936.    configurable.  Includes execute, single, and multiple choice menus, 
  937.    unlimited nested submenus, data entry windows, help windows, directory 
  938.    windows, message system, and fully completed interfaces.  Some of the 
  939.    features are:
  940.  
  941.      - Uses QWIK and WNDW.
  942.      - Work window(s) and complete interface for menus
  943.      - Pull-down menus with 3 menu modes and 7 line modes
  944.      - Pull-down file directory
  945.      - Highlighted command letters
  946.      - Unlimited levels of submenus
  947.      - Unlimited data entry windows for 9 types of data
  948.      - Data entry for the work window(s)
  949.         Free field entry with either fixed column or flexible column        
  950.          length.
  951.         Full editing capability including insert cursor mode
  952.         Full field selection with cursor keys
  953.         Automatic NumLock for numerical data entry
  954.  
  955.  
  956.    Appendix A: Other Products                                          Page 16
  957.    STRG String Utilities                            User's Guide, Version 5.5
  958.  
  959.  
  960.         Right or left justification for data entry output
  961.         Error messages for invalid data entries
  962.         Error messages for data entries out of range
  963.      - Automatic sizes and locations for menus.
  964.      - Operation by cursor 
  965.        keys or command keys
  966.      - Pull/Pop between work window and nested submenu(s)
  967.      - Programmable control of pull and pop sequences
  968.      - Context-sensitive help
  969.      - Message lines for prompts and processing
  970.      - Full working shell for user development
  971.      - Excellent documentation like this document.
  972.  
  973.    Here are the product versions:
  974.  
  975.       File name    CIS Name    Compiler
  976.       -----------  ----------  --------
  977.       PULL55.ARC   PULL55.ARC  TP
  978.       PULLQ10.ARC  PULQ10.ARC  QP
  979.       PULLC20.ARC  PULC20.ARC  TC/QC/MSC
  980.  
  981.  
  982.    ON-LINE SERVICES
  983.  
  984.    CompuServe - All updated files and later versions can be found on the 
  985.    CompuServe Borland Forums (GO BPROGA for TP and GO BPROGB for TC) or the 
  986.    Microsoft Systems Forum (GO MSSYS for QP, QC, and MSC).
  987.  
  988.    The Eagle BBS - You can also get the latest files on our 24-hour BBS at 
  989.    (214) 539-9878, 1200/2400 N81.
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.    Appendix A: Other Products                                          Page 17
  1018.    STRG String Utilities                            User's Guide, Version 5.5
  1019.  
  1020.  
  1021.    A P P E N D I X   B :  R E V I S I O N   H I S T O R Y
  1022.  
  1023.  
  1024.    Version 5.5 (01-02-90):
  1025.      Initial release.
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.    Appendix B: Revision History                                        Page 18
  1079.    STRG String Utilities                            User's Guide, Version 5.5
  1080.  
  1081.  
  1082.    A P P E N D I X   C :  R E F E R E N C E S
  1083.  
  1084.  
  1085.    REFERENCES
  1086.  
  1087.    Trademarks - Turbo Pascal and Turbo C are trademarks of Borland 
  1088.    International.  QuickPascal, Quick C, and Microsoft C are trademark of 
  1089.    Microsoft Corporation.
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.    Appendix C: References                                              Page 19
  1140.