home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / I0STRING.HPP < prev    next >
C/C++ Source or Header  |  1993-10-22  |  18KB  |  358 lines
  1. #ifndef _I0STRING_
  2. #define _I0STRING_
  3. /*******************************************************************************
  4. * FILE NAME: i0string.hpp                                                      *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   This file contains the declaration(s) of the class(es):                    *
  8. *     I0String - Derivative of class IString supporting 0-based indexing.      *
  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               *
  15. *   disclosure                                                                 *
  16. *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  17. *                                                                              *
  18. *******************************************************************************/
  19. #ifndef _ISTRING_
  20.   #include <istring.hpp>
  21. #endif
  22.  
  23. /*----------------------------------------------------------------------------*/
  24. /* Align classes on four byte boundary.                                       */
  25. /*----------------------------------------------------------------------------*/
  26. #pragma pack(4)
  27.  
  28. class IStringTest;
  29.  
  30. class I0String : public IString {
  31. /*******************************************************************************
  32. * Objects of this class are functionally equivalent to objects of class        *
  33. * IString with one major distinction:  I0Strings are indexed starting at       *
  34. * 0 instead of 1.                                                              *
  35. *                                                                              *
  36. * This class is intended to be used by programmers more comfortable with       *
  37. * such an indexing scheme.  Note that a consequence of starting indices at     *
  38. * 0 means that the search functions no longer can be used as if they           *
  39. * were Boolean.  That is:                                                      *
  40. *                                                                              *
  41. *   a0String.indexOf( anotherString ) != a0String.includes( anotherString ).   *
  42. *                                                                              *
  43. * IStrings and I0Strings can be freely intermixed in a program.  Objects of    *
  44. * one class can be assigned values of the other type.  Objects of either       *
  45. * class can be passed as arguments to functions requiring the other type.      *
  46. *                                                                              *
  47. * See the descriptions for class IString in ISTRING.HPP                        *
  48. *                                                                              *
  49. * WARNING: UINT_MAX is a reserved value for I0String.  Unpredictable results   *
  50. *          can occur if used for the startPos argument in I0String functions.  *
  51. *******************************************************************************/
  52. public:
  53. /*------------------------------- Constructors ---------------------------------
  54.   You can construct instances of this class in the following ways:
  55.     1. Construct a null string.
  56.     2. Construct a string with the ASCII representation of a given numeric
  57.        value, supporting all flavors of int and double.
  58.     3. Construct a string with a copy of the given character data, supporting
  59.        ASCIIZ strings, characters, and I0Strings.
  60.     4. Construct a string with contents that consist of copies of up to three
  61.        buffers of arbitrary data (void*).  Optionally, only the length need
  62.        be provided, in which case the I0String contents are initialized to a
  63.        given pad character.  The default is a blank.
  64. ------------------------------------------------------------------------------*/
  65.   I0String ( );
  66.   I0String ( const IString &aString );
  67.  
  68.   I0String ( int );
  69.   I0String ( unsigned );
  70.   I0String ( long );
  71.   I0String ( unsigned long );
  72.   I0String ( short );
  73.   I0String ( unsigned short );
  74.  
  75.   I0String ( double );
  76.  
  77.   I0String ( char );
  78.   I0String ( unsigned char );
  79.   I0String ( signed char );
  80.  
  81.   I0String ( const char * );
  82.   I0String ( const unsigned char * );
  83.   I0String ( const signed char * );
  84.  
  85.   I0String ( const void *pBuffer1,
  86.              unsigned    lenBuffer1,
  87.              char        padCharacter = ' ' );
  88.   I0String ( const void *pBuffer1,
  89.              unsigned    lenBuffer1,
  90.              const void *pBuffer2,
  91.              unsigned    lenBuffer2,
  92.              char        padCharacter = ' ' );
  93.   I0String ( const void *pBuffer1,
  94.              unsigned    lenBuffer1,
  95.              const void *pBuffer2,
  96.              unsigned    lenBuffer2,
  97.              const void *pBuffer3,
  98.              unsigned    lenBuffer3,
  99.              char        padCharacter = ' ' );
  100.  
  101. /*------------------------------- Accessors ------------------------------------
  102. | These functions are overridden to permit specification of the index          |
  103. | as a 0-based value:                                                          |
  104. |   subString   - Returns a given substring of the receiver.                   |
  105. |   operator [] - Returns a reference to the nth character of the string.      |
  106. |                 NOTE: The non-const version of this function extends the     |
  107. |                       string if it is invoked with an index beyond the end.  |
  108. |   charType    - Returns the type of the character at the argument index.     |
  109. ------------------------------------------------------------------------------*/
  110. I0String
  111.   subString ( unsigned startPos ) const,
  112.   subString ( unsigned startPos,
  113.               unsigned len,
  114.               char     padCharacter = ' ' ) const;
  115.  
  116. char
  117.  &operator [] ( unsigned index );
  118.  
  119. const char
  120.  &operator [] ( unsigned index ) const;
  121.  
  122. IStringEnum::CharType
  123.   charType ( unsigned index ) const;
  124.  
  125. /*------------------------------- Searching ------------------------------------
  126. | These functions are re-implemented to treat the starting position of the     |
  127. | search as a 0-based index.                                                   |
  128. |   indexOf           - Returns the index of the first occurrence of the       |
  129. |                       argument string within the receiver; 0 is returned if  |
  130. |                       there are no occurrences.  The argument can also be a  |
  131. |                       single character or an IStringTest.                    |
  132. |   indexOfAnyBut     - Returns the index of the first character of the        |
  133. |                       receiver that is not in the argument set of            |
  134. |                       characters; 0 is returned if there are no characters.  |
  135. |                       Alternatively, it returns the index of the first       |
  136. |                       character that fails the test proscribed by an         |
  137. |                       argument IStringTest object.                           |
  138. |   indexOfAnyOf      - Returns the index of the first character of the        |
  139. |                       receiver that is a character in the argument set of    |
  140. |                       characters; 0 is returned if there are no characters.  |
  141. |                       Alternatively, it returns the index of the first       |
  142. |                       character that passes the test proscribed by an        |
  143. |                       argument IStringTest object.                           |
  144. |   lastIndexOf       - Returns the index of the last occurrence of the        |
  145. |                       argument.                                              |
  146. |   lastIndexOfAnyBut - Returns the index of the last character not in the     |
  147. |                       argument.                                              |
  148. |   lastIndexOfAnyOf  - Returns the index of the last character in the         |
  149. |                       argument.                                              |
  150. |   occurrencesOf     - Returns the number of occurrences of the argument      |
  151. |                       'I0String,char*,char,test'.  This is slower than       |
  152. |                       'indexOf' if you just want a Boolean test.             |
  153. ------------------------------------------------------------------------------*/
  154. unsigned
  155.   indexOf ( const IString     &aString,
  156.             unsigned           startPos = 0 ) const,
  157.   indexOf ( const char        *pString,
  158.             unsigned           startPos = 0 ) const,
  159.   indexOf ( char               aCharacter,
  160.             unsigned           startPos = 0 ) const,
  161.   indexOf ( const IStringTest &aTest,
  162.             unsigned           startPos = 0 ) const,
  163.  
  164.   indexOfAnyBut ( const IString     &aString,
  165.                   unsigned           startPos = 0 ) const,
  166.   indexOfAnyBut ( const char        *pValidChars,
  167.                   unsigned           startPos = 0 ) const,
  168.   indexOfAnyBut ( char               validChar,
  169.                   unsigned           startPos = 0 ) const,
  170.   indexOfAnyBut ( const IStringTest &aTest,
  171.                   unsigned           startPos = 0 ) const,
  172.  
  173.   indexOfAnyOf ( const IString     &searchChars,
  174.                  unsigned           startPos = 0 ) const,
  175.   indexOfAnyOf ( const char        *pSearchChars,
  176.                  unsigned           startPos = 0 ) const,
  177.   indexOfAnyOf ( char               searchChar,
  178.                  unsigned           startPos = 0 ) const,
  179.   indexOfAnyOf ( const IStringTest &aTest,
  180.                  unsigned           startPos = 0 ) const,
  181.  
  182.   lastIndexOf ( const IString     &aString,
  183.                 unsigned           endPos = UINT_MAX-1 ) const,
  184.   lastIndexOf ( const char        *pString,
  185.                 unsigned           endPos = UINT_MAX-1 ) const,
  186.   lastIndexOf ( char               aCharacter,
  187.                 unsigned           endPos = UINT_MAX-1 ) const,
  188.   lastIndexOf ( const IStringTest &aTest,
  189.                 unsigned           startPos = UINT_MAX-1 ) const,
  190.  
  191.   lastIndexOfAnyBut ( const IString     &validChars,
  192.                       unsigned           endPos = UINT_MAX-1 ) const,
  193.   lastIndexOfAnyBut ( const char        *pValidChars,
  194.                       unsigned           endPos = UINT_MAX-1 ) const,
  195.   lastIndexOfAnyBut ( char               validChar,
  196.                       unsigned           startPos = UINT_MAX-1 ) const,
  197.   lastIndexOfAnyBut ( const IStringTest &aTest,
  198.                       unsigned           endPos = UINT_MAX-1 ) const,
  199.  
  200.   lastIndexOfAnyOf ( const IString     &searchChars,
  201.                      unsigned           endPos = UINT_MAX-1 ) const,
  202.   lastIndexOfAnyOf ( const char        *pSearchChars,
  203.                      unsigned           endPos = UINT_MAX-1 ) const,
  204.   lastIndexOfAnyOf ( char               searchChar,
  205.                      unsigned           startPos = UINT_MAX-1 ) const,
  206.   lastIndexOfAnyOf ( const IStringTest &aTest,
  207.                      unsigned           endPos = UINT_MAX-1 ) const,
  208.  
  209.   occurrencesOf ( const IString     &aString,
  210.                   unsigned           startPos = 0 ) const,
  211.   occurrencesOf ( const char        *pString,
  212.                   unsigned           startPos = 0 ) const,
  213.   occurrencesOf ( char               aCharacter,
  214.                   unsigned           startPos = 0 ) const,
  215.   occurrencesOf ( const IStringTest &aTest,
  216.                   unsigned           startPos = 0 ) const;
  217.  
  218. /*-------------------------------- Editing -------------------------------------
  219. | These editing functions are re-implemented to treat the position             |
  220. | arguments as 0-based:                                                        |
  221. |   change        - Changes occurrences of an argument pattern to an           |
  222. |                   argument replacement string.  The number of changes to     |
  223. |                   perform can be specified.  The default is to change all    |
  224. |                   occurrences of the pattern.  You can also specify the      |
  225. |                   position in the receiver at which to begin.                |
  226. |   insert        - Inserts an argument string at a given location.            |
  227. |   overlayWith   - Replaces a given portion of the receiver's contents        |
  228. |                   with an argument string.                                   |
  229. |   remove        - Deletes the specified substring from the receiver.         |
  230. ------------------------------------------------------------------------------*/
  231. I0String
  232.  &change ( const IString &aPattern,
  233.            const IString &aReplacement,
  234.            unsigned       startPos = 0,
  235.            unsigned       numChanges = UINT_MAX ),
  236.  &change ( const IString &aPattern,
  237.            const char    *pReplacement,
  238.            unsigned       startPos = 0,
  239.            unsigned       numChanges = UINT_MAX ),
  240.  &change ( const char    *pPattern,
  241.            const IString &aReplacement,
  242.            unsigned       startPos = 0,
  243.            unsigned       numChanges = UINT_MAX ),
  244.  &change ( const char    *pPattern,
  245.            const char    *pReplacement,
  246.            unsigned       startPos = 0,
  247.            unsigned       numChanges = UINT_MAX ),
  248.  
  249.  &insert ( const IString &aString,
  250.            unsigned       index = UINT_MAX,
  251.            char           padCharacter = ' ' ),
  252.  &insert ( const char    *pString,
  253.            unsigned       index = UINT_MAX,
  254.            char           padCharacter = ' ' ),
  255.  
  256.  &overlayWith ( const IString &aString,
  257.                 unsigned       index        = 0,
  258.                 char           padCharacter = ' ' ),
  259.  &overlayWith ( const char    *pString,
  260.                 unsigned       index        = 0,
  261.                 char           padCharacter = ' ' ),
  262.  
  263.  &remove ( unsigned startPos ),
  264.  &remove ( unsigned startPos,
  265.            unsigned numChars );
  266.  
  267. static I0String
  268.   change ( const IString &aString,
  269.            const IString &inputString,
  270.            const IString &outputString,
  271.            unsigned       startPos = 0,
  272.            unsigned       numChanges = UINT_MAX ),
  273.   change ( const IString &aString,
  274.            const IString &inputString,
  275.            const char    *pOutputString,
  276.            unsigned       startPos = 0,
  277.            unsigned       numChanges = UINT_MAX ),
  278.   change ( const IString &aString,
  279.            const char    *pInputString,
  280.            const IString &outputString,
  281.            unsigned       startPos = 0,
  282.            unsigned       numChanges = UINT_MAX ),
  283.   change ( const IString &aString,
  284.            const char    *pInputString,
  285.            const char    *pOutputString,
  286.            unsigned       startPos = 0,
  287.            unsigned       numChanges = UINT_MAX ),
  288.  
  289.   insert ( const IString &aString,
  290.            const IString &anInsert,
  291.            unsigned       index = UINT_MAX,
  292.            char           padCharacter = ' ' ),
  293.   insert ( const IString &aString,
  294.            const char    *pInsert,
  295.            unsigned       index = UINT_MAX,
  296.            char           padCharacter = ' ' ),
  297.  
  298.   overlayWith ( const IString &aString,
  299.                 const IString &anOverlay,
  300.                 unsigned       index        = 0,
  301.                 char           padCharacter = ' ' ),
  302.   overlayWith ( const IString &aString,
  303.                 const char    *pOverlay,
  304.                 unsigned       index        = 0,
  305.                 char           padCharacter = ' ' ),
  306.  
  307.   remove ( const IString &aString,
  308.            unsigned       startPos ),
  309.   remove ( const IString &aString,
  310.            unsigned       startPos,
  311.            unsigned       numChars );
  312.  
  313. /*----------------------------- Word Functions ---------------------------------
  314. | These two word search functions are re-implemented to treat the result        |
  315. | index as 0-based.                                                            |
  316. |   indexOfPhrase     - Returns the position of the first occurrence of the    |
  317. |                       argument phrase in the receiver.                       |
  318. |   indexOfWord       - Returns the index of the nth whitespace-delimited      |
  319. |                       word in the receiver.                                  |
  320. ------------------------------------------------------------------------------*/
  321. unsigned
  322.   indexOfPhrase ( const IString &wordString,
  323.                   unsigned       startWord = 1 ) const,
  324.   indexOfWord   ( unsigned wordNumber ) const;
  325.  
  326. /*----------------------------- Class Constants --------------------------------
  327. | The following static function can be used in conjunction with the searching
  328. | functions:
  329. |   notFound - Specifies the value returned by searching functions to indicate   |
  330. |              that the search failed.                                           |
  331. ------------------------------------------------------------------------------*/
  332. static const unsigned
  333.   notFound;
  334.  
  335. protected:
  336. /*------------------------------ Implementation --------------------------------
  337. | These functions provide various utilities used to implement this class:      |
  338. |   adjustArg    - Adjusts an argument index from 0- to 1-based.               |
  339. |   adjustResult - Adjusts a function result from 1- to 0-based.               |
  340. ------------------------------------------------------------------------------*/
  341. static unsigned
  342.   adjustArg    ( unsigned index ),
  343.   adjustResult ( unsigned index );
  344.  
  345. private: /*------------------------ PRIVATE ----------------------------------*/
  346. }; // class I0String
  347.  
  348. /*----------------------------------------------------------------------------*/
  349. /* Resume compiler default packing.                                           */
  350. /*----------------------------------------------------------------------------*/
  351. #pragma pack()
  352.  
  353. #ifndef I_NO_INLINES
  354.   #include <i0string.inl>
  355. #endif
  356.  
  357. #endif /* _I0STRING_ */
  358.