RWWSubString(3C++)

Name
     RWWSubString - Rogue Wave library class

Synopsis
              #include <rw/wstring.h>



              RWWString s(L"test string");
          s(6,3);   // "tri"




Description
     The class RWWSubString allows some subsection of an RWWString to be
     addressed by defining a starting position and an extent.  For example the
     7th through the 11th elements, inclusive, would have a starting position
     of 7 and an extent of 5.  The specification of a starting position and
     extent can also be done in your behalf by such functions as
     RWWString::strip() or the overloaded function call operator taking a
     regular expression as an argument.  There are no public constructors --
     RWWSubStrings are constructed by various functions of the RWWString class
     and then destroyed immediately.  A zero lengthsubstring is one with a
     defined starting position and an extent of zero.  It can be thought of as
     starting just before the indicated character, but not including it.  It
     can be used as an lvalue.  A null substring is also legal and is
     frequently used to indicate that a requested substring, perhaps through a
     search, does not exist.  A null substring can be detected with member
     function isNull().  However, it cannot be used as an lvalue.

Persistence
     None

Example
              #include <rw/rstream.h>
          #include <rw/wstring.h>
          main(){
           RWWString s(L"What I tell you is true.");
           // Create a substring and use it as an lvalue:
           s(15,0) = RWWString(L" three times");
           cout << s << endl;
           return 0;
          }


     Program output:

              What I tell you three times is true.

Assignment Operators




              void
          operator=(const RWWString&);


     Assignment from an RWWString.  The statements:

              RWWString a;



              RWWString b;
          b(2, 3) = a;


     will copy a's data into the substring b(2,3).  The number of elements
     need not match: if they differ, b will be resized appropriately.  If self
     is the null substring, then the statement has no effect.

              void
          operator=(const wchar_t*);


     Assignment from a wide character string.  Example:

              RWWString wstr(L"Mary had a little lamb");



              wchar_t dat[] = L"Perrier";
          wstr(11,4) = dat;     // "Mary had a Perrier"


     Note that the number of characters selected need not match: if they
     differ, wstr will be resized appropriately.  If self is the null
     substring, then the statement has no effect.

Indexing Operators
              wchar_t
          operator[](size_t i);
          wchar_t&
          operator[](size_t i) const;


     Returns the ith character of the substring.  The first variant can be
     used as an lvalue, the second cannot.  The index i must be between zero
     and the length of the substring less one.  Bounds checking is performed:
     if the index is out of range, then an exception of type RWBoundsErr will
     be thrown.

              wchar_t
          operator()(size_t i);
          wchar_t&
          operator()(size_t i) const;


     Returns the ith character of the substring.  The first variant can be
     used as an lvalue, the second cannot.  The index i must be between zero
     and the length of the substring less one.  Bounds checking is enabled by
     defining the pre-processor macro RWBOUNDS_CHECK before including
     <rw/wstring.h>.  In that case, if the index is out of range, then an
     exception of type RWBoundsErr will be thrown.

Public Member Functions
              RWBoolean
          isNull() const;


     Returns TRUE if this is a null substring.

              size_t
          length() const;


     Returns the extent (length) of the RWWSubString.

              RWBoolean
          operator!() const;


     Returns TRUE if this is a null substring.

              size_t
          start() const;


     Returns the starting element of the RWWSubString.

              void
          toLower();


     Changes all upper-case letters in self to lower-case. Uses the C library
     function towlower().

              void
          toUpper();


     Changes all lower-case letters in self to upper-case. Uses the C library
     function towupper().

Global Logical Operators
              RWBoolean
          operator==(const RWWSubString&, const RWWSubString&);
          RWBoolean
          operator==(const RWWString&,    const RWWSubString&);
          RWBoolean
          operator==(const RWWSubString&, const RWWString&   );
          RWBoolean
          operator==(const wchar_t*,      const RWWSubString&);
          RWBoolean
          operator==(const RWWSubString&, const wchar_t*     );


     Returns TRUE if the substring is lexicographically equal to the wide
     character string or RWWString argument.  Case sensitivity is exact.

              RWBoolean
          operator!=(const RWWString&,    const RWWString&   );
          RWBoolean
          operator!=(const RWWString&,    const RWWSubString&);
          RWBoolean
          operator!=(const RWWSubString&, const RWWString&   );
          RWBoolean
          operator!=(const wchar_t*,      const RWWString&   );
          RWBoolean
          operator!=(const RWWString&,    const wchar_t*     );


     Returns the negation of the respective operator==()