home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional Developers Kit 1992 November / Disc01 / Disc01.mdf / cppbeta / ibmcli / istring.hp_ / ISTRING.HPP
Encoding:
C/C++ Source or Header  |  1992-10-26  |  38.4 KB  |  1,057 lines
  1. /*==============================================================================
  2.  Module Name: istring.hpp
  3.  
  4.  Description:
  5.    Declaration for the "string" class IString.
  6.  
  7.  Copyright: (C) Copyright IBM Corporation 1992
  8.             All Rights Reserved
  9.             Licensed Materials = Property of IBM
  10.  
  11.  Usage:
  12.    This header file is #include-d in other modules requiring
  13.    use of the class IString.
  14.  
  15.  Notes:
  16.  
  17.  History:
  18.    flag yymmdd who description
  19.    ---- ------ --- -----------------------------------------------------------
  20.         920710 law Revised for ICLUI
  21. ==============================================================================*/
  22. #if !defined( _ISTRING_ )
  23.   #define _ISTRING_
  24.  
  25. #if !defined( _IBASETYP_ )
  26.   #include <ibasetyp.hpp>
  27. #endif
  28.  
  29. // Forward declarations for classes referenced herein.
  30. class IStringTest;
  31. class IBuffer;
  32. class ostream;
  33.  
  34. /*------------------------------------------------------------------------------
  35.  Class Name: IString
  36.  
  37.  Class Hierarchy:
  38.    IString
  39.  
  40.  Description:
  41.    Objects of this class replace conventional C "strings"
  42.    (i.e., char* pointers).
  43.  
  44.  Usage:
  45.    Objects of this class are essentially arrays of characters.
  46.  
  47.    IStrings provide the following function beyond that typically
  48.    granted by standard C char* arrays and the string.h library
  49.    functions:
  50.  
  51.    o  No restrictions on string contents (i.e., strings can
  52.       contain null characters)
  53.    o  Automatic conversion from/to numeric types
  54.    o  Automatic deletion of string buffer when the IString is
  55.       deleted
  56.    o  Full support for all comparison operators
  57.    o  Full support for all bit-wise operators
  58.    o  Full support for concatenation using the more natural "+"
  59.       operator
  60.    o  String data testing (for characters, digits, hex digits,
  61.       etc.)
  62.    o  Full complement of string manipulation functions (center,
  63.       left/right justify, leading/trailing char stripping,
  64.       substring deletion, insertion of strings, etc.)
  65.    o  Full complement of correponding string manipulation functions
  66.       that return a new IString, rather than modifying the receiver
  67.    o  Full complement of string searching functions (index of
  68.       string, last index of string, etc.)
  69.    o  Word manipulation (index of word, search for word phrase,
  70.       etc.)
  71.  
  72.  Notes:
  73.    1. DBCS and NLS support is "enabled" but not yet implemented.
  74.  
  75.  Related Topics:
  76.    IStringTest
  77.    IBuffer
  78. ------------------------------------------------------------------------------*/
  79. class IString {
  80. public:
  81. /*---------------------------- Instance Creation -------------------------------
  82.  
  83.    There are four basic categories of constructors:
  84.  
  85.    1. Construct a null string.
  86.  
  87.    2. Construct a string with the Ascii representation of a given
  88.       numeric value (supporting all flavors of int and double).
  89.  
  90.    3. Construct a string with a copy of the given character data
  91.       (supporting Ascii-Z strings, characters, and IStrings).
  92.  
  93.    4. Construct a string with contents consisting of copies of up
  94.       to three buffers of arbitrary data (void*).  Optionally,
  95.       only the length need be provided, in which case the IString
  96.       contents will be initialize to a given pad character (default
  97.       is a blank).
  98. ------------------------------------------------------------------------------*/
  99. IString ( );
  100. IString ( const IString & );
  101.  
  102. IString ( int );
  103. IString ( unsigned );
  104. IString ( long );
  105. IString ( unsigned long );
  106. IString ( short );
  107. IString ( unsigned short );
  108.  
  109. IString ( double );
  110.  
  111. IString ( char );
  112. IString ( unsigned char );
  113. #if !defined( __BORLANDC__ )
  114. IString ( signed char );
  115. #endif
  116.  
  117. IString ( const char * );
  118. IString ( const unsigned char * );
  119. #if !defined( __BORLANDC__ )
  120. IString ( const signed char * );
  121. #endif
  122.  
  123. IString ( const void *pBuffer1,
  124.           unsigned    lenBuffer1,
  125.           char        padCharacter = ' ' );
  126. IString ( const void *pBuffer1,
  127.           unsigned     lenBuffer1,
  128.           const void  *pBuffer2,
  129.           unsigned     lenBuffer2,
  130.           char         padCharacter = ' ' );
  131. IString ( const void *pBuffer1,
  132.           unsigned     lenBuffer1,
  133.           const void  *pBuffer2,
  134.           unsigned     lenBuffer2,
  135.           const void  *pBuffer3,
  136.           unsigned     lenBuffer3,
  137.           char         padCharacter = ' ' );
  138.  
  139. ~IString ( );
  140.  
  141. /*-------------------------------- Displaying ----------------------------------
  142.  
  143.    This function can be used to display a IString on an output
  144.    stream, using the traditional left-shift operator (<<).
  145. ------------------------------------------------------------------------------*/
  146. friend ostream
  147.  &operator << ( ostream       &aStream,
  148.                 const IString &aString );
  149.  
  150. /*--------------------------------- Testing ------------------------------------
  151.  
  152.    These functions test the characters that comprise the string.
  153.  
  154.    isAlnum       - true iff all characters are in
  155.                    {'A'-'Z','a'-'z','0'-'9'}.
  156.    isAlpha       - true iff all characters are in {'A'-'Z','a'-'z'}.
  157.    isAscii       - true iff all characters are in {0x00-0x7F}.
  158.    isCntrl       - true iff all characters are in {0x00-0x1F,0x7F}.
  159.    isDigits      - true iff all characters are in {'0'-'9'}.
  160.    isGraphics    - true iff all characters are in {0x21-0x7E}
  161.    isHexDigits   - true iff all characters are in
  162.                    {'0'-'9','A'-'F','a'-'f'}.
  163.    isBinaryDigits- true iff all characters are either '0' or '1'
  164.    isLowerCase   - true iff all characters are in {'a'-'z'}.
  165.    isPrintable   - true iff all characters are in {0x20-0x7E}.
  166.    isPunctuation - !( isWhiteSpace || isCntrl || isAlnum ).
  167.    isWhiteSpace  - true iff all characters are in {0x09-0x0D,0x20}.
  168.    isUpperCase   - true iff all characters are in {'A'-'Z'}.
  169.  
  170.    isLike        - true iff the receiver matches the argument "pattern"
  171.                    which may contain 'wildcard' characters
  172.  
  173.    isAbbrevFor   - true if the receiver is a valid abbreviation of the
  174.                    argument string.
  175.  
  176.    includes      - true if the receiver contains the argument search
  177.                    string
  178. ------------------------------------------------------------------------------*/
  179. Boolean
  180.   isAlnum        ( ) const,
  181.   isAlpha        ( ) const,
  182.   isAscii        ( ) const,
  183.   isCntrl        ( ) const,
  184.   isDigits       ( ) const,
  185.   isGraphics     ( ) const,
  186.   isHexDigits    ( ) const,
  187.   isBinaryDigits ( ) const,
  188.   isLowerCase    ( ) const,
  189.   isPrintable    ( ) const,
  190.   isPunctuation  ( ) const,
  191.   isUpperCase    ( ) const,
  192.   isWhiteSpace   ( ) const,
  193.  
  194.   isLike ( const IString &aPattern,
  195.            char           zeroOrMore = '*',
  196.            char           anyChar    = '?' ) const,
  197.   isLike ( const char    *pPattern,
  198.            char           zeroOrMore = '*',
  199.            char           anyChar    = '?' ) const,
  200.  
  201.   isAbbrevFor ( const IString &fullString,
  202.                 unsigned       minAbbrevLength = 0 ) const,
  203.   isAbbrevFor ( const char    *pFullString,
  204.                 unsigned       minAbbrevLength = 0 ) const,
  205.  
  206.   includes ( const IString     &aString ) const,
  207.   includes ( const char        *pString ) const,
  208.   includes ( char               aChar   ) const,
  209.   includes ( const IStringTest &aTest   ) const;
  210.  
  211. /*------------------------------- Comparison -----------------------------------
  212.  
  213.    All boolean operators are defined for strings:
  214.  
  215.    ==  true iff the strings are identical
  216.    !=  true iff the strings are not identical
  217.    <   true iff the first string is less than the second,
  218.        applying the standard collating scheme (memcmp)
  219.    >   equivalent to !( string1 <= string2 )
  220.    <=  equivalent to ( string1 < string2) || (string1 == string2 )
  221.    >=  equivalent to !( string1 < string2)
  222.  
  223.    These functions are overloaded so that IStrings can be compared
  224.    to objects of type char*, as well as to other IStrings.
  225. ------------------------------------------------------------------------------*/
  226. friend Boolean
  227.   operator == ( const IString &string1,
  228.                 const IString &string2  ),
  229.   operator == ( const IString &string1,
  230.                 const char    *pString2 ),
  231.   operator == ( const char    *pString1,
  232.                 const IString &string2  ),
  233.  
  234.   operator != ( const IString &string1,
  235.                 const IString &string2  ),
  236.   operator != ( const IString &string1,
  237.                 const char    *pString2 ),
  238.   operator != ( const char    *pString1,
  239.                 const IString &string2  ),
  240.  
  241.   operator <  ( const IString &string1,
  242.                 const IString &string2  ),
  243.   operator <  ( const IString &string1,
  244.                 const char    *pString2 ),
  245.   operator <  ( const char    *pString1,
  246.                 const IString &string2  ),
  247.  
  248.   operator <= ( const IString &string1,
  249.                 const IString &string2  ),
  250.   operator <= ( const IString &string1,
  251.                 const char    *pString2 ),
  252.   operator <= ( const char    *pString1,
  253.                 const IString &string2  ),
  254.  
  255.   operator >  ( const IString &string1,
  256.                 const IString &string2  ),
  257.   operator >  ( const IString &string1,
  258.                 const char    *pString2 ),
  259.   operator >  ( const char    *pString1,
  260.                 const IString &string2  ),
  261.  
  262.   operator >= ( const IString &string1,
  263.                 const IString &string2  ),
  264.   operator >= ( const IString &string1,
  265.                 const char    *pString2 ),
  266.   operator >= ( const char    *pString1,
  267.                 const IString &string2  );
  268.  
  269. /*------------------------------- Conversion -----------------------------------
  270.  
  271.    These functions permit the conversion of a string to various
  272.    other data types.  The types supported are the same set as are
  273.    supported by the IString constructors:
  274.  
  275.      operator char* - returns char* pointer to string contents; note
  276.                       that there are also variants for unsigned char*
  277.                       and signed char*
  278.      asInt          - returns number represented by the string as a
  279.                       long integer
  280.      asUnsigned     - returns number represented by the string as an
  281.                       unsigned long
  282.      asDouble       - returns number represented by the string as a
  283.                       double
  284.  
  285.    In addition, there are a complete set of functions to convert a
  286.    String from any "format" to another.  The "formats" can be any of
  287.      b - a string of binary digits ('0' and '1')
  288.      c - a normal string of characters
  289.      d - a string of decimal digits ('0' thru '9')
  290.      x - a string of hexidecimal digits ('0' thru '9' and 'a/A' thru 'f/F')
  291.  
  292.    The resulting functions are:
  293.  
  294.    The following work if isBinaryDigits() == true; if not, they return a
  295.    null string:
  296.      b2c - changes '01' to '\x01', '00110011' to '3'
  297.      b2d - changes '00011001' to '25', '0001001000110100' to '4660'
  298.      b2x - changes '00011011' to '1b', '10001001000110100' to '11234'
  299.  
  300.    The following will always work:
  301.      c2b - changes 'a' to '01010001', '12' to '11000100110010'
  302.      c2d - changes 'a' to '97', 'ab' to '24930'
  303.      c2x - changes 'a' to '61', 'ab' to '6162'
  304.  
  305.    The following work if isDigits() == true; if not, they return a null
  306.    string:
  307.      d2b - changes '12' to '1100', '123' to '1111011'
  308.      d2c - changes '12' to '\x0c', '56' to '8'
  309.      d2x - changes '12' to 'c', '123' to '7b'
  310.  
  311.    The following work if isHexDigits() == true; if not, they return a
  312.    null string:
  313.      x2b - changes 'a1c' to '101000011100', 'f3' to '11110011'
  314.      x2c - changes '8' to '\x08', '31393932' to '1992'
  315.      x2d - changes 'a1c' to '2588', '10000' to '65536'
  316.  
  317.    There are plain functions by the same name that can be applied to
  318.    a String to return the modified string (without changing the argument
  319.    String).  These are used much like the similar Rexx functions.  E.g.,
  320.  
  321.      aString.c2b();                        // Changes aString.
  322.      String binaryDigits = c2b( aString ); // Leaves aString alone.
  323. ------------------------------------------------------------------------------*/
  324. operator char* ( ) const;
  325. operator unsigned char* ( ) const;
  326. #if !defined( __BORLANDC__ )
  327. operator signed char* ( ) const;
  328. #endif
  329.  
  330. long
  331.   asInt ( ) const;
  332.  
  333. unsigned long
  334.   asUnsigned ( ) const;
  335.  
  336. double
  337.   asDouble ( ) const;
  338.  
  339. IString
  340.  &b2c ( ),
  341.  &b2d ( ),
  342.  &b2x ( ),
  343.  &c2b ( ),
  344.  &c2d ( ),
  345.  &c2x ( ),
  346.  &d2b ( ),
  347.  &d2c ( ),
  348.  &d2x ( ),
  349.  &x2b ( ),
  350.  &x2c ( ),
  351.  &x2d ( );
  352.  
  353. /*------------------------- Manipulation Operators -----------------------------
  354.  
  355.    These functions allow the string contents to be manipulated.
  356.    All are overloaded so that standard C "strings" can be used
  357.    efficiently (without constructing an equivalent String
  358.    first).
  359.  
  360.    =  - Replaces the contents of the string
  361.    ~  - Returns bitwise negation (one's complement)
  362.    +  - Concatenates two strings
  363.    += - Concatenate and replace
  364.    &  - Performs bitwise "and"
  365.    &= - Performs bitwise "and" and replaces receiver
  366.    |  - Performs bitwise "or"
  367.    |= - Performs bitwise "or" and replaces receiver
  368.    ^  - Performs bitwise "xor"
  369.    ^= - Performs bitwise "xor" and replaces receiver
  370. ------------------------------------------------------------------------------*/
  371. IString
  372.  &operator =  ( const IString &aString );
  373.  
  374. IString
  375.   operator +  ( const IString &aString ) const,
  376.   operator +  ( const char    *pString ) const;
  377.  
  378. friend IString
  379.   operator +  ( const char    *pString,
  380.                 const IString &aString );
  381.  
  382. IString
  383.   operator ~  ( ) const;
  384.  
  385. IString
  386.  &operator += ( const IString &aString ),
  387.  &operator += ( const char    *pString );
  388.  
  389. IString
  390.   operator &  ( const IString &aString ) const,
  391.   operator &  ( const char    *pString ) const;
  392.  
  393. friend IString
  394.   operator &  ( const char    *pString,
  395.                 const IString &aString );
  396.  
  397. IString
  398.  &operator &= ( const IString &aString ),
  399.  &operator &= ( const char    *pString );
  400.  
  401. IString
  402.   operator |  ( const IString &aString ) const,
  403.   operator |  ( const char    *pString ) const;
  404.  
  405. friend IString
  406.   operator |  ( const char    *pString,
  407.                 const IString &aString );
  408.  
  409. IString
  410.  &operator |= ( const IString &aString ),
  411.  &operator |= ( const char    *pString );
  412.  
  413. IString
  414.   operator ^  ( const IString &aString ) const,
  415.   operator ^  ( const char    *pString ) const;
  416.  
  417. friend IString
  418.   operator ^  ( const char    *pString,
  419.                 const IString &aString );
  420.  
  421. IString
  422.  &operator ^= ( const IString &aString ),
  423.  &operator ^= ( const char    *pString );
  424.  
  425. /*------------------------------- Accessing ------------------------------------
  426.  
  427.    These functions provide access to general information about
  428.    the string.
  429.  
  430.    size       - Returns the length of the string (not counting
  431.                 the terminating null character).
  432.    length     - Same as "size"
  433.    subString  - Returns a given substring of the receiver.
  434.    operator[] - Return a reference to the n-th character of the
  435.                 string.  NOTE: The non-const version of this
  436.                 function will extend the string if invoked with
  437.                 and extend beyond the end.
  438. ------------------------------------------------------------------------------*/
  439. unsigned
  440.   size   ( ) const,
  441.   length ( ) const;
  442.  
  443. IString
  444.   subString ( unsigned startPos ) const,
  445.   subString ( unsigned startPos,
  446.               unsigned length,
  447.               char     padCharacter = ' ' ) const;
  448.  
  449. char
  450.  &operator [] ( unsigned index );
  451.  
  452. const char
  453.  &operator [] ( unsigned index ) const;
  454.  
  455. /*------------------------------- Searching ------------------------------------
  456.  
  457.    These functions permit searching the string in various ways.
  458.  
  459.    indexOfAnyBut - Returns the index of the first character of
  460.                    the receiver that is *not* in the argument
  461.                    set of characters (0 if none); alternatively,
  462.                    returns the index of the first character that
  463.                    fails the test proscribed by an argument
  464.                    IStringTest object
  465.    indexOfAnyOf  - Returns the index of the first character of
  466.                    the receiver that *is* a character in the
  467.                    argument set of characters (0 if none);
  468.                    alternatively, returns the index of the first
  469.                    character that passes the test proscribed by
  470.                    an argument IStringTest object
  471.    indexOf       - Return the index of the first occurrence of
  472.                    the argument string within the reciever (0
  473.                    if none); the argument can also be a single
  474.                    character or a IStringTest
  475.    occurrencesOf - Returns number of occurrences of the argument
  476.                    String,char*,char,test (slower than indexOf if you
  477.                    just want a boolean test).
  478.  
  479.    One can specify an optional index that indicates where in
  480.    the String the search is to start (default is to start at
  481.    the beginning of the string).
  482.  
  483.    Each of the "indexing" functions also has a "lastIndexOf"
  484.    version that returns the index of the last character in
  485.    the receiver IString that satisfies the search criteria.
  486.    These functions accept an optional argument that specifies
  487.    where the search is to commence (defaults to the end of the
  488.    string).
  489.  
  490.  Notes:
  491.    1. Use of the search functions requiring a IStringTest
  492.       argument necessitate the #including of istrtest.hpp
  493.  
  494.  Related Topics:
  495.    includes
  496. ------------------------------------------------------------------------------*/
  497. unsigned
  498.   indexOf ( const IString     &aString,
  499.             unsigned           startPos = 1 ) const,
  500.   indexOf ( const char        *pString,
  501.             unsigned           startPos = 1 ) const,
  502.   indexOf ( char              aCharacter,
  503.             unsigned           startPos = 1 ) const,
  504.   indexOf ( const IStringTest &aTest,
  505.             unsigned           startPos = 1 ) const,
  506.  
  507.   indexOfAnyBut ( const IString     &validChars,
  508.                   unsigned           startPos = 1 ) const,
  509.   indexOfAnyBut ( const char        *pValidChars,
  510.                   unsigned           startPos = 1 ) const,
  511.   indexOfAnyBut ( char               validChar,
  512.                   unsigned           startPos = 1 ) const,
  513.   indexOfAnyBut ( const IStringTest &aTest,
  514.                   unsigned           startPos = 1 ) const,
  515.  
  516.   indexOfAnyOf ( const IString     &searchChars,
  517.                  unsigned           startPos = 1 ) const,
  518.   indexOfAnyOf ( const char        *pSearchChars,
  519.                  unsigned           startPos = 1 ) const,
  520.   indexOfAnyOf ( char               searchChar,
  521.                  unsigned           startPos = 1 ) const,
  522.   indexOfAnyOf ( const IStringTest &aTest,
  523.                  unsigned           startPos = 1 ) const,
  524.  
  525.   lastIndexOf ( const IString &aString,
  526.                 unsigned       endPos = 0 ) const,
  527.   lastIndexOf ( const char    *pString,
  528.                 unsigned       endPos = 0 ) const,
  529.   lastIndexOf ( char          aCharacter,
  530.                 unsigned       endPos = 0 ) const,
  531.   lastIndexOf ( const IStringTest &aTest,
  532.                 unsigned           startPos = 1 ) const,
  533.  
  534.   lastIndexOfAnyBut ( const IString     &validChars,
  535.                       unsigned           endPos = 0 ) const,
  536.   lastIndexOfAnyBut ( const char        *pValidChars,
  537.                       unsigned           endPos = 0 ) const,
  538.   lastIndexOfAnyBut ( char               validChar,
  539.                       unsigned           startPos = 1 ) const,
  540.   lastIndexOfAnyBut ( const IStringTest &aTest,
  541.                       unsigned           endPos = 0 ) const,
  542.  
  543.   lastIndexOfAnyOf ( const IString     &searchChars,
  544.                      unsigned           endPos = 0 ) const,
  545.   lastIndexOfAnyOf ( const char        *pSearchChars,
  546.                      unsigned           endPos = 0 ) const,
  547.   lastIndexOfAnyOf ( char               searchChar,
  548.                      unsigned           startPos = 1 ) const,
  549.   lastIndexOfAnyOf ( const IStringTest &aTest,
  550.                      unsigned           endPos = 0 ) const,
  551.  
  552.   occurrencesOf ( const IString     &aString,
  553.                   unsigned           startPos = 1 ) const,
  554.   occurrencesOf ( const char        *pString,
  555.                   unsigned           startPos = 1 ) const,
  556.   occurrencesOf ( char              aCharacter,
  557.                   unsigned           startPos = 1 ) const,
  558.   occurrencesOf ( const IStringTest &aTest,
  559.                   unsigned           startPos = 1 ) const;
  560.  
  561. /*-------------------------------- Editing -------------------------------------
  562.  
  563.    These functions are used to edit the string.  All return
  564.    a reference to the (modified) receiver.  Many that are
  565.    'length related' (e.g., center, leftJustify) accept a pad
  566.    character which defaults to a blank.  In all cases, argument
  567.    strings can be specified as either objects of class String
  568.    or via char*.
  569.  
  570.    center         - centers the receiver within a string of the
  571.                     specified length
  572.    change         - changes occurrences of an argument pattern to
  573.                     an argument replacement string, the number
  574.                     of changes to perform can be specified (defaults
  575.                     to all occurrences of the pattern), as can the
  576.                     position in the receiver at which to begin
  577.    copy           - replaces the receiver's contents with a given
  578.                     number of replications of itself
  579.    remove         - Deletes the specified substring from the receiver
  580.    insert         - Inserts an argument string at a given location
  581.    leftJustify    - Left justifies the receiver in a string of the
  582.                     specified length
  583.    lowerCase      - Translates all upper case letters in the receiver
  584.                     to lower case
  585.    overlayWith    - Replaces a given portion of the receiver's contents
  586.                     with an argument string
  587.    reverse        - Reverse the receiver contents
  588.    rightJustify   - Right justifies the receiver in a string of the
  589.                     specified length.
  590.    strip          - Strips both leading and trailing character or
  591.                     characters; the character(s) can be specified
  592.                     either as a single char, a String (or char*
  593.                     array), or via a IStringTest (the latter defined
  594.                     in StrTest.hpp); the default is "whitespace"
  595.    stripLeading   - Strip leading char/chars
  596.    stripTrailing  - Strip trailing char/chars
  597.    translate      - Converts all receiver characters that are in one
  598.                     argument string to the corresponding character in
  599.                     a second argument string
  600.    upperCase      - Translates all lower case letters in the receiver
  601.                     to upper case.
  602.  
  603.    There are plain functions by the same name that can be applied to
  604.    a String to obtain the modified String without affecting the
  605.    argument.  For example:
  606.  
  607.    aString.change('\t', '   '); // Changes all tabs in
  608.                                 // aString to 3 blanks.
  609.    String s = change( aString, '\t', '   ' ); // Leaves aString as is
  610.                                 // but obtains modified version.
  611. ------------------------------------------------------------------------------*/
  612. IString
  613.  ¢er         ( unsigned length,
  614.                    char     padCharacter = ' ' ),
  615.  
  616.  &change         ( const IString &inputString,
  617.                    const IString &outputString,
  618.                    unsigned       startPos = 1,
  619.                    unsigned       numChanges = 0 ),
  620.  &change         ( const IString &inputString,
  621.                    const char    *pOutputString,
  622.                    unsigned       startPos = 1,
  623.                    unsigned       numChanges = 0 ),
  624.  &change         ( const char    *pInputString,
  625.                    const IString &outputString,
  626.                    unsigned       startPos = 1,
  627.                    unsigned       numChanges = 0 ),
  628.  &change         ( const char    *pInputString,
  629.                    const char    *pOutputString,
  630.                    unsigned       startPos = 1,
  631.                    unsigned       numChanges = 0 ),
  632.  
  633.  ©           ( unsigned numCopies ),
  634.  
  635.  &insert         ( const IString &aString,
  636.                    unsigned       index = 0,
  637.                    char           padCharacter = ' ' ),
  638.  &insert         ( const char    *pString,
  639.                    unsigned       index = 0,
  640.                    char           padCharacter = ' ' ),
  641.  
  642.  &leftJustify    ( unsigned length,
  643.                    char     padCharacter = ' ' ),
  644.  
  645.  &lowerCase      ( ),
  646.  
  647.  &overlayWith    ( const IString &aString,
  648.                    unsigned       index        = 1,
  649.                    char           padCharacter = ' ' ),
  650.  &overlayWith    ( const char    *pString,
  651.                    unsigned       index        = 1,
  652.                    char           padCharacter = ' ' ),
  653.  
  654.  &remove         ( unsigned startPos ),
  655.  &remove         ( unsigned startPos,
  656.                    unsigned numChars ),
  657.  
  658.  &reverse        ( ),
  659.  
  660.  &rightJustify   ( unsigned length,
  661.                    char     padCharacter = ' ' ),
  662.  
  663.  &strip          ( ),
  664.  &strip          ( char               aCharacter ),
  665.  &strip          ( const IString     &aString ),
  666.  &strip          ( const char        *pString ),
  667.  &strip          ( const IStringTest &aTest ),
  668.  
  669.  &stripLeading   ( ),
  670.  &stripLeading   ( char               aCharacter ),
  671.  &stripLeading   ( const IString     &aString ),
  672.  &stripLeading   ( const char        *pString ),
  673.  &stripLeading   ( const IStringTest &aTest ),
  674.  
  675.  &stripTrailing  ( ),
  676.  &stripTrailing  ( char               aCharacter ),
  677.  &stripTrailing  ( const IString     &aString ),
  678.  &stripTrailing  ( const char        *pString ),
  679.  &stripTrailing  ( const IStringTest &aTest ),
  680.  
  681.  &translate      ( const IString &inputChars,
  682.                    const IString &outputChars,
  683.                    char           padCharacter = ' ' ),
  684.  &translate      ( const IString &inputChars,
  685.                    const char    *pOutputChars,
  686.                    char           padCharacter = ' ' ),
  687.  &translate      ( const char    *pInputChars,
  688.                    const IString &outputChars,
  689.                    char           padCharacter = ' ' ),
  690.  &translate      ( const char    *pInputChars,
  691.                    const char    *pOutputChars,
  692.                    char           padCharacter = ' ' ),
  693.  
  694.  &upperCase      ( );
  695.  
  696. /*----------------------------- Word Functions ---------------------------------
  697.  
  698.    These functions operate on the string as a collection of
  699.    words separated by whitespace characters.
  700.  
  701.    indexOfPhrase - Returns the position of the first occurrence
  702.                    of the argument phrase in the receiver
  703.    indexOfWord   - Returns the index of the n-th whitespace
  704.                    delimited word in the receiver
  705.    lengthOfWord  - Returns the length of the n-th whitespace
  706.                    delimited word in the receiver
  707.    numWords      - Returns the number of whitespace delimited words
  708.                    in the receiver
  709.    removeWords   - Deletes the specified words from the receiver
  710.                    contents; the words are specified via a starting
  711.                    word number and the number of words (the latter
  712.                    defaulting to the rest of the string) (See note)
  713.    space         - Modifies the receiver so that all words are
  714.                    separated by the specified number of blanks
  715.                    (defaults to 1); all whitespace is converted
  716.                    to simple blanks (See note)
  717.    word          - Returns a copy of the n-th whitespace delimited
  718.                    word in the receiver
  719.    wordIndexOfPhrase - Returns the word number of the first word in
  720.                    receiver matching the argument phrase
  721.    words         - Returns a substring of the receiver that starts
  722.                    at a given word and comprised of a given number
  723.                    of words;  the word separators are copied to
  724.                    the result intact
  725.  
  726.    There are plain functions "space" and "removeWords" that obtain
  727.    the same result but do not affect the String to which they are
  728.    applied.
  729. ------------------------------------------------------------------------------*/
  730. IString
  731.  &removeWords ( unsigned firstWord ),
  732.  &removeWords ( unsigned firstWord,
  733.                 unsigned numWords );
  734. unsigned
  735.   indexOfPhrase     ( const IString &wordString,
  736.                       unsigned       startWord = 1 ) const,
  737.  
  738.   indexOfWord       ( unsigned wordNumber ) const,
  739.  
  740.   lengthOfWord      ( unsigned wordNumber ) const,
  741.  
  742.   numWords          ( ) const,
  743.  
  744.   wordIndexOfPhrase ( const IString &aPhrase,
  745.                       unsigned       startWord = 1 ) const;
  746.  
  747. IString
  748.  &space ( unsigned numSpaces = 1,
  749.           char     spaceChar = ' ' );
  750.  
  751. IString
  752.   word  ( unsigned  wordNumber ) const,
  753.  
  754.   words ( unsigned  firstWord ) const,
  755.   words ( unsigned  firstWord,
  756.           unsigned  numWords  ) const;
  757.  
  758. // Modes for strip functions:
  759. typedef enum
  760.   {
  761.   leading,
  762.   trailing,
  763.   both
  764.   } StripMode;
  765.  
  766. protected:
  767.  
  768. // Pointer to string contents:
  769. // IBuffer *pBuffer;                                               deleted KMT
  770. char* pBuffer;                                                  // new - KMT
  771.  
  772. // Static "constants":
  773. static const IString
  774.   null,
  775.   zero,
  776.   maxLong;
  777.  
  778. // Function to obtain contents:
  779. char
  780.  *data ( ) const;
  781.  
  782. // Function to set associatedIBuffer:
  783. void     
  784.   setBuffer( IBuffer *ibuff );
  785.  
  786. // Function to obtain associated IBuffer:
  787. IBuffer
  788.  *buffer ( ) const;
  789.  
  790. // Static function to return string length (handles NULL):
  791. static unsigned
  792.   lengthOf( const char *p );
  793.  
  794. #if defined( __ZTC__ )
  795. public:
  796. #endif
  797.  
  798. // Static function to return default (null) buffer pointer:
  799. static char
  800.  *defaultBuffer ( );
  801.  
  802. // Special constructor to take over ownership of buffer:
  803. IString ( IBuffer *pBuffer );
  804.  
  805. #if defined( __ZTC__ )
  806. protected:
  807. #endif
  808.  
  809. // Buffer inititialization:
  810. void
  811.   initBuffer ( const void *p1,
  812.                unsigned    len1,
  813.                const void *p2      = 0,
  814.                unsigned    len2    = 0,
  815.                const void *p3      = 0,
  816.                unsigned    len3    = 0,
  817.                char        padChar = 0 ),
  818.   initBuffer ( long n ),
  819.   initBuffer ( unsigned long n ),
  820.   initBuffer ( double d );
  821.  
  822. // Common "occurrencesOf" implementation function:
  823. unsigned
  824.   occurrencesOf ( const char *pSearchString,
  825.                   unsigned    searchLen,
  826.                   unsigned    startPos ) const;
  827.  
  828. // Perform common isLike function:
  829. Boolean
  830.   isLike ( const char *pPattern,
  831.            unsigned    patternLen,
  832.            char        zeroOrMore,
  833.            char        anyChar ) const;
  834.  
  835. // Implement isAbbrevFor:
  836. Boolean
  837.   isAbbrevFor ( const char *pFullString,
  838.                 unsigned    fullLen,
  839.                 unsigned    minLen ) const;
  840.  
  841. // Apply bitwise operators:
  842. typedef enum
  843.   {
  844.   and,
  845.   or,
  846.   exclusiveOr
  847.   } BitOperator;
  848.  
  849. IString
  850.  &applyBitOp ( const char *pArg,
  851.                unsigned argLen,
  852.                BitOperator op );
  853.  
  854. // Common edit function implementation:
  855. IString
  856.  &change      ( const char *pPattern,
  857.                 unsigned    patternLen,
  858.                 const char *pReplacement,
  859.                 unsigned    replacementLen,
  860.                 unsigned    startPos,
  861.                 unsigned    numChanges ),
  862.  &insert      ( const char *pInsert,
  863.                 unsigned    insertLen,
  864.                 unsigned    startPos,
  865.                 char        padCharacter ),
  866.  &overlayWith ( const char *pOverlay,
  867.                 unsigned    overlayLen,
  868.                 unsigned    index,
  869.                 char        padCharacter ),
  870.  &strip       ( const char *p,
  871.                 unsigned    len,
  872.                 StripMode   mode ),
  873.  &strip       ( const IStringTest &aTest,
  874.                 StripMode          mode ),
  875.  &translate   ( const char *pInputChars,
  876.                 unsigned    inputLen,
  877.                 const char *pOutputChars,
  878.                 unsigned    outputLen,
  879.                 char        padCharacter );
  880.  
  881. // Enumeration of options to findPhrase:
  882. typedef enum
  883.   {
  884.   charIndex,
  885.   wordIndex
  886.   } IndexType;
  887.  
  888. // Function to find word/phrase:
  889. unsigned
  890.   findPhrase ( const IString &aPhrase,
  891.                unsigned       startWord,
  892.                IndexType      charOrWord ) const;
  893.  
  894. // IndexOfWord utility function:
  895. unsigned
  896.   indexOfWord ( unsigned wordNumber,
  897.                 unsigned startPos,
  898.                 unsigned numWords ) const;
  899.  
  900. // character/decimal conversion utilities:
  901. void
  902.   binaryMath  ( unsigned char newDigit ),
  903.   decimalMath ( unsigned char newDigit );
  904.  
  905. // Make sure receiver holds only reference to its buffer:
  906. IString
  907.  &prepareToChange();
  908.  
  909. }; // class IString
  910.  
  911. /*------------------------------Related Functions-------------------------------
  912.  
  913.    These are non-member functions that manipulate Strings.  All (except
  914.    the ones that declare binary operators with char* as first argument)
  915.    are versions of the editing and conversion functions of the same name
  916.    as member functions.  These functions leave the IString argument
  917.    unmodified (and return a modified IString only).
  918. ------------------------------------------------------------------------------*/
  919. IString
  920.   center        ( const IString &aString,
  921.                   unsigned       length,
  922.                   char           padCharacter = ' ' ),
  923.  
  924.   change        ( const IString &aString,
  925.                   const IString &inputString,
  926.                   const IString &outputString,
  927.                   unsigned       startPos = 1,
  928.                   unsigned       numChanges = 0 ),
  929.   change        ( const IString &aString,
  930.                   const IString &inputString,
  931.                   const char    *pOutputString,
  932.                   unsigned       startPos = 1,
  933.                   unsigned       numChanges = 0 ),
  934.   change        ( const IString &aString,
  935.                   const char    *pInputString,
  936.                   const IString &outputString,
  937.                   unsigned       startPos = 1,
  938.                   unsigned       numChanges = 0 ),
  939.   change        ( const IString &aString,
  940.                   const char    *pInputString,
  941.                   const char    *pOutputString,
  942.                   unsigned       startPos = 1,
  943.                   unsigned       numChanges = 0 ),
  944.  
  945.   copy          ( const IString &aString,
  946.                   unsigned       numCopies ),
  947.  
  948.   insert        ( const IString &aString,
  949.                   const IString &anInsert,
  950.                   unsigned       index = 0,
  951.                   char           padCharacter = ' ' ),
  952.   insert        ( const IString &aString,
  953.                   const char    *pInsert,
  954.                   unsigned       index = 0,
  955.                   char           padCharacter = ' ' ),
  956.  
  957.   leftJustify   ( const IString &aString,
  958.                   unsigned       length,
  959.                   char           padCharacter = ' ' ),
  960.  
  961.   lowerCase     ( const IString &aString ),
  962.  
  963.   overlayWith   ( const IString &aString,
  964.                   const IString &anOverlay,
  965.                   unsigned       index        = 1,
  966.                   char           padCharacter = ' ' ),
  967.   overlayWith   ( const IString &aString,
  968.                   const char    *pOverlay,
  969.                   unsigned       index        = 1,
  970.                   char           padCharacter = ' ' ),
  971.  
  972.   remove        ( const IString &aString,
  973.                   unsigned       startPos ),
  974.   remove        ( const IString &aString,
  975.                   unsigned       startPos,
  976.                   unsigned       numChars ),
  977.  
  978.   removeWords   ( const IString &aString,
  979.                   unsigned       startWord ),
  980.   removeWords   ( const IString &aString,
  981.                   unsigned       startWord,
  982.                   unsigned       numWords  ),
  983.  
  984.   reverse       ( const IString &aString ),
  985.  
  986.   rightJustify  ( const IString &aString,
  987.                   unsigned       length,
  988.                   char           padCharacter = ' ' ),
  989.  
  990.   space         ( const IString &aString,
  991.                   unsigned       numSpaces = 1,
  992.                   char           spaceChar = ' ' ),
  993.  
  994.   strip         ( const IString &aString ),
  995.   strip         ( const IString &aString,
  996.                   char           aChar ),
  997.   strip         ( const IString &aString,
  998.                   const IString &aStringOfChars ),
  999.   strip         ( const IString &aString,
  1000.                   const char    *pStringOfChars ),
  1001.   strip         ( const IString &aString,
  1002.                   const IStringTest &aTest ),
  1003.  
  1004.   stripLeading  ( const IString &aString ),
  1005.   stripLeading  ( const IString &aString,
  1006.                   char           aChar ),
  1007.   stripLeading  ( const IString &aString,
  1008.                   const IString &aStringOfChars ),
  1009.   stripLeading  ( const IString &aString,
  1010.                   const char    *pStringOfChars ),
  1011.   stripLeading  ( const IString &aString,
  1012.                   const IStringTest &aTest ),
  1013.  
  1014.   stripTrailing ( const IString &aString ),
  1015.   stripTrailing ( const IString &aString,
  1016.                   char           aChar ),
  1017.   stripTrailing ( const IString &aString,
  1018.                   const IString &aStringOfChars ),
  1019.   stripTrailing ( const IString &aString,
  1020.                   const char    *pStringOfChars ),
  1021.   stripTrailing ( const IString &aString,
  1022.                   const IStringTest &aTest ),
  1023.  
  1024.   translate     ( const IString &aString,
  1025.                   const IString &inputChars,
  1026.                   const IString &outputChars,
  1027.                   char           padCharacter = ' ' ),
  1028.   translate     ( const IString &aString,
  1029.                   const IString &inputChars,
  1030.                   const char    *pOutputChars,
  1031.                   char           padCharacter = ' ' ),
  1032.   translate     ( const IString &aString,
  1033.                   const char    *pInputChars,
  1034.                   const IString &outputChars,
  1035.                   char           padCharacter = ' ' ),
  1036.   translate     ( const IString &aString,
  1037.                   const char    *pInputChars,
  1038.                   const char    *pOutputChars,
  1039.                   char           padCharacter = ' ' ),
  1040.  
  1041.   upperCase     ( const IString &aString ),
  1042.  
  1043.   b2c           ( const IString &aString ),
  1044.   b2d           ( const IString &aString ),
  1045.   b2x           ( const IString &aString ),
  1046.   c2b           ( const IString &aString ),
  1047.   c2d           ( const IString &aString ),
  1048.   c2x           ( const IString &aString ),
  1049.   d2b           ( const IString &aString ),
  1050.   d2c           ( const IString &aString ),
  1051.   d2x           ( const IString &aString ),
  1052.   x2b           ( const IString &aString ),
  1053.   x2c           ( const IString &aString ),
  1054.   x2d           ( const IString &aString );
  1055.  
  1056. #endif
  1057.