IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/p_man/cat3/librw/RWCString.z/RWCString

Text File | 1998-10-30 | 75.8 KB | 1,189 lines

RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



NNNNaaaammmmeeee
     RWCString - Rogue Wave library class

SSSSyyyynnnnooooppppssssiiiissss
              #include <rw/cstring.h>



              RWCString a;




DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn
     Class RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg offers very powerful and convenient facilities for
     manipulating strings that are just as efficient as the familiar standard
     C <<<<ssssttttrrrriiiinnnngggg....hhhh>>>> functions.  Although the class is primarily intended to be
     used to handle single-byte character sets (SBCS; such as ASCII or ISO
     Latin-1), with care it can be used to handle multibyte character sets
     (MBCS).  There are two things that must be kept in mind when working with
     MBCS:
          Because characters can be more than one byte long, the number of
          bytes in a string can, in general, be greater than the number of
          characters in the string.  Use function RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::lllleeeennnnggggtttthhhh(((()))) to get
          the number of bytes in a string, function RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::mmmmbbbbLLLLeeeennnnggggtttthhhh(((()))) to
          get the number of characters.  Note that the latter is much slower
          because it must determine the number of bytes in every character.
          Hence, if the string is known to be nothing but SBCS, then
          RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::lllleeeennnnggggtttthhhh(((()))) is much to be preferred.

          One or more bytes of a multibyte character can be zero.  Hence, MBCS
          cannot be counted on being null terminated.  In practice, it is a
          rare MBCS that uses embedded nulls.  Nevertheless, you should be
          aware of this and program defensively.  In any case, class RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg
          can handle embedded nulls.

     Parameters of type "ccccoooonnnnsssstttt cccchhhhaaaarrrr****" must not be passed a value of zero.
     This is detected in the debug version of the library.  The class is
     implemented using a technique called ccccooooppppyyyy oooonnnn wwwwrrrriiiitttteeee.  With this technique,
     the copy constructor and assignment operators still reference the old
     object and hence are very fast.  An actual copy is made only when a
     "write" is performed, that is if the object is about to be changed.  The
     net result is excellent performance, but with easy-to-understand copy
     semantics.  A separate class RRRRWWWWCCCCSSSSuuuubbbbSSSSttttrrrriiiinnnngggg supports substring extraction
     and modification operations.

PPPPeeeerrrrssssiiiisssstttteeeennnncccceeee
     Simple







                                                                        PPPPaaaaggggeeee 1111






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



Example
              #include <rw/re.h>
          #include <rw/rstream.h>
          main(){
            RWCString a("There is no joy in Beantown.");
            cout << a << endl << "becomes...." << endl;
            RWCRExpr re("[A-Z][a-z]*town");  // Any capitalized "town"
            a.replace(re, "Redmond");
            cout << a << endl;
          }


     PPPPrrrrooooggggrrrraaaammmm oooouuuuttttppppuuuutttt::::

              There is no joy in Redmond.



EEEEnnnnuuuummmmeeeerrrraaaattttiiiioooonnnnssss
              enum RWCString::caseCompare { exact, ignoreCase }


     Used to specify whether comparisons, searches, and hashing functions
     should use case sensitive (eeeexxxxaaaacccctttt) or case-insensitive (iiiiggggnnnnoooorrrreeeeCCCCaaaasssseeee)
     semantics.

              enum RWCString::scopeType { one, all }


     Used to specify whether regular expression rrrreeeeppppllllaaaacccceeee replaces the first oooonnnneeee
     substring matched by the regular expression or replaces aaaallllllll substrings
     matched by the regular expression.

PPPPuuuubbbblllliiiicccc CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrrssss
              RWCString();


     Creates a string of length zero (the null string).

              RWCString(const char* cs);


     Conversion from the null-terminated character string ccccssss.  The created
     string will ccccooooppppyyyy the data pointed to by ccccssss, up to the first terminating
     null.  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss  ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd
     nnnnuuuullllllllssss....  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              RWCString(const char* cs, size_t N);


     Constructs a string from the character string ccccssss.  The created string
     will ccccooooppppyyyy the data pointed to by ccccssss.  Exactly NNNN bytes are copied,



                                                                        PPPPaaaaggggeeee 2222






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     iiiinnnncccclllluuuuddddiiiinnnngggg aaaannnnyyyy eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss.  Hence, the buffer pointed to by ccccssss must be
     at least NNNN bytes long.

              RWCString(RWSize_T ic);


     Creates a string of length zero (the null string).  The string's ccccaaaappppaaaacccciiiittttyyyy
     (that is, the size it can grow to without resizing) is given by the
     parameter iiiicccc.  We recommend creating an RRRRWWWWSSSSiiiizzzzeeee____TTTT value from a numerical
     constant to pass into this constructor.  While RRRRWWWWSSSSiiiizzzzeeee____TTTT knows how to
     convert size_t's to itself, conforming compilers will chose the
     conversion to char instead.

              RWCString(const RWCString& str);


     Copy constructor.  The created string will ccccooooppppyyyy ssssttttrrrr's data.

              RWCString(const RWCSubString& ss);


     Conversion from sub-string.  The created string will ccccooooppppyyyy the substring
     represented by ssssssss.

              RWCString(char c);


     Constructs a string containing the single character cccc.

              RWCString(char c, size_t N);


     Constructs a string containing the character cccc repeated NNNN times.

TTTTyyyyppppeeee CCCCoooonnnnvvvveeeerrrrssssiiiioooonnnn
              operator
          ccccoooonnnnsssstttt cccchhhhaaaarrrr****() const;


     Access to the RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg's data as a null terminated string.  This data is
     owned by the RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg and may not be deleted or changed.  If the
     RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg object itself changes or goes out of scope, the pointer value
     previously returned may (will!) become invalid.  While the string is
     null-terminated, note that its lllleeeennnnggggtttthhhh is still given by the member
     function lllleeeennnnggggtttthhhh(((()))).  That is, it may contain embedded nulls.

AAAAssssssssiiiiggggnnnnmmmmeeeennnntttt OOOOppppeeeerrrraaaattttoooorrrrssss
              RWCString&
          ooooppppeeeerrrraaaattttoooorrrr====(const char* cs);


     Assignment operator.  Copies the null-terminated character string pointed



                                                                        PPPPaaaaggggeeee 3333






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     to by ccccssss into self.  Returns a reference to self. TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss
     iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee
     iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              RWCString&
          ooooppppeeeerrrraaaattttoooorrrr====(const RWCString& str);


     Assignment operator.  The string will ccccooooppppyyyy ssssttttrrrr's data.  Returns a
     reference to self.

              RWCString&
          ooooppppeeeerrrraaaattttoooorrrr++++====(const char* cs);


     Append the null-terminated character string pointed to by ccccssss to self.
     Returns a reference to self. TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss
     ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss
     MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              RWCString&
          ooooppppeeeerrrraaaattttoooorrrr++++====(const RWCString& str);


     Append the string ssssttttrrrr to self.  Returns a reference to self.

IIIInnnnddddeeeexxxxiiiinnnngggg OOOOppppeeeerrrraaaattttoooorrrrssss
              char&
          ooooppppeeeerrrraaaattttoooorrrr[[[[]]]](size_t i);
          char
          ooooppppeeeerrrraaaattttoooorrrr[[[[]]]](size_t i) const;


     Return the iiiith byte.  The first variant can be used as an lvalue.  The
     index iiii must be between 0 and the length of the string less one.  Bounds
     checking is performed -- if the index is out of range then an exceptionof
     type RRRRWWWWBBBBoooouuuunnnnddddssssEEEErrrrrrrr will occur.

              char&
          ooooppppeeeerrrraaaattttoooorrrr(((())))(size_t i);
          char
          ooooppppeeeerrrraaaattttoooorrrr(((())))(size_t i) const;


     Return the iiiith byte.  The first variant can be used as an lvalue.  The
     index iiii must be between 0 and the length of the string less one.  Bounds
     checking is performed if the pre-processor macro RRRRWWWWBBBBOOOOUUUUNNNNDDDDSSSS____CCCCHHHHEEEECCCCKKKK has been
     defined before including <<<<rrrrwwww////ccccssssttttrrrriiiinnnngggg....hhhh>>>>....  In this case, if the index is
     out of range, then an exception of type RRRRWWWWBBBBoooouuuunnnnddddssssEEEErrrrrrrr will occur.






                                                                        PPPPaaaaggggeeee 4444






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



              RWCSubString
          ooooppppeeeerrrraaaattttoooorrrr(((())))(size_t start, size_t len);
          const RWCSubString
          ooooppppeeeerrrraaaattttoooorrrr(((())))(size_t start, size_t len) const;


     Substring operator.  Returns an RRRRWWWWCCCCSSSSuuuubbbbSSSSttttrrrriiiinnnngggg of self with length lllleeeennnn,
     starting at index ssssttttaaaarrrrtttt.  The first variant can be used as an lvalue.
     The sum of ssssttttaaaarrrrtttt plus lllleeeennnn must be less than or equal to the string
     length.  If the library was built using the RRRRWWWWDDDDEEEEBBBBUUUUGGGG flag, and ssssttttaaaarrrrtttt and
     lllleeeennnn are out of range, then an exception of type RRRRWWWWBBBBoooouuuunnnnddddssssEEEErrrrrrrr will occur.

              RWCSubString
          ooooppppeeeerrrraaaattttoooorrrr(((())))(const RWCRExpr& re, size_t start=0);
          const RWCSubString
          ooooppppeeeerrrraaaattttoooorrrr(((())))(const RWCRExpr& re, size_t start=0) const;
          RWCSubString
          ooooppppeeeerrrraaaattttoooorrrr(((())))(const RWCRegexp& re, size_t start=0);
          const RWCSubString
          ooooppppeeeerrrraaaattttoooorrrr(((())))(const RWCRegexp& re, size_t start=0) const;


     Returns the first substring starting after index ssssttttaaaarrrrtttt that matches the
     regular expression rrrreeee.  If there is no such substring, then the null
     substring is returned.  The first variant can be used as an llllvvvvaaaalllluuuueeee.  Note
     that if you wish to use ooooppppeeeerrrraaaattttoooorrrr(((())))((((ccccoooonnnnsssstttt RRRRWWWWCCCCRRRREEEExxxxpppprrrr&&&&............)))) you must instead
     use mmmmaaaattttcccchhhh((((ccccoooonnnnsssstttt RRRRWWWWCCCCRRRREEEExxxxpppprrrr&&&&............)))) described below.  The reason for this is
     that  we are presently retaining RRRRWWWWCCCCRRRReeeeggggeeeexxxxpppp but ooooppppeeeerrrraaaattttoooorrrr((((ccccoooonnnnsssstttt
     RRRRWWWWCCCCRRRREEEExxxxpppprrrr&&&&............)))) and ooooppppeeeerrrraaaattttoooorrrr((((ccccoooonnnnsssstttt RRRRWWWWCCCCRRRReeeeggggeeeexxxxpppp)))) are ambiguous in the case of
     RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::ooooppppeeeerrrraaaattttoooorrrr((((""""ssssttttrrrriiiinnnngggg""""))))....  In addition, operator((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****)))) and
     operator(ssssiiiizzzzeeee____tttt) are ambiguous in the case of RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::ooooppppeeeerrrraaaattttoooorrrr((((0000)))).
     TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyybbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....  TTTThhhhiiiissss
     ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrr FFFFuuuunnnnccccttttiiiioooonnnnssss
              RWCString&
          aaaappppppppeeeennnndddd(const char* cs);


     Append a copy of the null-terminated character string pointed to by ccccssss to
     self.  Returns a reference to self. TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss
     ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss
     MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              RWCString&
          aaaappppppppeeeennnndddd(const char* cs, size_t N);


     Append a copy of the character string ccccssss to self.  Exactly NNNN bytes are
     copied, iiiinnnncccclllluuuuddddiiiinnnngggg aaaannnnyyyy eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss.  Hence, the buffer pointed to by ccccssss
     must be at least NNNN bytes long.  Returns a reference to self.




                                                                        PPPPaaaaggggeeee 5555






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



              RWCString&
          aaaappppppppeeeennnndddd(char c, size_t N);


     Append NNNN copies of the character cccc to self.  Returns a reference to self.

              RWCString&
          aaaappppppppeeeennnndddd(const RWCString& cstr);


     Append a copy of the string ccccssssttttrrrr to self.  Returns a reference to self.

              RWCString&
          aaaappppppppeeeennnndddd(const RWCString& cstr, size_t N);


     Append the first NNNN bytes or the length of ccccssssttttrrrr (whichever is less) of
     ccccssssttttrrrr to self.  Returns a reference to self.

              size_t
          bbbbiiiinnnnaaaarrrryyyySSSSttttoooorrrreeeeSSSSiiiizzzzeeee() const;


     Returns the number of bytes necessary to store the object using the
     global function:

              RWFile& operator<<(RWFile&, const RWCString&);



              size_t
          ccccaaaappppaaaacccciiiittttyyyy() const;


     Return the current capacity of self.  This is the number of bytes the
     string can hold without resizing.

              size_t
          ccccaaaappppaaaacccciiiittttyyyy(size_t capac);


     Hint to the implementation to change the capacity of self to ccccaaaappppaaaacccc.
     Returns the actual capacity.

              int
          ccccoooollllllllaaaatttteeee(const char* str) const;
          int
          ccccoooollllllllaaaatttteeee(const RWCString& str) const;


     Returns an iiiinnnntttt less then, greater than, or equal to zero, according to
     the result of calling the standard C library function ::::::::ssssttttrrrrccccoooollllllll(((()))) on self



                                                                        PPPPaaaaggggeeee 6666






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     and the argument ssssttttrrrr.  This supports locale-dependent collation.
     Provided only on platforms that provide ::::::::ssssttttrrrrccccoooollllllll(((()))).  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss
     iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....

              int
          ccccoooommmmppppaaaarrrreeeeTTTToooo(const char* str, caseCompare = RWCString::exact) const;
          int
          ccccoooommmmppppaaaarrrreeeeTTTToooo(const RWCString& str,
                    caseCompare = RWCString::exact) const;


     Returns an iiiinnnntttt less than, greater than, or equal to zero, according to
     the result of calling the standard C library function mmmmeeeemmmmccccmmmmpppp(((()))) on self
     and the argument ssssttttrrrr.  Case sensitivity is according to the caseCompare
     argument, and may be RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt or RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::iiiiggggnnnnoooorrrreeeeCCCCaaaasssseeee. If
     ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee is RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt, then this function works for all string
     types....  OOOOtttthhhheeeerrrrwwwwiiiisssseeee,,,, tttthhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss.... Thhhhiiiissss
     ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccoooonnnnsssstttt cccchhhhaaaarrrr**** ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....
     TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccoooonnnnsssstttt cccchhhhaaaarrrr**** MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              RWBoolean
          ccccoooonnnnttttaaaaiiiinnnnssss(const char* str, caseCompare = RWCString::exact)
                   const;
          RWBoolean
          ccccoooonnnnttttaaaaiiiinnnnssss(const RWCString& cs,
                   caseCompare = RWCString::exact) const;


     Pattern matching.  Returns TTTTRRRRUUUUEEEE if ssssttttrrrr occurs in sssseeeellllffff.  Case sensitivity
     is according to the ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee argument, and may be RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt or
     RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::iiiiggggnnnnoooorrrreeeeCCCCaaaasssseeee. If ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee is RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt, then this
     function works for all string types....  OOOOtttthhhheeeerrrrwwwwiiiisssseeee,,,, tttthhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss
     iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss.... Thhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccoooonnnnsssstttt
     cccchhhhaaaarrrr**** ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss.... TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh
     ccccoooonnnnsssstttt cccchhhhaaaarrrr**** MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              const char*
          ddddaaaattttaaaa() const;


     Access to the RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg's data as a null terminated string.  This datum
     is owned by the RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg and may not be deleted or changed.  If the
     RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg object itself changes or goes out of scope, the pointer value
     previously returned will become invalid.  While the string is null
     terminated, note that its lllleeeennnnggggtttthhhh is still given by the member function
     lllleeeennnnggggtttthhhh(((()))).  That is, it may contain embedded nulls.

              size_t
          ffffiiiirrrrsssstttt(char c) const;


     Returns the index of the first occurence of the character cccc in self.



                                                                        PPPPaaaaggggeeee 7777






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no such character or if there is an embedded
     null prior to finding cccc. TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh
     eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              size_t
          ffffiiiirrrrsssstttt(char c, size_t) const;


     Returns the index of the first occurence of the character cccc in self.
     Continues to search past embedded nulls.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no
     such character. TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              size_t
          ffffiiiirrrrsssstttt(const char* str) const;


     Returns the index of the first occurence in self of any character in ssssttttrrrr.
     Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no match or if there is an embedded null
     prior to finding any character from ssssttttrrrr. TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee
     wwwwiiiitttthhhh ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh
     MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              size_t
          ffffiiiirrrrsssstttt(const char* str, size_t N) const;


     Returns the index of the first occurence in self of any character in ssssttttrrrr.
     Exactly NNNN bytes in ssssttttrrrr are checked iiiinnnncccclllluuuuddddiiiinnnngggg aaaannnnyyyy eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss so ssssttttrrrr
     must point to a buffer containing at least NNNN  bytes.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if
     there is no match.

              unsigned
          hhhhaaaasssshhhh(caseCompare = RWCString::exact) const;


     Returns a suitable hash value. IIIIffff ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee iiiissss RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::iiiiggggnnnnoooorrrreeeeCCCCaaaasssseeee
     tttthhhheeeennnn tttthhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn wwwwiiiillllllll bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              size_t
          iiiinnnnddddeeeexxxx(const char* pat,size_t i=0,
                caseCompare = RWCString::exact) const;
          size_t
          iiiinnnnddddeeeexxxx(const RWCString& pat,size_t i=0,
                caseCompare = RWCString::exact) const;


     Pattern matching.  Starting with index iiii, searches for the first
     occurrence of ppppaaaatttt in self and returns the index of the start of the
     match.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no such pattern.  Case sensitivity is
     according to the ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee argument; it defaults to RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt.
     If ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee is RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt, then this function works for all
     string types....  OOOOtttthhhheeeerrrrwwwwiiiisssseeee,,,, tttthhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS



                                                                        PPPPaaaaggggeeee 8888






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     ssssttttrrrriiiinnnnggggssss....

              size_t
          iiiinnnnddddeeeexxxx(const char* pat, size_t patlen,size_t i,
                caseCompare cmp) const;
          size_t
          iiiinnnnddddeeeexxxx(const RWCString& pat, size_t patlen,size_t i,
                caseCompare cmp) const;


     Pattern matching.  Starting with index iiii, searches for the first
     occurrence of the first ppppaaaattttlllleeeennnn bytes from ppppaaaatttt in self and returns the
     index of the start of the match.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no such
     pattern.  Case sensitivity is according to the ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee argument. If
     ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee is RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt, then this function works for all string
     types....  OOOOtttthhhheeeerrrrwwwwiiiisssseeee,,,, tttthhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              size_t
          iiiinnnnddddeeeexxxx(const RWCRExpr& re, size_t i=0) const;
          size_t
          iiiinnnnddddeeeexxxx(const RWCRegexp& re, size_t i=0) const;


     Regular expression matching.  Returns the index greater than or equal to
     iiii of the start of the first pattern that matches the regular expression
     rrrreeee.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no such pattern. TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss
     iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              size_t
          iiiinnnnddddeeeexxxx(const RWCRExpr& re,size_t* ext,size_t i=0) const;
          size_t
          iiiinnnnddddeeeexxxx(const RWCRegexp& re,size_t* ext,size_t i=0) const;


     Regular expression matching.  Returns the index greater than or equal to
     i of the start of the first pattern that matches the regular expression
     rrrreeee.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no such pattern.  The length of the
     matching pattern is returned in the variable pointed to by eeeexxxxtttt. TTTThhhhiiiissss
     ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn
     mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              RWCString&
          iiiinnnnsssseeeerrrrtttt(size_t pos, const char* cs);


     Insert a copy of the null-terminated string ccccssss into self at byte position
     ppppoooossss, thus expanding the string.  Returns a reference to self. TTTThhhhiiiissss
     ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....  TTTThhhhiiiissss
     ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....






                                                                        PPPPaaaaggggeeee 9999






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



              RWCString&
          iiiinnnnsssseeeerrrrtttt(size_t pos, const char* cs, size_t N);


     Insert a copy of the first NNNN bytes of ccccssss into self at byte position ppppoooossss,
     thus expanding the string.  Exactly NNNN bytes are copied, iiiinnnncccclllluuuuddddiiiinnnngggg aaaannnnyyyy
     eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss.  Hence, the buffer pointed to by ccccssss must be at least NNNN
     bytes long.  Returns a reference to self.

              RWCString&
          iiiinnnnsssseeeerrrrtttt(size_t pos, const RWCString& str);


     Insert a copy of the string ssssttttrrrr into self at byte position ppppoooossss.  Returns
     a reference to self.

              RWCString&
          iiiinnnnsssseeeerrrrtttt(size_t pos, const RWCString& str, size_t N);


     Insert a copy of the first NNNN bytes or the length of ssssttttrrrr (whichever is
     less) of ssssttttrrrr into self at byte position ppppoooossss.  Returns a reference to
     self.

              RWBoolean
          iiiissssAAAAsssscccciiiiiiii() const;


     Returns TTTTRRRRUUUUEEEE if self contains no bytes with the high bit set.

              RWBoolean
          iiiissssNNNNuuuullllllll() const;


     Returns TTTTRRRRUUUUEEEE if this is a zero lengthed string (iiii....eeee...., the null string).

              size_t
          llllaaaasssstttt(char c) const;


     Returns the index of the last occurrence in the string of the character
     cccc.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no such character or if there is an
     embedded null to the right of cccc in self. TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee
     wwwwiiiitttthhhh ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh
     MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              size_t
          llllaaaasssstttt(char c, size_t N) const;


     Returns the index of the last occurrence in the string of the character
     cccc.  Continues to search past embedded nulls.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is



                                                                       PPPPaaaaggggeeee 11110000






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     no such character. TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              size_t
          lllleeeennnnggggtttthhhh() const;


     Return the number of bytes in self.  NNNNooootttteeee tttthhhhaaaatttt iiiiffff sssseeeellllffff ccccoooonnnnttttaaaaiiiinnnnssss mmmmuuuullllttttiiiibbbbyyyytttteeee
     cccchhhhaaaarrrraaaacccctttteeeerrrrssss,,,, tttthhhheeeennnn tttthhhhiiiissss wwwwiiiillllllll nnnnooootttt bbbbeeee tttthhhheeee nnnnuuuummmmbbbbeeeerrrr ooooffff cccchhhhaaaarrrraaaacccctttteeeerrrrssss....

              RWCSubString
          mmmmaaaattttcccchhhh(const RWCRExpr& re, size_t start=0);
          const RWCSubString
          mmmmaaaattttcccchhhh(const RWCRExpr& re, size_t start=0) const;


     Returns the first substring starting after index ssssttttaaaarrrrtttt that matches the
     regular expression rrrreeee.  If there is no such substring, then the null
     substring is returned.  The first variant can be used as an lvalue.  Note
     that this is used in place of ooooppppeeeerrrraaaattttoooorrrr(((())))((((ccccoooonnnnsssstttt RRRRWWWWCCCCRRRReeeeggggeeeexxxxpppp&&&&............)))) if you want
     to use extended regular expressions.

              size_t
          mmmmbbbbLLLLeeeennnnggggtttthhhh() const;


     Return the number of multibyte characters in self, according to the
     Standard C function ::::::::mmmmbbbblllleeeennnn(((()))).  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if a bad character is
     encountered.  Note that, in general, mmmmbbbbLLLLeeeennnnggggtttthhhh(((()))) _ lllleeeennnnggggtttthhhh(((()))).  Provided
     only on platforms that provide ::::::::mmmmbbbblllleeeennnn(((()))).

              RWCString&
          pppprrrreeeeppppeeeennnndddd(const char* cs);


     Prepend a copy of the null-terminated character string pointed to by ccccssss
     to self.  Returns a reference to self. TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh
     ccccssss ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh
     ccccssss MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              RWCString&
          pppprrrreeeeppppeeeennnndddd(const char* cs, size_t N);


     Prepend a copy of the character string ccccssss to self.  Exactly NNNN bytes are
     copied, iiiinnnncccclllluuuuddddiiiinnnngggg aaaannnnyyyy eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss.  Hence, the buffer pointed to by ccccssss
     must be at least NNNN bytes long.  Returns a reference to self.

              RWCString&
          pppprrrreeeeppppeeeennnndddd(char c, size_t N);


     Prepend NNNN copies of character cccc to self. Returns a reference to self.



                                                                       PPPPaaaaggggeeee 11111111






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



              RWCString&
          pppprrrreeeeppppeeeennnndddd(const RWCString& str);


     Prepends a copy of the string ssssttttrrrr to self.  Returns a reference to self.

              RWCString&
          pppprrrreeeeppppeeeennnndddd(const RWCString& cstr, size_t N);


     Prepend the first NNNN bytes or the length of ccccssssttttrrrr (whichever is less) of
     ccccssssttttrrrr to self.  Returns a reference to self.

              istream&
          rrrreeeeaaaaddddFFFFiiiilllleeee(istream& s);


     Reads characters from the input stream ssss, replacing the previous contents
     of self, until EEEEOOOOFFFF is reached.  Null characters are treated the same as
     other characters.

              istream&
          rrrreeeeaaaaddddLLLLiiiinnnneeee(istream& s, RWBoolean skipWhite = TRUE);


     Reads characters from the input stream ssss, replacing the previous contents
     of self, until a newline (or an EEEEOOOOFFFF) is encountered. The newline is
     removed from the input stream but is not stored.  Null characters are
     treated the same as other characters.  If the sssskkkkiiiippppWWWWhhhhiiiitttteeee argument is TTTTRRRRUUUUEEEE,
     then whitespace is skipped (using the iostream library manipulator wwwwssss)
     before saving characters.

              istream&
          rrrreeeeaaaaddddSSSSttttrrrriiiinnnngggg(istream& s);


     Reads characters from the input stream ssss, replacing the previous contents
     of self, until an EEEEOOOOFFFF or null terminator is encountered.  If the number
     of bytes remaining in the stream is large, you should resize the
     RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg to approximately the number of bytes to be read prior to using
     this method.  See "Implementation Details" in the User's Guide for more
     information. TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd
     nnnnuuuullllllllssss....  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              istream&
          rrrreeeeaaaaddddTTTTooooDDDDeeeelllliiiimmmm(istream& s, char delim='0);


     Reads characters from the input stream ssss, replacing the previous contents
     of self, until an EEEEOOOOFFFF or the delimiting character ddddeeeelllliiiimmmm is encountered.
     The delimiter is removed from the input stream but is not stored.  Null
     characters are treated the same as other characters. IIIIffff ddddeeeelllliiiimmmm iiiissss '''' '''' tttthhhheeeennnn



                                                                       PPPPaaaaggggeeee 11112222






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     tttthhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss.... IIIIffff ddddeeeelllliiiimmmm
     iiiissss '''' '''' tttthhhheeeennnn tttthhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              istream&
          rrrreeeeaaaaddddTTTTooookkkkeeeennnn(istream& s);


     Whitespace is skipped before saving characters. Characters are then read
     from the input stream ssss, replacing previous contents of self, until
     trailing whitespace or an EEEEOOOOFFFF is encountered. The whitespace is left on
     the input stream.  Null characters are treated the same as other
     characters.  Whitespace is identified by the standard C library function
     iiiissssssssppppaaaacccceeee(((()))).  Thhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              RWCString&
          rrrreeeemmmmoooovvvveeee(size_t pos);


     Removes the bytes from the byte position ppppoooossss, which must be no greater
     than lllleeeennnnggggtttthhhh(((()))), to the end of string.  Returns a reference to self.

              RWCString&
          rrrreeeemmmmoooovvvveeee(size_t pos, size_t N);


     Removes NNNN bytes or to the end of string (whichever comes first) starting
     at the byte position ppppoooossss, which must be no greater than lllleeeennnnggggtttthhhh(((()))).
     Returns a reference to self.

              RWCString&
          rrrreeeeppppllllaaaacccceeee(size_t pos, size_t N, const char* cs);


     Replaces NNNN bytes or to the end of string (whichever comes first) starting
     at byte position ppppoooossss, which must be no greater than lllleeeennnnggggtttthhhh(((()))), with a copy
     of the null-terminated string ccccssss.  Returns a reference to self. Thhhhiiiissss
     ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....  TTTThhhhiiiissss
     ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              RWCString&
          rrrreeeeppppllllaaaacccceeee(size_t pos, size_t N1,const char* cs, size_t N2);


     Replaces NNNN1111 bytes or to the end of string (whichever comes first)
     starting at byte position ppppoooossss, which must be no greater than lllleeeennnnggggtttthhhh(((()))),
     with a copy of the string ccccssss.  Exactly NNNN2222 bytes are copied, iiiinnnncccclllluuuuddddiiiinnnngggg aaaannnnyyyy
     eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss.  Hence, the buffer pointed to by ccccssss must be at least NNNN2222
     bytes long.  Returns a reference to self.

              RWCString&
          rrrreeeeppppllllaaaacccceeee(size_t pos, size_t N, const RWCString& str);




                                                                       PPPPaaaaggggeeee 11113333






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     Replaces NNNN bytes or to the end of string (whichever comes first) starting
     at byte position ppppoooossss, which must be no greater than lllleeeennnnggggtttthhhh(((()))), with a copy
     of the string ssssttttrrrr.  Returns a reference to self.

              RWCString&
          rrrreeeeppppllllaaaacccceeee(size_t pos, size_t N1,const RWCString& str, size_t N2);


     Replaces NNNN1111 bytes or to the end of string (whichever comes first)
     starting at position ppppoooossss, which must be no greater than lllleeeennnnggggtttthhhh(((()))), with a
     copy of the first NNNN2222 bytes, or the length of ssssttttrrrr (whichever is less),
     from ssssttttrrrr.  Returns a reference to self.

              rrrreeeeppppllllaaaacccceeee(const RWCRExpr& pattern, const char* replacement,
                  scopeType scope=one);
          rrrreeeeppppllllaaaacccceeee(const RWCRExpr& pattern,
                  const RWCString& replacement,scopeType scope=one);


     Replaces substring matched by ppppaaaatttttttteeeerrrrnnnn with replacement string.   ppppaaaatttttttteeeerrrrnnnn
     is the new extended regular expression.  ssssccccooooppppeeee is one of {oooonnnneeee, aaaallllllll} and
     controls whether all matches of pattern are replaced with rrrreeeeppppllllaaaacccceeeemmmmeeeennnntttt or
     just the first one match is replaced.  rrrreeeeppppllllaaaacccceeeemmmmeeeennnntttt is the replacement
     pattern for the string.  Here's an example:

              RWCString s("hahahohoheehee");



              s.replace(RWCRExpr("(ho)+","HAR"); // s == "hahaHARheehee"


     Thhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccoooonnnnsssstttt cccchhhhaaaarrrr**** rrrreeeeppppllllaaaacccceeeemmmmeeeennnntttt ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh
     eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccoooonnnnsssstttt cccchhhhaaaarrrr****
     rrrreeeeppppllllaaaacccceeeemmmmeeeennnntttt MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              void
          rrrreeeessssiiiizzzzeeee(size_t n);


     Changes the length of self to nnnn bytes, adding blanks or truncating as
     necessary.

              RWCSubString
          ssssttttrrrriiiipppp(stripType s = RWCString::trailing, char c = ' ');
          const RWCSubString
          ssssttttrrrriiiipppp(stripType s = RWCString::trailing, char c = ' ')
          const;


     Returns a substring of self where the character cccc has been stripped off
     the beginning, end, or both ends of the string.  The first variant can be



                                                                       PPPPaaaaggggeeee 11114444






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     used as an lvalue.  The enum ssssttttrrrriiiippppTTTTyyyyppppeeee can take values:






     ssssttttrrrriiiippppTTTTyyyyppppeeeeMMMMeeeeaaaannnniiiinnnngggg


     lllleeeeaaaaddddiiiinnnnggggRemove characters at beginning


     ttttrrrraaaaiiiilllliiiinnnnggggRemove characters at end


     bbbbooootttthhhhRemove characters at both ends


          RWCSubString
          ssssuuuubbbbSSSSttttrrrriiiinnnngggg(const char* cs, size_t start=0,
                    caseCompare = RWCString::exact);
          const RWCSubString
          ssssuuuubbbbSSSSttttrrrriiiinnnngggg(const char* cs, size_t start=0,
                    caseCompare = RWCString::exact) const;


     Returns a substring representing the first occurence of the null-
     terminated string pointed to by "ccccssss".  The first variant can be used as
     an lvalue.  Case sensitivity is according to the ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee argument; it
     defaults to RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt.   IIIIffff ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee iiiissss RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::iiiiggggnnnnoooorrrreeeeCCCCaaaasssseeee
     tttthhhheeeennnn tttthhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss
     iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee
     iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccssss MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              void
          ttttooooLLLLoooowwwweeeerrrr();


     Changes all upper-case letters in self to lower-case, using the standard
     C library facilities declared in <<<<ccccttttyyyyppppeeee....hhhh>>>>.... TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee
     wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              void
          ttttooooUUUUppppppppeeeerrrr();


     Changes all lower-case letters in self to upper-case, using the standard
     C library facilities declared in <<<<ccccttttyyyyppppeeee....hhhh>>>>.... TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee






                                                                       PPPPaaaaggggeeee 11115555






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

SSSSttttaaaattttiiiicccc PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrr FFFFuuuunnnnccccttttiiiioooonnnnssss
              static unsigned
          hhhhaaaasssshhhh(const RWCString& str);


     Returns the hash value of ssssttttrrrr as returned by ssssttttrrrr....hhhhaaaasssshhhh((((RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt)))).

              static size_t
          iiiinnnniiiittttiiiiaaaallllCCCCaaaappppaaaacccciiiittttyyyy(size_t ic = 15);


     Sets the minimum initial capacity of an RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg, and returns the old
     value.  The initial setting is 15 bytes. Larger values will use more
     memory, but result in fewer resizes when concatenating or reading
     strings. Smaller values will waste less memory, but result in more
     resizes.

              static size_t
          mmmmaaaaxxxxWWWWaaaasssstttteeee(size_t mw = 15);


     Sets the maximum amount of unused space allowed in a string should it
     shrink, and returns the old value.  The initial setting is 15 bytes.  If
     more than mmmmwwww bytes are wasted, then excess space will be reclaimed.

              static size_t
          rrrreeeessssiiiizzzzeeeeIIIInnnnccccrrrreeeemmmmeeeennnntttt(size_t ri = 16);


     Sets the resize increment when more memory is needed to grow a string.
     Returns the old value.  The initial setting is 16 bytes.

RRRReeeellllaaaatttteeeedddd GGGGlllloooobbbbaaaallll OOOOppppeeeerrrraaaattttoooorrrrssss
              RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr========(const RWCString&, const char*     );
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr========(const char*,      const RWCString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr========(const RWCString&, const RWCString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr!!!!====(const RWCString&, const char*     );
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr!!!!====(const char*,      const RWCString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr!!!!====(const RWCString&, const RWCString&);


     Logical equality and inequality.  Case sensitivity is eeeexxxxaaaacccctttt. Thhhhiiiissss
     ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccoooonnnnsssstttt cccchhhhaaaarrrr**** ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....
     TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccoooonnnnsssstttt cccchhhhaaaarrrr**** MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....



                                                                       PPPPaaaaggggeeee 11116666






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



              RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr<<<< (const RWCString&, const char*     );
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr<<<< (const char*,      const RWCString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr<<<< (const RWCString&, const RWCString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr>>>> (const RWCString&, const char*     );
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr>>>> (const char*,      const RWCString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr>>>> (const RWCString&, const RWCString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr<<<<====(const RWCString&, const char*     );
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr<<<<====(const char*,      const RWCString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr<<<<====(const RWCString&, const RWCString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr>>>>====(const RWCString&, const char*     );
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr>>>>====(const char*,      const RWCString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr>>>>====(const RWCString&, const RWCString&);


     Comparisons are done lexicographically, byte by byte.  Case sensitivity
     is eeeexxxxaaaacccctttt.  Use member ccccoooollllllllaaaatttteeee(((()))) or ssssttttrrrrxxxxffffrrrrmmmm(((()))) for locale sensitivity. TTTThhhhiiiissss
     ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccoooonnnnsssstttt cccchhhhaaaarrrr**** ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....
     TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccoooonnnnsssstttt cccchhhhaaaarrrr**** MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              RWCString
          ooooppppeeeerrrraaaattttoooorrrr++++(const RWCString&, const RWCString&);
          RWCString
          ooooppppeeeerrrraaaattttoooorrrr++++(const char*,      const RWCString&);
          RWCString
          ooooppppeeeerrrraaaattttoooorrrr++++(const RWCString&, const char*     );


     Concatenation operators. TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccoooonnnnsssstttt cccchhhhaaaarrrr****
     ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss.... TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn mmmmaaaayyyy bbbbeeee iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh ccccoooonnnnsssstttt
     cccchhhhaaaarrrr**** MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              ostream&
          ooooppppeeeerrrraaaattttoooorrrr<<<<<<<<(ostream& s, const RWCString&);


     Output an RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg on ostream ssss.

              istream&
          ooooppppeeeerrrraaaattttoooorrrr>>>>>>>>(istream& s, RWCString& str);




                                                                       PPPPaaaaggggeeee 11117777






RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     Calls ssssttttrrrr....rrrreeeeaaaaddddTTTTooookkkkeeeennnn((((ssss)))).  That is, a token is read from the input stream
     ssss. Thhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              RWvostream&
          ooooppppeeeerrrraaaattttoooorrrr<<<<<<<<(RWvostream&, const RWCString& str);
          RWFile&
          ooooppppeeeerrrraaaattttoooorrrr<<<<<<<<(RWFile&,     const RWCString& str);


     Saves string ssssttttrrrr to a virtual stream or RRRRWWWWFFFFiiiilllleeee, respectively.

              RWvistream&
          ooooppppeeeerrrraaaattttoooorrrr>>>>>>>>(RWvistream&, RWCString& str);
          RWFile&
          ooooppppeeeerrrraaaattttoooorrrr>>>>>>>>(RWFile&,     RWCString& str);


     Restores a string into ssssttttrrrr from a virtual stream or RRRRWWWWFFFFiiiilllleeee, respectively,
     replacing the previous contents of ssssttttrrrr.

RRRReeeellllaaaatttteeeedddd GGGGlllloooobbbbaaaallll FFFFuuuunnnnccccttttiiiioooonnnnssss
              RWCString
          ssssttttrrrrXXXXFFFFoooorrrrmmmm(const RWCString&);


     Returns the result of applying ::::::::ssssttttrrrrxxxxffffrrrrmmmm(((()))) to the argument string, to
     allow quicker collation than RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::ccccoooollllllllaaaatttteeee(((())))....  Provided only on
     platforms that provide ::::::::ssssttttrrrrxxxxffffrrrrmmmm(((()))).  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh
     ssssttttrrrriiiinnnnggggssss wwwwiiiitttthhhh eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss....

              RWCString
          ttttooooLLLLoooowwwweeeerrrr(const RWCString& str);


     Returns a version of ssssttttrrrr where all upper-case characters have been
     replaced with lower-case characters.  Uses the standard C library
     function ttttoooolllloooowwwweeeerrrr(((()))).  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....

              RWCString
          ttttooooUUUUppppppppeeeerrrr(const RWCString& str);


     Returns a version of ssssttttrrrr where all lower-case characters have been
     replaced with upper-case characters.  Uses the standard C library
     function ttttoooouuuuppppppppeeeerrrr(((()))).  TTTThhhhiiiissss ffffuuuunnnnccccttttiiiioooonnnn iiiissss iiiinnnnccccoooommmmppppaaaattttiiiibbbblllleeee wwwwiiiitttthhhh MMMMBBBBCCCCSSSS ssssttttrrrriiiinnnnggggssss....










                                                                       PPPPaaaaggggeeee 11118888