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