RWClassicWString

Module:  Essential Tools Module   Group:  String Processing Classes

Does not inherit

• Local Index
• Synopsis
• Description
• Persistence
• Example
• Enumerations
• Public Constructors
• Type Conversion
• Assignment Operators
• Indexing Operators
• Public Member Functions
• Static Public Member Functions
• Related Global Operators
• Related Global Functions

Members

append() binaryStoreSize() capacity() collate() compareTo() const wchar_t*() contains() data() first() fromAscii() fromMultiByte() hash()

index() initialCapacity() insert() isAscii() isNull() last() length() maxWaste() operator()() operator+=() operator=() operator[]()

prepend() readFile() readLine() readString() readToDelim() readToken() remove() replace() resize() resizeIncrement() RWClassicWString() RWClassicWString::ascii_

RWClassicWString::caseCompare RWClassicWString::multiByte_ scopeType strip() stripType subString() toAscii() toLower() toMultiByte() toUpper()

Non-Members

operator!=() operator>>() operator>()

operator>=() operator<<() operator<()

operator<=() operator+() operator==()

strXForm() toLower() toUpper()

#include <rw/tools/nostl/wstring.h>

RWClassicWString is an alternate implementation of RWWString, but does not depend on the C++ Standard Library. RWWString is a typedef for RWClassicWString if you define a non-standard library build.

---

NOTE -- Rogue Wave does not support non-standard library builds.

---

For more information on how to use this class, see the Description section of RWWString in this reference guide.

Simple

#include <rw/rstream.h>
#include <rw/wstring.h>

main(){
 RWClassicWString a(L"There is no joy in Beantown");
 a.subString(L"Beantown") = L"Redmond";
 cout << a << endl;
 return 0;
}

Program output:

There is no joy in Redmond.

enum stripType   
               {leading = 0x1, trailing = 0x2, both = 0x3};

Used to specify whether characters are stripped from the beginning of the string, the end, or both.

enum RWClassicWString::caseCompare 
               { exact, ignoreCase, ignoreCaseStrict };

Used to specify whether comparisons, searches, and hashing functions should use exact (case sensitive), ignoreCase (case-insensitive) or ignoreCaseStrict (case-insensitive for alpha characters only).

enum scopeType   {one, all};

Used to specify whether to replace the first substring matched by the regular expression or all matched substrings.

enum RWClassicWString::multiByte_ { multiByte };

Allows conversion from multibyte character strings to wide character strings. See constructor below.

enum RWClassicWString::ascii_ {ascii };

Allows conversion from ASCII character strings to wide character strings. See constructor below.

RWClassicWString();

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

RWClassicWString(wchar_t);

Constructs a string containing a single wide character.

RWClassicWString(const wchar_t* cs);

Creates a string from the wide character string cs. The created string will copy the data pointed to by cs, up to the first terminating null.

RWClassicWString(const wchar_t* cs, size_t N);

Constructs a string from the character string cs. The created string will copy the data pointed to by cs. Exactly N characters are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N* sizeof(wchar_t) bytes or N wide characters long.

RWClassicWString(RWSize_T ic);

Creates a string of length zero (the null string). The string's capacity (that is, the size it can grow to without resizing) is given by the parameter ic.

RWClassicWString(const RWClassicWString& str); 

Copy constructor. The created string will copy str's data.

RWClassicWString(const RWClassicWSubString& ss);

Conversion from sub-string. The created string will copy the substring represented by ss.

RWClassicWString(char c);

Constructs a wide character string from the single character c.

RWClassicWString(char c, size_t N);

Constructs a string containing the character c repeated N times.

RWClassicWString(const char* mbcs, multiByte_ mb);
RWClassicWString(const RWClassicCString& cstr, multiByte_);

Constructs a wide character string from the multibyte character string contained in mbcs. The conversion is done using the Standard C library function ::mbstowcs(). This constructor can be used as follows:

RWClassicWString a("\306\374\315\313\306\374", multiByte);

RWClassicWString(const char* mbcs, size_t N, multiByte_ mb)

Same as above, but converts exactly N characters, including any embedded nulls. Hence, the buffer pointed to by mbcs must be at lest N bytes long.

RWClassicWString(const char* acs, ascii_ asc);
RWClassicWString(const RWClassicCString&, ascii_);

Constructs a wide character string from an ASCII character string. The conversion is done by simply stripping the high-order bit and, hence, is much faster than the more general constructor given immediately above. For this conversion to be successful, you must be certain that the string contains only ASCII characters. This can be confirmed (if necessary) using RWCString::isAscii(). This constructor can be used as follows:

   RWClassicWString a("An ASCII character string", ascii);

RWClassicWString(const char* cs, size_t N, ascii_ asc);

Same as above, but converts exactly N characters, including any embedded nulls.

operator
const wchar_t*() const 

Access to the RWClassicWString's data as a null terminated wide string. This datum is owned by the RWClassicWString and may not be deleted or changed. If the RWClassicWString 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 length is still given by the member function length(). That is, it may contain embedded nulls.

RWClassicWString&
operator=(const wchar_t*);

Assignment operator. Copies a null-terminated character string into self. Returns a reference to self.

RWClassicWString&
operator=(const RWClassicWString&);

Assignment operator. Returns a reference to self.

RWClassicWString&
operator+=(const wchar_t*); 

Appends a null-terminated character string. Returns a reference to self.

RWClassicWString&
operator+=(const RWClassicWString& s);

Appends the string s to self. Returns a reference to self.

wchar_t&
operator[](short i); 
wchar_t&            
operator[](int i);
  wchar_t&            
operator[](long i);
  wchar_t&            
operator[](unsigned short i);
  wchar_t&            
operator[](unsigned int i);
  wchar_t&            
operator[](unsigned long i);
wchar_t             
operator[](short i)           const;
wchar_t             
operator[](int i)             const;
wchar_t             
operator[](long i)            const;
wchar_t             
operator[](unsigned short i)  const;
wchar_t             
operator[](unsigned int i)    const;
wchar_t             
operator[](unsigned long i)   const;

Returns the ith character. The first variant can be used as an lvalue. The index i 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 exception of type RWBoundsErr is thrown.

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

Returns the ith character. The first variant can be used as an lvalue. The index i must be between 0 and the length of the string less one. Bounds checking is performed if the pre-processor macro RWBOUNDS_CHECK has been defined before including <rw/wstring.h>. In this case, if the index is out of range, then an exception of type RWBoundsErr is thrown.

RWClassicWSubString
operator()(size_t start, size_t len); 
const RWClassicWSubString
operator()(size_t start, size_t len) const;

Substring operator. Returns an RWClassicWSubString of self with length len, starting at index start. The first variant can be used as an lvalue. The sum of start plus len must be less than or equal to the string length. If the library was built using the RW_DEBUG flag, and start and len are out of range, then an exception of type RWBoundsErr is thrown.

RWClassicWString&
append(const wchar_t* cs); 

Appends a copy of the null-terminated wide character string pointed to by cs to self. Returns a reference to self.

RWClassicWString&
append(const wchar_t* cs, size_t N,);

Appends a copy of the wide character string cs to self. Exactly N wide characters are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N*sizeof(wchar_t) bytes long. Returns a reference to self.

RWClassicWString&
append(const RWClassicWString& s);

Appends a copy of the string s to self. Returns a reference to self.

RWClassicWString&
append(const RWClassicWString& s, size_t N);

Appends the first N characters or the length of s (whichever is less) to self. Returns a reference to self.

RWClassicWString&    
append(wchar_t c, size_t rep=1);        

Appends c rep times. The default is 1.

size_t
binaryStoreSize() const; 

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

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

size_t
capacity() const; 

Returns the current capacity of self. This is the number of characters the string can hold without resizing.

size_t
capacity(size_t N); 

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

int
collate(const RWClassicWString& str) const; 
int
collate(const wchar_t* str) const 

Returns an int less then, greater than, or equal to zero, according to the result of calling the POSIX function ::wscoll() on self and the argument str. This supports locale-dependent collation.

int
compareTo(const RWClassicWString& str, 
          caseCompare RWClassicWString::exact) const
int  
compareTo(const RWClassicWString* str, 
          caseCompare RWClassicWString::exact)
int
compareTo(const wchar_t* cs,   
          caseCompare cmp = exact) const

Returns an int less than, greater than, or equal to zero, according to the result of calling the Standard C library function ::memcmp() on self and the argument st. Case sensitivity is according to the caseCompare argument, and may be RWClassicWString::exact or RWClassicWString::ignoreCase.

bool
contains(const wchar_t* cs,   
         caseCompare cmp = exact) const;
contains(const RWClassicWString& str, 
         caseCompare RWClassicWString::exact) const;

Pattern matching. Returns true if str occurs in self. Case sensitivity is according to the caseCompare argument, and may be RWClassicWString::exact or RWClassicWString::ignoreCase.

const wchar_t*
data() const; 

Access to the RWClassicWString's data as a null terminated string. This datum is owned by the RWClassicWString and may not be deleted or changed. If the RWClassicWString 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 length is still given by the member function length(). That is, it may contain embedded nulls.

size_t
first(wchar_t c) const; 

Returns the index of the first occurrence of the wide character c in self. Returns RW_NPOS if there is no such character or if there is an embedded null prior to finding c.

size_t   
first(wchar_t c,size_t i) const

Starting with index i, returns the index of the first occurrence of the wide character c in self. Continues to search past embedded nulls. Returns RW_NPOS if there is no such character.

size_t
first(const wchar_t* cs) const;

Returns the index of the first occurrence in self of any character in cs. Returns RW_NPOS if there is no match or if there is an embedded null prior to finding any character from cs.

size_t
first(const wchar_t* cs, size_t N) const;

Returns the index of the first occurrence in self of any character in cs. Exactly N characters in str are checked including any embedded nulls so str must point to a buffer containing at least N wide characters. Returns RW_NPOS if there is no match.

unsigned
hash(caseCompare cmp = exact) const; 

Returns a suitable hash value.

size_t
index(const wchar_t* pat, size_t i=0, 
      caseCompare cmp = exact) const;
size_t
index(const RWClassicWString& pat,size_t i=0, 
      caseCompare cmp = exact) const;

Pattern matching. Starting with index i, searches for the first occurrence of pat in self and returns the index of the start of the match. Returns RW_NPOS if there is no such pattern. Case sensitivity is according to the caseCompare argument; it defaults to RWClassicWString::exact.

size_t
index(const wchar_t* pat, size_t patlen,size_t i, 
      caseCompare cmp) const;
size_t
index(const RWClassicWString& s, size_t patlen,size_t i, 
      caseCompare) const;

Pattern matching. Starting with index i, searches for the first occurrence of the first patlen characters from s in self and returns the index of the start of the match. Returns RW_NPOS if there is no such pattern. Case sensitivity is according to the caseCompare argument.

RWClassicWString&
insert(size_t pos, const wchar_t* cs); 

Inserts a copy of the null-terminated string cs into self at position pos. Returns a reference to self.

RWClassicWString&
insert(size_t pos, const wchar_t* cs, size_t N);

Insert a copy of the first N wide characters of cs into self at position pos. Exactly N wide characters are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N*sizeof(wchar_t) bytes long. Returns a reference to self.

RWClassicWString&
insert(size_t pos, const RWClassicWString& str);

Inserts a copy of the string str into self at position pos. Returns a reference to self.

RWClassicWString&
insert(size_t pos, const RWClassicWString& str, size_t N);

Inserts a copy of the first N wide characters or the length of str (whichever is less) of str into self at position pos. Returns a reference to self.

bool
isAscii() const; 

Returns true if it is safe to perform the conversion toAscii() (that is, if all characters of self are ASCII characters).

bool
isNull() const; 

Returns true if this string has zero length (i.e., the null string).

size_t
last(wchar_t c) const; 

Returns the index of the last occurrence in the string of the wide character c. Returns RW_NPOS if there is no such character.

size_t
length() const; 

Returns the number of characters in self.

RWClassicWString&
prepend(const wchar_t* cs); 

Prepends a copy of the null-terminated wide character string pointed to by cs to self. Returns a reference to self.

RWClassicWString&
prepend(const wchar_t* cs, size_t N,);

Prepends a copy of the character string cs to self. Exactly N characters are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N*sizeof(wchar_t) bytes long. Returns a reference to self.

RWClassicWString&
prepend(const RWClassicWString& str);

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

RWClassicWString&
prepend(const RWClassicWString& cstr, size_t N);

Prepends the first N wide characters or the length of cstr (whichever is less) of cstr to self. Returns a reference to self.

istream&
readFile(istream& s); 

Reads characters from the input stream s, replacing the previous contents of self, until EOF is reached. The input stream is treated as a sequence of multibyte characters, each of which is converted to a wide character (using the Standard C library function mbtowc()) before storing. Null characters are treated the same as other characters.

istream&
readLine(istream& s, bool skipWhite = true); 

Reads characters from the input stream s, replacing the previous contents of self, until a newline (or an EOF) is encountered. The newline is removed from the input stream, but is not stored. The input stream is treated as a sequence of multibyte characters, each of which is converted to a wide character (using the Standard C library function mbtowc()) before storing. Null characters are treated the same as other characters. If the skipWhite argument is true, then whitespace is skipped (using the iostream library manipulator ws) before saving characters.

istream&
readString(istream& s); 

Reads characters from the input stream s, replacing the previous contents of self, until an EOF or null terminator is encountered. The input stream is treated as a sequence of multibyte characters, each of which is converted to a wide character (using the Standard C library function mbtowc()) before storing.

istream&
readToDelim(istream&, wchar_t delim=(wchar_t)'\n'); 

Reads characters from the input stream s, replacing the previous contents of self, until an EOF or the delimiting character delim is encountered. The delimiter is removed from the input stream but is not stored. The input stream is treated as a sequence of multibyte characters, each of which is converted to a wide character (using the Standard C library function mbtowc()) before storing. Null characters are treated the same as other characters.

istream&
readToken(istream& s); 

Whitespace is skipped before storing characters into wide string. Characters are then read from the input stream s, replacing previous contents of self, until trailing whitespace or an EOF is encountered. The trailing whitespace is left on the input stream. Only ASCII whitespace characters are recognized, as defined by the standard C library function isspace(). The input stream is treated as a sequence of multibyte characters, each of which is converted to a wide character (using the Standard C library function mbtowc()) before storing.

RWClassicWString&
remove(size_t pos); 

Removes the characters from the position pos, which must be no greater than length(), to the end of string. Returns a reference to self.

RWClassicWString&
remove(size_t pos, size_t N); 

Removes N wide characters or to the end of string (whichever comes first) starting at the position pos, which must be no greater than length(). Returns a reference to self.

RWClassicWString&
replace(size_t pos, size_t N, const wchar_t* cs); 

Replaces N wide characters or to the end of string (whichever comes first) starting at position pos, which must be no greater than length(), with a copy of the null-terminated string cs. Returns a reference to self.

RWClassicWString&
replace(size_t pos, size_t N1,const wchar_t* cs, size_t N2);

Replaces N1 characters or to the end of string (whichever comes first) starting at position pos, which must be no greater than length(), with a copy of the string cs. Exactly N2 characters are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N2*sizeof(wchar_t) bytes long. Returns a reference to self.

RWClassicWString&
replace(size_t pos, size_t N, const RWClassicWString& str);

Replaces N characters or to the end of string (whichever comes first) starting at position pos, which must be no greater than length(), with a copy of the string str. Returns a reference to self.

RWClassicWString&
replace(size_t pos, size_t N1,
        const RWClassicWString& str, size_t N2);

Replaces N1 characters or to the end of string (whichever comes first) starting at position pos, which must be no greater than length(), with a copy of the first N2 characters, or the length of str (whichever is less), from str. Returns a reference to self.

void
resize(size_t n); 

Changes the length of self, adding blanks (i.e., L' ') or truncating as necessary.

RWClassicWSubString
strip(stripType s = RWClassicWString::trailing, 
       wchar_t c = L' '); 
const RWClassicWSubString
strip(stripType s = RWClassicWString::trailing, 
       wchar_t c = L' ') const;

Returns a substring of self where the character c has been stripped off the beginning, end, or both ends of the string. The first variant can be used as an lvalue. The enum stripType can take values:

Table 13: RWClassicWString stripType Values

stripType	Meaning
leading	Remove characters at beginning
trailing	Remove characters at end
both	Remove characters at both ends

RWClassicWSubString
subString(const wchar_t* cs, size_t start=0, 
          caseCompare = RWClassicWString::exact);
RWClassicWSubString
subString(const wchar_t* cs, size_t start=0,
          caseCompare = RWClassicWString::exact) const;

Returns a substring representing the first occurrence of the null-terminated string pointed to by cs. Case sensitivity is according to the caseCompare argument, defaulting to RWClassicWString::exact. The first variant can be used as an lvalue.

RWClassicCString 
toAscii() const; 

Returns an RWClassicCString object of the same length as self, containing only ASCII characters. Any non-ASCII characters in self simply have the high bits stripped off. Use isAscii() to determine whether this function is safe to use.

void
toLower();

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

RWClassicCString
toMultiByte() const; 

Returns an RWClassicCString containing the result of applying the standard C library function wcstombs() to self. This function is always safe to use.

void
toUpper();

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

static RWClassicWString
fromAscii(const RWClassicCString& str)

Convenience member function. Returns the result of the constructor RWClassicWString(const RWClassicCString&, RWClassicWString::ascii).

static RWClassicWString
fromMultiByte(const RWClassicCString& str)

Convenience member function. Returns the result of the constructor RWClassicWString(const RWClassicCString&, RWClassicWString::multiByte).

static unsigned
hash(const RWClassicWString& wstr); 

Returns the hash value of wstr as returned by wstr.hash(RWClassicWString::exact).

static size_t
initialCapacity(size_t ic = 15); 

Sets the minimum initial capacity of an RWClassicWString, and returns the old value. The initial setting is 15 wide characters. 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
maxWaste(size_t mw = 15); 

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

static size_t
resizeIncrement(size_t ri = 16); 

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

bool
operator==(const RWClassicWString&, const wchar_t*  ); 
bool
operator==(const wchar_t*,          const RWClassicWString&);
bool
operator==(const RWClassicWString&, const RWClassicWString&);
bool
operator!=(const RWClassicWString&, const wchar_t*  );
bool
operator!=(const wchar_t*,          const RWClassicWString&);
bool
operator!=(const RWClassicWString&, const RWClassicWString&);

Logical equality and inequality. Case sensitivity is exact.

bool
operator< (const RWClassicWString&,  const wchar_t*  ); 
bool
operator< (const wchar_t*,           const RWClassicWString&);
bool
operator< (const RWClassicWString&,  const RWClassicWString&);
bool
operator> (const RWClassicWString&,  const wchar_t*  ); 
bool
operator> (const wchar_t*,           const RWClassicWString&);
bool
operator> (const RWClassicWString&,  const RWClassicWString&);
bool
operator<=(const RWClassicWString&,  const wchar_t*  ); 
bool
operator<=(const wchar_t*,           const RWClassicWString&);
bool
operator<=(const RWClassicWString&,  const RWClassicWString&);
bool
operator>=(const RWClassicWString&,  const wchar_t*  );
bool
operator>=(const wchar_t*,           const RWClassicWString&);
bool
operator>=(const RWClassicWString&,  const RWClassicWString&);

Comparisons are done lexicographically, byte by byte. Case sensitivity is exact. Use member collate() or strxfrm() for locale sensitivity.

RWClassicWString
operator+(const RWClassicWString&,   const RWClassicWString&);
RWClassicWString
operator+(const wchar_t*,            const RWClassicWString&);
RWClassicWString
operator+(const RWClassicWString&,   const wchar_t*

Concatenation operators.

ostream&
operator<<(ostream& s, const RWClassicWString& str); 

Output an RWClassicWString on ostream s. Each character of str is first converted to a multibyte character before being shifted out to s.

istream&
operator>>(istream& s, RWClassicWString& str); 

Calls str.readToken(s). That is, a token is read from the input stream s.

RWvostream&
operator<<(RWvostream&, const RWClassicWString& str);
RWFile&
operator<<(RWFile&,     const RWClassicWString& str);

Saves string str to a virtual stream or RWFile, respectively.

RWvistream&
operator>>(RWvistream&, RWClassicWString& str);
RWFile&
operator>>(RWFile&,     RWClassicWString& str);

Restores a wide character string into str from a virtual stream or RWFile, respectively, replacing the previous contents of str.

RWClassicWString
strXForm(const RWClassicWString&);

Returns a string transformed by ::wsxfrm(), to allow quicker collation than RWClassicWString::collate().

RWClassicWString
toLower(const RWClassicWString& str); 

Returns a version of str where all upper-case characters have been replaced with lower-case characters. Uses the C library function towlower().

RWClassicWString
toUpper(const RWClassicWString& str); 

Returns a version of str where all lower-case characters have been replaced with upper-case characters. Uses the C library function towupper().

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.