RWBasicUString

Module:  Essential Tools Module   Group:  Internationalization Classes

Does not inherit

• Local Index
• Synopsis
• Description
• Persistence
• Global Typedefs
• Enumerators
• Constructors
• Destructors
• Static Public Member Functions
• Public Member Functions
• Related Global Operators
• Class Deallocator
• Class StaticDeallocator
• Class Pad

Members

append() begin() boundsCheckIndex() boundsCheckLength() capacity() codePointLength() codePoint_ codeUnitLength() compareCodePoints() compareCodeUnits() compareTo() computeCodePointValue() contains() data() data_ deallocate() Deallocator()

doDeallocate() Duration empty() end() equals() first() getNullDeallocator() hash() highSurrogate() index() insert() isHighSurrogate() isLowSurrogate() isNull() isUnicodeCharacter() last() length()

length_ lowSurrogate() max_size() operator()() operator+=() operator=() operator[]() Pad() prepend() remove() replace() requiresSurrogatePair() resize() restoreFrom() rindex() RWBasicUString() RWUChar16*()

saveOn() size() skipLeading() skipTrailing() StaticDeallocator() swap() toUtf32() toUtf8() toWide() USE_DELETE() USE_FREE() USE_NONE() validateCodePoint() ~Deallocator() ~StaticDeallocator()

Non-Members

const_iterator const_reference difference_type iterator

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

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

pointer reference size_type value_type

#include <rw/tools/bustring.h>
RWBasicUString b;

RWBasicUString is used to manage an array of RWUChar16 values. An instance of RWBasicUString may be constructed to use one of three memory management models:

• The initial contents are owned and managed by the client; the instance assumes no responsibility for deallocating the array. This model is primarily used to treat a static or other long storage-duration array as RWBasicUString instance. The client array may be treated as read-only storage, or as a writable buffer.

• The array is allocated by the client, but the RWBasicUString instance is given the responsibility for deallocating the array.

• The source array is copied by the RWBasicUString instance. The client retains ownership of the source array. The instance owns and manages its own internal copy.

When deallocation responsibility is passed from the client to an RWBasicUString, the client must supply a function object, or functor, that can be used to deallocate the storage. This mechanism allows the client to choose to use delete[], free(), or custom memory-management mechanisms. The use of an externally supplied deallocation method can also be used to satisfy the heap management requirements of Microsoft Windows dynamically linked libraries, which in some situations may create their own heap in addition to that of the calling process.

Given sufficient capacity, RWBasicUString adds a null terminator to any non-static array passed to it. An added null is not considered part of the contents, and is not included in the count returned by length().

None

typedef size_t size_type;

Declares a conventional Standard C++ alias for the type used to represent non-negative values of the distance or difference type. Used for sizes and indices.

typedef ptrdiff_t difference_type;

Declares a conventional Standard C++ alias for the type used to represent the distance between two RWBasicUString iterators.

typedef RWUChar16 value_type;

Declares a conventional Standard C++ alias for the type of values stored within an RWBasicUString instance.

typedef RWUChar16* pointer;

Declares a conventional Standard C++ alias for a pointer to the RWBasicUString value type.

typedef RWUChar16& reference;

Declares a conventional Standard C++ alias for a reference to the RWBasicUString value type.

typedef const RWUChar16& const_reference;

Declares a conventional Standard C++ alias for a constant reference to the RWBasicUString value type.

typedef const RWUChar16* iterator;

Declares a conventional Standard C++ alias for an iterator type that may be used to iterate over the contents of an RWBasicUString.

The pointer type is const because pointers may not be used to modify the contents of an RWBasicUString.

typedef const RWUChar16* const_iterator;

Declares a conventional Standard C++ alias for an iterator type that may be used to iterate over the contents of an RWBasicUString.

enum Duration { Transient, Persistent}

An enumeration whose values are used to indicate whether the source array provided by a client should be copied or simply referenced.

RWBasicUString();

Constructs an empty or null instance.

RWBasicUString(const RWBasicUString& source);

Constructs an RWBasicUString instance from source.

The new instance either copies the data stored in source, or refers to the same storage as source, depending on the storage strategy used to construct source.

RWBasicUString(const RWUChar16* source, Duration duration = Transient);

Constructs an RWBasicUString instance that copies or references the contents of source, a null-terminated sequence of RWUChar16 values. The new RWBasicUString instance assumes no responsibility for deallocating the storage associated with source.

If duration is Transient, this method copies the contents of source into an internally allocated and managed array.

If duration is Persistent, the client retains responsibility for the storage used for source. This mode may be used when source resides in static or otherwise durable storage. The storage associated with source must not be deallocated while the RWBasicUString instance still references it.

The original source array cannot be modified by any of the non-const methods provided by this class. Any attempt to do so will force RWBasicUString to create a copy of source.

RWBasicUString(const RWUChar16* source, size_t sourceLength, Duration duration = Transient);

Constructs an RWBasicUString instance that copies or references the contents of source, an array of RWUChar16 values that contains length elements and may contain embedded nulls. The new RWBasicUString instance assumes no responsibility for deallocating the storage associated with source.

If duration is Transient, this method copies the contents of source into an internally allocated and managed array.

If duration is Persistent, the client retains responsibility for the storage used for source. This mode may be used when source resides in static or otherwise durable storage. Care must be taken to prohibit deallocation of this storage while the RWBasicUString instance still exists.

The original source array cannot be modified by any of the non-const methods provided by this class. Any attempt to do so will force RWBasicUString to create a copy of source.

RWBasicUString(const RWUChar16* source, size_t sourceLength, size_t initialCapacity);

Constructs an RWBasicUString instance that copies the array source into an internally managed buffer with a minimum capacity of initialCapacity.

If the original allocation does not possess the capacity required by an append, insert, or replace operation, a new buffer allocation is made to accommodate the change in length.

RWBasicUString(RWUChar16* clientBuffer, Deallocator* deallocator);

Constructs an RWBasicUString instance that assumes ownership of clientBuffer, a dynamically-allocated, null-terminated sequence of RWUChar16 values. The terminating null may appear at any position within the storage allocated for the unicode string.

The deallocator parameter is used to supply the Counter instance with a Deallocator object that can be used to deallocate the storage referenced by clientBuffer.

Copy-construction or assignment produces an RWBasicUString that refers to the same client-supplied buffer. RWBasicUString does not synchronize access to the client-supplied buffer. External synchronization is required if multiple threads will have access to the buffer through one or more RWBasicUString instances.

RWBasicUString(RWUChar16* clientBuffer, size_t contentLength, Deallocator* deallocator);

Constructs an RWBasicUString instance that assumes ownership of clientBuffer, a dynamically-allocated array of RWUChar16 values that contains contentLength elements and may contain embedded nulls.

The storage required to hold contentLength elements may be less than the storage that was allocated for clientBuffer.

The deallocator parameter is used to supply the Counter instance with a Deallocator object that can be used to deallocate the storage referenced by clientBuffer.

Copy-construction or assignment produces an RWBasicUString that refers to the same client-supplied buffer.

RWBasicUString does not synchronize access to the client-supplied buffer. External synchronization is required if multiple threads will have access to the buffer through one or more RWBasicUString instances.

RWBasicUString(RWUChar16* clientBuffer, size_t contentLength, size_t bufferCapacity, Deallocator* deallocator);

Constructs an RWBasicUString instance that manipulates clientBuffer, a writable, client-supplied array that initially contains contentLength elements and whose total usable size is given by bufferCapacity.

The deallocator parameter is used to supply the Counter instance with a Deallocator object that can be used to deallocate the storage referenced by clientBuffer.

The storage associated with clientBuffer must not be deallocated while the RWBasicUString instance still references it.

If the original clientBuffer array does not possess the capacity required by an append, insert, or replace operation, the buffer is copied into an internally allocated buffer.

Copy-construction or assignment produces an RWBasicUString that refers to the same client-supplied buffer.

RWBasicUString does not synchronize access to the client-supplied buffer. External synchronization is required if multiple threads will have access to the buffer through one or more RWBasicUString instances.

RWBasicUString(const RWUChar32* source);

Constructs an RWBasicUString from the code units produced by converting the UCS-4 or UTF-32 encoded source into its equivalent UTF-16 representation.

RWBasicUString(const RWUChar32* source, size_t sourceLength);

Constructs an RWBasicUString from the code units produced by converting the UCS-4 or UTF-32 encoded source into its equivalent UTF-16 representation.

The number of elements in source is specified using sourceLength.

The source array may contain embedded nulls.

RWBasicUString(const RWSize_T& initialCapacity);

Constructs RWBasicUString containing a zero-length string and a capacity of initialCapacity.

An RWSize_T instance must be constructed to eliminate potential ambiguity with the RWBasicUString(RWUChar32,size_t=1) constructor.

RWBasicUString array(RWSize_T(10));

RWBasicUString(RWUChar16 codeUnit, size_t repeat = 1);

Constructs an RWBasicUString that contains repeat copies of the codeUnit.

RWBasicUString(RWUChar32 codePoint, size_t repeat = 1);

Constructs an RWBasicUString that contains repeat copies of the code unit or surrogate pair of code units produced by converting the UTF-32 codePoint into its equivalent UTF-16 representation.

RWBasicUString(const char* utf8Source);

Constructs an RWBasicUString instance that contains the code units produced by converting the UTF-8 encoded Unicode text in utf8Source into a UTF-16 representation.

The source string must be null-terminated.

RWBasicUString(const char* utf8Source, size_t length);

Constructs an RWBasicUString instance that contains the code units produced by converting the UTF-8 encoded Unicode text in utf8Source into a UTF-16 representation.

The source string length is given by length and may contain embedded nulls.

RWBasicUString(const RWCString& utf8Source);

Constructs an RWBasicUString instance that contains the code units produced by converting the UTF-8 encoded Unicode text in utf8Source into a UTF-16 representation.

~RWBasicUString();

Destroys self. Relinquishes ownership and frees any resources used by self.

static size_t
codePointLength(const RWUChar16* array);

Returns the number of Unicode code points encoded by the code units in the null-terminated sequence array. The terminating null is not included in the count.

static size_t
codePointLength(const RWUChar16* array, size_t length);

Returns the number of Unicode code points encoded by the code units in the sequence array. The size of array is specified using length.

static size_t
codePointLength(const RWUChar32* array);

Returns the size of the null-terminated sequence array. The terminating null is not included in the count.

static size_t
codeUnitLength(const RWUChar16* array);

Returns the size of the null-terminated sequence array. The terminating null is not included in the count.

static size_t
codeUnitLength(const RWUChar32* array);

Returns the number of UTF-16 code units required to encode the null-terminated UTF-32 code point sequence contained in array. The terminating null is not included in the count.

static size_t
codeUnitLength(const RWUChar32* array, size_t length);

Returns the number of UTF-16 code units required to encode the UTF-32 code point sequence contained in array. The size of array is specified using length.

static RWUChar32
computeCodePointValue(RWUChar16 highSurrogate, RWUChar16 lowSurrogate);

Returns the code point value encoded by the specified pair of code units. The code units must describe a valid surrogate pair. Any other values produce an undefined and erroneous result.

static Deallocator* 
getNullDeallocator();

Use this method to retrieve a deallocator for use in constructing an RWBasicUString instance that has been given access to a client-owned and managed buffer.

RWBasicUString buffer[32]; // Client owned array
RWBasicUString array(buffer,0,getNullDeallocator());

The Deallocator object is owned by this class and must not be deleted.

static RWUChar16
highSurrogate(RWUChar32 codePoint);

Returns the high, UTF-16 surrogate (0xD800..0xDBFF) for a code point in the range 0x10000..0x10FFFF.

static bool
isHighSurrogate(RWUChar16 codeUnit);

Returns true if codeUnit encodes the high surrogate of a surrogate pair; otherwise, false.

static bool
isLowSurrogate(RWUChar16 codeUnit);

Returns true if codeUnit encodes the low surrogate of a surrogate pair, otherwise, false.

static bool
isUnicodeCharacter(RWUChar32 codePoint);

Returns true if codePoint is a valid Unicode character; otherwise, false.

Non-characters include:

• single surrogate code points (U+d800..U+dfff, 2048 code points)

• the last two code points on each plane (U+__fffe and U+__ffff, 34 code points)

• U+fdd0..U+fdef (new with Unicode 3.1, 32 code points)

• the highest Unicode code point value is U+10ffff

static RWUChar16
lowSurrogate(RWUChar32 codePoint);

Returns the low UTF-16 surrogate (0xDC00..0xDFFF) for a code point in the range 0x10000..0x10FFFF.

static bool
requiresSurrogatePair(RWUChar32 codeUnit);

Returns true if the UTF-16 representation of codeUnit requires the use of a surrogate pair; otherwise, false.

static void 
USE_DELETE(RWUChar16* p);

Uses the C++ delete[] expression to deallocate an array that was allocated using new.

The method must be defined as an inline method to insure that the code generated to implement the delete resides in the client library or executable, and not within the Essential Tools library.

The code must be compiled this way to avoid the problems that arise when an application contains some libraries that use debug versions of heap management routines while others do not.

static void 
USE_FREE(RWUChar16* p);

Calls the C free() method to deallocate an array that was allocated by a call to malloc().

The method must be defined as an inline method to insure that the version of free() called by this method is the same version that is used within the client code, and that it manipulates the same heap as that of malloc().

The code must be compiled this way to avoid the problems that arise when an application contains some libraries that use debug versions of heap management routines while others do not.

static void 
USE_NONE(RWUChar16* p);

This method may be used to construct a StaticDeallocator instance that does nothing.

Use this method when constructing an RWBasicUString instance that has been given access to a client-owned and managed buffer.

static RWUChar32
validateCodePoint(RWUChar32 codePoint);

Throws RWUConversionErr if codePoint is not a valid Unicode character, or returns codePoint if it is valid. Non-characters include:

• single surrogate code points (U+d800..U+dfff, 2048 code points)

• the last two code points on each plane (U+__fffe and U+__ffff, 34 code points)

• U+fdd0..U+fdef (new with Unicode 3.1, 32 code points)

• values greater than the last Unicode code point value U+10ffff

This method may be used anywhere an individual code point value is passed to a method:

RWUChar32 indentationCharacter = ...
RWBasicUString indent(validateCodePoint(indentationCharacter),8);

RWBasicUString&
append(const RWBasicUString& source);

Appends the contents of source to the contents of self.

RWBasicUString&
append(const RWBasicUString& source, size_t sourceOffset, size_t sourceLength);

Appends the contents of the specified range in source to the contents of self.

Throws RWBoundsErr if the sum of sourceOffset and sourceLength is greater than source.length().

RWBasicUString&
append(const RWUChar16* source);

Appends the contents of the null-terminated array source to the contents of self.

RWBasicUString&
append(const RWUChar16* source, size_t sourceLength);

Appends the contents of the array source to the contents of self. The size of the source array is specified using sourceLength. The source array may contain embedded nulls.

RWBasicUString&
append(const RWUChar32* source);

Converts the code points in the null-terminated array source into UTF-16 code units and appends those code units to contents of self.

RWBasicUString&
append(const RWUChar32* source, size_t sourceLength);

Converts the code points in the array source into UTF-16 code units and appends those code units to contents of self. The size of the source array is specified using sourceLength.

RWBasicUString&
append(RWUChar16 codeUnit, size_t repeat = 1);

Appends repeat copies of codeUnit to the contents of self. The code unit may be zero or null.

RWBasicUString&
append(RWUChar32 codePoint, size_t repeat = 1);

Converts the UTF-32 codePoint into its equivalent UTF-16 representation and appends repeat copies of the resultant code unit or surrogate pair of code units to the contents of self. The code point may be zero or null.

const_iterator
begin() const;

Returns an iterator that may be used to iterate over and examine the contents of self. This method produces the same result as data() and is provided to satisfy the requirements for a Standard C++ container. See also end().

size_t
boundsCheckIndex(size_t offset) const;

Throws RWBoundsErr with a message of RWTOOL_INDEXERR if offset is greater than or equal to length(), or simply returns offset if the value is in bounds.

size_t
boundsCheckLength(size_t offset, size_t length) const;

Throws RWBoundsErr with a message of RWTOOL_INDEXERR if offset plus length is greater than or equal to length() or simply returns length if the value is in bounds.

size_t
capacity() const;

Returns the maximum number of UTF-16 code units that may be stored in self without allocating new storage.

size_t
capacity(size_t newCapacity);

Allocates and copies the existing buffer contents as required to provide the capacity specified by newCapacity. The new capacity must be greater than or equal to the current value of length(); otherwise no reallocation or copy occurs. Returns the resultant capacity of self, which in some cases may be larger than the capacity requested.

size_t
codePointLength() const;

Returns the number of Unicode code points encoded by the code units contained in self, including embedded nulls. This method recalculates the result each time it is called. Use codeUnitLength() to determine the number of UTF-16 code units contained in self.

size_t
codeUnitLength() const;

Returns the number of code units contained in self including embedded nulls. This method uses a cached value and may be called repeatedly without incurring a significant performance penalty. This method returns the same value as length(). Use codePointLength() to determine the number of Unicode code points contained in self.

int
compareCodePoints(const RWBasicUString& rhs) const;

Returns a value that describes the lexical ordering between self and rhs. The return value should be interpreted as follows:

• Self appears before rhs if the return value is less than zero.

• Self is identical to rhs if the return value is zero.

• Self appears after rhs if the return value is greater than zero.

If the two strings have different lengths, the shorter array appears before the longer array if both arrays are identical over the length of the shorter array.

int
compareCodePoints(const RWBasicUString& rhs, size_t rhsOffset, size_t rhsLength) const;

Returns a value that describes the lexical ordering between self and the specified range in rhs. The return value should be interpreted as follows:

• Self appears before rhs range if the return value is less than zero.

• Self is identical to rhs range if the return value is zero.

• Self appears after rhs range if the return value is greater than zero.

If the two strings have different lengths, the shorter string appears before the longer string if both arrays are identical over the length of the shorter string.

Throws RWBoundsErr if the sum of rhsOffset and rhsLength is greater than rhs.length().

int
compareCodePoints(const RWUChar16* rhs) const;

Returns a value that describes the lexical ordering between self and the null-terminated array rhs. The return value should be interpreted as follows:

• Self appears before rhs if the return value is less than zero.

• Self is identical to rhs if the return value is zero.

• Self appears after rhs if the return value is greater than zero.

If the two strings have different lengths, the shorter string appears before the longer string if both strings are identical over the length of the shorter string.

int
compareCodePoints(const RWUChar16* rhs, size_t rhsLength) const;

Returns a value that describes the lexical ordering between self and the array rhs whose length is given by rhsLength. The return value should be interpreted as follows:

• Self appears before rhs if the return value is less than zero.

• Self is identical to rhs if the return value is zero.

• Self appears after rhs if the return value is greater than zero.

If the two strings have different lengths, the shorter string appears before the longer string if both strings are identical over the length of the shorter string.

int
compareCodePoints(const RWUChar32* rhs) const;

Returns a value that describes the lexical ordering between self and the null-terminated array rhs. The return value should be interpreted as follows:

• Self appears before rhs if the return value is less than zero.

• Self is identical to rhs if the return value is zero.

• Self appears after rhs if the return value is greater than zero.

If the two strings have different code unit lengths, the shorter string appears before the longer string if both strings are identical over the length of the shorter string.

int
compareCodePoints(const RWUChar32* rhs, size_t rhsLength) const;

Returns a value that describes the lexical ordering between self and the array rhs whose length is given by rhsLength. The return value should be interpreted as follows:

• Self appears before rhs if the return value is less than zero.

• Self is identical to rhs if the return value is zero.

• Self appears after rhs if the return value is greater than zero.

If the two string have different code unit lengths, the shorter string appears before the longer string if both strings are identical over the length of the shorter string.

int
compareCodeUnits(const RWBasicUString& rhs) const;

Returns a value that describes the lexical ordering between self and rhs. The return value should be interpreted as follows:

• Self appears before rhs if the return value is less than zero.

• Self is identical to rhs if the return value is zero.

• Self appears after rhs if the return value is greater than zero.

If the two strings have different lengths, the shorter string appears before the longer string if both strings are identical over the length of the shorter string.

This method compares code unit values, not code point values. This may not produce the desired result if either string contains surrogate pairs or code unit values above the surrogate region. Use compareCodePoints() if code point ordering is required.

int
compareCodeUnits(const RWBasicUString& rhs, size_t rhsOffset, size_t rhsLength) const;

Returns a value that describes the lexical ordering between self and the specified range in rhs. The return value should be interpreted as follows:

• Self appears before rhs range if the return value is less than zero.

• Self is identical to rhs range if the return value is zero.

• Self appears after rhs range if the return value is greater than zero.

If the two strings have different lengths, the shorter string appears before the longer string if both strings are identical over the length of the shorter string.

This method compares code unit values, not code point values. This may not produce the desired result if either string contains surrogate pairs or code unit values above the surrogate region. Use compareCodePoints() if code point ordering is required.

Throws RWBoundsErr if the sum of rhsOffset and rhsLength is greater than rhs.length().

int
compareCodeUnits(const RWUChar16* rhs) const;

Returns a value that describes the lexical ordering between self and the null-terminated array rhs. The return value should be interpreted as follows:

• Self appears before rhs if the return value is less than zero.

• Self is identical to rhs if the return value is zero.

• Self appears after rhs if the return value is greater than zero.

If the two strings have different lengths, the shorter string appears before the longer string if both strings are identical over the length of the shorter string.

This method compares code unit values, not code point values. This may not produce the desired result if either string contains surrogate pairs or code unit values above the surrogate region. Use compareCodePoints() if code point ordering is required.

int
compareCodeUnits(const RWUChar16* rhs, size_t rhsLength) const;

Returns a value that describes the lexical ordering between self and the array rhs whose length is given by rhsLength. The return value should be interpreted as follows:

• Self appears before rhs if the return value is less than zero.

• Self is identical to rhs if the return value is zero.

• Self appears after rhs if the return value is greater than zero.

If the two strings have different lengths, the shorter string appears before the longer string if both strings are identical over the length of the shorter string.

This method compares code unit values, not code point values. This may not produce the desired result if either string contains surrogate pairs or code unit values above the surrogate region. Use compareCodePoints() if code point ordering is required.

int
compareTo(const RWBasicUString& rhs) const;

Returns a value that describes the lexical ordering between self and rhs. Equivalent to compareCodeUnits(const RWBasicUString&).

int
compareTo(const RWBasicUString& rhs, size_t rhsOffset, size_t rhsLength) const;

Returns a value that describes the lexical ordering between self and the specified range in rhs. Equivalent to compareCodeUnits(const RWBasicUString&).

int
compareTo(const RWUChar16* rhs) const;

Returns a value that describes the lexical ordering between self and the null-terminated array rhs. Equivalent to compareCodeUnits(const RUChar16*).

int
compareTo(const RWUChar16* rhs, size_t rhsLength) const;

Returns a value that describes the lexical ordering between self and the array rhs whose length is give by rhsLength. Equivalent to compareCodeUnits(const RUChar16*,size_t).

int
compareTo(const RWUChar32* rhs) const;

Returns a value that describes the lexical ordering between self and the null-terminated array rhs. Equivalent to compareCodePoints(const RUChar32*).

int
compareTo(const RWUChar32* rhs, size_t rhsLength) const;

Returns a value that describes the lexical ordering between self and the array rhs whose length is give by rhsLength. Equivalent to compareCodePoints(const RUChar32*,size_t).

bool
contains(const RWBasicUString& pattern) const;

Returns true if self contains pattern; otherwise, false. A zero-length pattern returns true.

bool
contains(const RWBasicUString& pattern, size_t patternOffset, size_t patternLength) const;

Returns true if self contains the specified range in pattern; otherwise, false. The pattern range starts at index patternOffset, and extends for patternLength code units. A zero-length pattern returns true.

Throws RWBoundsErr if the sum of patternOffset and patternLength is greater than pattern.length().

bool
contains(const RWUChar16* pattern) const;

Returns true if self contains pattern; otherwise, false. The pattern array must be null-terminated. A zero-length pattern returns true.

bool
contains(const RWUChar16* pattern, size_t patternLength) const;

Returns true if self contains pattern; otherwise, false. The size of the pattern array is specified using patternLength. A zero-length pattern returns true.

bool
contains(const RWUChar32* pattern) const;

Returns true if self contains pattern; otherwise, false. The pattern array must be null-terminated. A zero-length pattern returns true.

bool
contains(const RWUChar32* pattern, size_t patternLength) const;

Returns true if self contains pattern; otherwise, false. The size of the pattern array is specified using patternLength. A zero-length pattern returns true.

bool
contains(RWUChar16 codeUnit) const;

Returns true if self contains codeUnit; otherwise, false.

bool
contains(RWUChar32 codePoint) const;

Returns true if self contains codePoint; otherwise, false.

bool
contains(size_t offset, const RWBasicUString& pattern) const;

Returns true if the specified range in self contains pattern; otherwise, false. The search begins at index offset within self. A zero-length pattern returns true.

Throws RWBoundsErr if offset is greater than or equal to length().

bool
contains(size_t offset, const RWBasicUString& pattern, size_t patternOffset, size_t patternLength) const;

Returns true if the specified range in self contains the specified range in pattern; otherwise, false. The search begins at index offset within self. The pattern range starts at index patternOffset, and extends for patternLength code units. A zero-length pattern returns true.

Throws RWBoundsErr if offset is greater than or equal to length(), or the sum of patternOffset and patternLength is greater than pattern.length().

bool
contains(size_t offset, const RWUChar16* pattern) const;

Returns true if the specified range in self contains pattern; otherwise, false. The search begins at index offset within self. The pattern array must be null-terminated. A zero-length pattern returns true.

Throws RWBoundsErr if offset is greater than or equal to length().

bool
contains(size_t offset, const RWUChar16* pattern, size_t patternLength) const;

Returns true if the specified range in self contains pattern; otherwise, false. The search begins at index offset within self. The size of the pattern array is specified using patternLength. A zero-length pattern returns true.

Throws RWBoundsErr if offset is greater than or equal to length().

bool
contains(size_t offset, const RWUChar32* pattern) const;

Returns true if the specified range in self contains pattern; otherwise, false. The search begins at index offset within self. The pattern array must be null-terminated. A zero-length pattern returns true.

Throws RWBoundsErr if offset is greater than or equal to length().

bool
contains(size_t offset, const RWUChar32* pattern, size_t patternLength) const;

Returns true if the specified range in self contains pattern; otherwise, false. The search begins at index offset within self. The size of the pattern array is specified using patternLength. A zero-length pattern returns true.

Throws RWBoundsErr if offset is greater than or equal to length().

bool
contains(size_t offset, RWUChar16 codeUnit) const;

Returns true if the specified range in self contains codeUnit; otherwise false. The search begins at index offset within self.

Throws RWBoundsErr if offset is greater than or equal to length().

bool
contains(size_t offset, RWUChar32 codePoint) const;

Returns true if the specified range in self contains codePoint; otherwise, false. The search begins at index offset within self.

Throws RWBoundsErr if offset is greater than or equal to length().

bool
contains(size_t offset, size_t length, const RWBasicUString& pattern) const;

Returns true if the specified range in self contains pattern; otherwise, false. The search range starts at index offset within self, and extends for length code units. A zero-length pattern returns true.

Throws RWBoundsErr if the sum of offset and length is greater than length().

bool
contains(size_t offset, size_t length, const RWBasicUString& pattern, size_t patternOffset, size_t patternLength) const;

Returns true if the specified range in self contains the specified range in pattern; otherwise, false. The search range starts at index offset within self, and extends for length code units. The pattern range starts at index patternOffset, and extends for patternLength code units. A zero-length pattern returns true.

Throws RWBoundsErr if the sum of offset and length is greater than length(), or the sum of patternOffset and patternLength is greater than pattern.length().

bool
contains(size_t offset, size_t length, const RWUChar16* pattern) const;

Returns true if the specified range in self contains pattern; otherwise, false. The search range starts at index offset within self, and extends for length code units. The pattern array must be null-terminated. A zero-length pattern returns true.

Throws RWBoundsErr if the sum of offset and length is greater than length().

bool
contains(size_t offset, size_t length, const RWUChar16* pattern, size_t patternLength) const;

Returns true if the specified range in self contains pattern; otherwise, false. The search range starts at index offset within self, and extends for length code units. The size of the pattern array is specified using patternLength. A zero-length pattern returns true.

Throws RWBoundsErr the sum of offset and length is greater than length().

bool
contains(size_t offset, size_t length, const RWUChar32* pattern) const;

Returns true if the specified range in self contains pattern; otherwise, false. The search range starts at index offset within self, and extends for length code units. The pattern array must be null-terminated. A zero-length pattern returns true.

Throws RWBoundsErr if the sum of offset and length is greater than length().

bool
contains(size_t offset, size_t length, const RWUChar32* pattern, size_t patternLength) const;

Returns true if the specified range in self contains pattern; otherwise, false. The search range starts at index offset within self, and extends for length code units. The size of the pattern array is specified using patternLength. A zero-length pattern returns true.

Throws RWBoundsErr if the sum of offset and length is greater than length().

bool
contains(size_t offset, size_t length, RWUChar16 codeUnit) const;

Returns true if the specified range in self contains codeUnit; otherwise, false. The search range starts at index offset within self, and extends for length code units. within self.

Throws RWBoundsErr if the sum of offset and length is greater than length().

bool
contains(size_t offset, size_t length, RWUChar32 codePoint) const;

Returns true if the specified range in self contains codePoint; otherwise, false. The search range starts at index offset within self, and extends for length code units.

Throws RWBoundsErr if the sum of offset and length is greater than length().

const RWUChar16*
data() const;

Returns a pointer to the contents of self. The storage referenced by this pointer is owned by RWBasicUString and may not be deleted or modified. The pointer becomes invalid if self is modified or destroyed. The contents may not be null-terminated if the client provided the underlying buffer and there was insufficient space for a terminating null. In all other cases, the contents will be null terminated. The contents may contain embedded nulls, in which case the length of the code-unit sequence is determined using length().

bool
empty() const;

Returns true if self has a length of zero; otherwise, false. This method requires constant time, while length() == 0 may require linear time to execute. Equivalent to isNull().

const_iterator
end() const;

Returns an iterator that points past the end of the contents of self. Use the iterator returned from this method to test whether another iterator is positioned past the end of the contents. This method produces the same result as data()+length() and is provided to satisfy the requirements for a Standard C++ container. See also begin().

size_t
first(const RWBasicUString& codeUnitSet) const;

Returns the index of the first occurrence of any code unit in codeUnitSet, or RW_NPOS if none of the code units in the set are found.

size_t
first(const RWUChar16* codeUnitSet) const;

Returns the index of the first occurrence of any code unit in codeUnitSet, or RW_NPOS if none of the code units in the set are found. The codeUnitSet array must be null-terminated.

size_t
first(const RWUChar16* codeUnitSet, size_t numCodeUnits) const;

Returns the index of the first occurrence of any code unit in codeUnitSet, or RW_NPOS if none of the code units in the set are found. The size of the codeUnitSet array is specified using numCodeUnits.

size_t
first(const RWUChar32* codePointSet) const;

Returns the index of the first occurrence of any code point in codePointSet, or RW_NPOS if none of the code points in the set are found. The codePointSet array must be null-terminated.

size_t
first(const RWUChar32* codePointSet, size_t numCodePoints) const;

Returns the index of the first occurrence of any code point in codePointSet, or RW_NPOS if none of the code points in the set are found. The size of the codePointSet is specified using numCodePoints.

size_t
first(RWUChar16 codeUnit) const;

Returns the index of the first occurrence of codeUnit, or RW_NPOS if that code unit is not found. This method produces the same result as index(RWUChar16).

size_t
first(RWUChar32 codePoint) const;

Returns the index of the first occurrence of codePoint, or RW_NPOS if the code point is not found.

size_t
first(size_t offset, const RWBasicUString& codeUnitSet) const;

Returns the index of the first occurrence of any code unit in codeUnitSet, or RW_NPOS if none of the code units in the set are found. The search range starts at index offset within self, The value of offset must be less than length().

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
first(size_t offset, const RWUChar16* codeUnitSet) const;

Returns the index of the first occurrence of any code unit in codeUnitSet within the specified range of self, or RW_NPOS is none of the code units in the set are found. The search range starts at index offset within self. The value of offset must be less than length(). The codeUnitSet array must be null-terminated.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
first(size_t offset, const RWUChar16* codeUnitSet, size_t numCodeUnits) const;

Returns the index of the first occurrence of any code unit in codeUnitSet, or RW_NPOS if none of the code units in the set are found. The search range starts at index offset within self, The value of offset must be less than length(). The size of the codeUnitSet array is specified using numCodeUnits.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
first(size_t offset, const RWUChar32* codePointSet) const;

Returns the index of the first occurrence of any code point in codePointSet within the specified range in self, or RW_NPOS if none of the code points in the set are found. The search begins at index position offset within self. The value of offset must be less than length(). The codePointSet array must be null-terminated.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
first(size_t offset, const RWUChar32* codePointSet, size_t numCodePoints) const;

Returns the index of the first occurrence of any code point in codePointSet, or RW_NPOS if none of the code points in the set are found. The search begins at index position offset within self. The value of offset must be less than length(). The size of the codePointSet array is specified using numCodePoints.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
first(size_t offset, RWUChar16 codeUnit) const;

Returns the index of the first occurrence of codeUnit, or RW_NPOS if the code unit is not found. The search range starts at index offset within self. The value of offset must be less than length().

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
first(size_t offset, RWUChar32 codePoint) const;

Returns the index of the first occurrence of codePoint within the specified range in self, or RW_NPOS if the code point is not found. The search begins at index position offset within self. The value of offset must be less than length().

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
first(size_t offset, size_t length, const RWBasicUString& codeUnitSet) const;

Returns the index of the first occurrence of any code unit in codeUnitSet within the specified range of self, or RW_NPOS if none of the code units in the set are found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length().

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
first(size_t offset, size_t length, const RWUChar16* codeUnitSet) const;

Returns the index of the first occurrence of any code unit in codeUnitSet within the specified range of self, or RW_NPOS if none of the code units in the set are found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). The codeUnitSet array must be null-terminated.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
first(size_t offset, size_t length, const RWUChar16* codeUnitSet, size_t numCodeUnits) const;

Returns the index of the first occurrence of any code unit in codeUnitSet within the specified range of self, or RW_NPOS if none of the code units in the set are found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). The size of the codeUnitSet array is specified using numCodeUnits.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
first(size_t offset, size_t length, const RWUChar32* codePointSet) const;

Returns the index of the first occurrence of any codePoint in codePointSet within the specified range of self, or RW_NPOS if the none of the code points in the set are found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). The codePointSet array must be null-terminated.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
first(size_t offset, size_t length, const RWUChar32* codePointSet, size_t numCodePoints) const;

Returns the index of the first occurrence of any codePoint in codePointSet within the specified range of self, or RW_NPOS if the none of the code points in the set are found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). The size of the codePointSet array is specified using numCodePoints.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
first(size_t offset, size_t length, RWUChar16 codeUnit) const;

Returns the index of the first occurrence of codeUnit within the specified range of self, or RW_NPOS if the code unit is not found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length().

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
first(size_t offset, size_t length, RWUChar32 codePoint) const;

Returns the index of the first occurrence of codePoint within the specified range of self, or RW_NPOS if the code point is not found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length().

Throws RWBoundsErr if the sum of offset and length is greater than length().

bool
equals(const RWBasicUString& array) const;

Returns true if the contents and length of self are identical to array; otherwise, false. This method is more efficient than compareCodeUnits() when testing for equality.

unsigned long
hash() const;

Returns a hash value computed from the contents of self.

size_t
index(const RWBasicUString& pattern) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. Returns an index value of zero if the pattern length is zero.

size_t
index(const RWBasicUString& pattern, size_t patternOffset, size_t patternLength) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The pattern range starts at index patternOffset, and extends for patternLength code units. Returns an index value of zero if the pattern length is zero.

Throws RWBoundsErr if the sum of patternOffset and patternLength is greater than pattern.length().

size_t
index(const RWUChar16* pattern) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The pattern must be null-terminated. Returns an index value of zero if the pattern length is zero.

size_t
index(const RWUChar16* pattern, size_t patternLength) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The size of the pattern is specified using patternLength. Returns an index value of zero if the pattern length is zero.

size_t
index(const RWUChar32* pattern) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The pattern must be null-terminated. Returns an index value of zero if the pattern length is zero.

size_t
index(const RWUChar32* pattern, size_t patternLength) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The size of the pattern is specified using patternLength. Returns an index value of zero if the pattern length is zero.

size_t
index(RWUChar16 codeUnit) const;

Returns the index of the first occurrence of codeUnit, or RW_NPOS if the code unit is not found. This function produces the same result as first(RWUChar16).

size_t
index(RWUChar32 codePoint) const;

Returns the index of the first occurrence of codePoint, or RW_NPOS if the code unit is not found. This function produces the same result as first(RWUChar32).

size_t
index(size_t offset, const RWBasicUString& pattern) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index position offset within self. The value of offset must be less than length(). Returns an index value of zero if the pattern length is zero.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
index(size_t offset, const RWBasicUString& pattern, size_t patternOffset, size_t patternLength) const;

Returns the index of the first occurrence of the specified range in pattern, or RW_NPOS if the pattern is not found. The search begins at index position offset within self. The value of offset must be less than length(). The pattern range starts at index patternOffset, and extends for patternLength code units. Returns an index value of zero if the pattern length is zero.

Throws RWBoundsErr if offset is greater than or equal to length() or if the sum of patternOffset and patternLength is greater than pattern.length().

size_t
index(size_t offset, const RWUChar16* pattern) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index position offset within self. The value of offset must be less than length(). The pattern must be null-terminated. Returns an index value of zero if the pattern length is zero.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
index(size_t offset, const RWUChar16* pattern, size_t patternLength) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index position offset within self. The value of offset must be less than length(). The size of the pattern is specified using patternLength. Returns an index value of zero if the pattern length is zero.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
index(size_t offset, const RWUChar32* pattern) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index position offset within self. The value of offset must be less than length(). The pattern must be null-terminated. Returns an index value of zero if the pattern length is zero.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
index(size_t offset, const RWUChar32* pattern, size_t patternLength) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index position offset within self. The value of offset must be less than length(). The size of the pattern is specified using patternLength. Returns an index value of zero if the pattern length is zero.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
index(size_t offset, RWUChar16 codeUnit) const;

Returns the index of the first occurrence of codeUnit, or RW_NPOS if the code unit is not found. The search begins at index position offset within self. The value of offset must be less than length(). This function produces the same result as first(size_t,RWUChar16).

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
index(size_t offset, RWUChar32 codeUnit) const;

Returns the index of the first occurrence of codePoint, or RW_NPOS if the code unit is not found. The search begins at index position offset within self. The value of offset must be less than length(). This function produces the same result as first(size_t,RWUChar32).

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
index(size_t offset, size_t length, const RWBasicUString& pattern) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). Returns an index value of zero if the pattern length is zero.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
index(size_t offset, size_t length, const RWBasicUString& pattern, size_t patternOffset, size_t patternLength) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). The pattern range starts at index patternOffset, and extends for patternLength code units. Returns an index value of zero if the pattern length is zero.

Throws RWBoundsErr if the sum of offset and length is greater than length() or if the sum of patternOffset and patternLength is greater than pattern.length().

size_t
index(size_t offset, size_t length, const RWUChar16* pattern) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). The pattern must be null-terminated. Returns an index value of zero if the pattern length is zero.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
index(size_t offset, size_t length, const RWUChar16* pattern, size_t patternLength) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). The size of the pattern is specified using patternLength. Returns an index value of zero if the pattern length is zero.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
index(size_t offset, size_t length, const RWUChar32* pattern) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). The pattern must be null-terminated. Returns an index value of zero if the pattern length is zero.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
index(size_t offset, size_t length, const RWUChar32* pattern, size_t patternLength) const;

Returns the index of the first occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). The size of the pattern is specified using patternLength. Returns an index value of zero if the pattern length is zero.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
index(size_t offset, size_t length, RWUChar16 codeUnit) const;

Returns the index of the first occurrence of codeUnit, or RW_NPOS if the code unit is not found. The search begins at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). This function produces the same result as first(size_t,RWUChar16).

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
index(size_t offset, size_t length, RWUChar32 codeUnit) const;

Returns the index of the first occurrence of codePoint, or RW_NPOS if the code unit is not found. The search begins at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). This function produces the same result as first(size_t,RWUChar32).

Throws RWBoundsErr if the sum of offset and length is greater than length().

RWBasicUString&
insert(size_t offset, const RWBasicUString& source);

Inserts the contents of source before the code unit at index offset within the contents of self. The value of offset must be less than length().

Throws RWBoundsErr if offset is greater than or equal to length().

RWBasicUString&
insert(size_t offset, const RWBasicUString& source, size_t sourceOffset, size_t sourceLength);

Inserts the contents of the specified range in source before the code unit at index offset within the contents of self. The value of offset must be less than length(). The sum of sourceOffset and sourceLength must be less than or equal source.length().

Throws RWBoundsErr if offset is greater than or equal to length() or if the sum of sourceOffset and sourceLength is greater than source.length().

RWBasicUString&
insert(size_t offset, const RWUChar16* source);

Inserts the contents of the null-terminated array source before the code unit at index offset within the contents of self. The value of offset must be less than length().

Throws RWBoundsErr if offset is greater than or equal to length().

RWBasicUString&
insert(size_t offset, const RWUChar16* source, size_t sourceLength);

Inserts the contents of the array source before the code unit at index offset within the contents of self. The value of offset must be less than length(). The size of the source array is specified using sourceLength. The source array may contain embedded nulls.

Throws RWBoundsErr if offset is greater than or equal to length().

RWBasicUString&
insert(size_t offset, const RWUChar32* source);

Converts the code points in the null-terminated array source into UTF-16 code units and inserts those code units before the code unit at index offset within contents of self. The value of offset must be less than length().

Throws RWBoundsErr if offset is greater than or equal to length().

RWBasicUString&
insert(size_t offset, const RWUChar32* source, size_t sourceLength);

Converts the code points in the array source into UTF-16 code units and inserts those code units before the code unit at index offset within the contents of self. The value of offset must be less than length(). The size of the source array is specified using sourceLength.

Throws RWBoundsErr if offset is greater than or equal to length().

RWBasicUString&
insert(size_t offset, RWUChar16 codeUnit, size_t repeat = 1);

Inserts repeat copies of codeUnit before the code unit at index offset within the contents of self. The value of offset must be less than length(). The code unit is repeated repeat times. The code unit may be zero or null.

Throws RWBoundsErr if offset is greater than or equal to length().

RWBasicUString&
insert(size_t offset, RWUChar32 codePoint, size_t repeat = 1);

Converts the UTF-32 codePoint into its equivalent UTF-16 representation and inserts repeat copies of the resultant code unit or surrogate pair of code units before the code unit at index offset within the contents of self. The value of offset must be less than length(). The code point may be zero or null.

Throws RWBoundsErr if offset is greater than or equal to length().

bool
isNull() const;

Returns true if self has a length of zero; otherwise, false. This method requires constant time while length() == 0 may require linear time to execute. Equivalent to empty().

size_t
last(const RWBasicUString& codeUnitSet) const;

Returns the index of the last occurrence of any code unit in codeUnitSet, or RW_NPOS is none of the code units in the set are found.

size_t
last(const RWUChar16* codeUnitSet) const;

Returns the index of the last occurrence of any code unit in codeUnitSet, or RW_NPOS is none of the code units in the set are found. The codeUnitSet array must be null-terminated.

size_t
last(const RWUChar16* codeUnitSet, size_t numCodeUnits) const;

Returns the index of the last occurrence of any code unit in codeUnitSet, or RW_NPOS if none of the code units in the set are found. The size of the codeUnitSet array is specified using numCodeUnits.

size_t
last(const RWUChar32* codePointSet) const;

Returns the index of the last occurrence of any code point in codePointSet, or RW_NPOS is none of the code points in the set are found. The codePointSet array must be null-terminated.

size_t
last(const RWUChar32* codePointSet, size_t numCodePoints) const;

Returns the index of the last occurrence of any code point in codePointSet, or RW_NPOS if none of the code points in the set are found. The size of the codePointSet is specified using numCodePoints.

size_t
last(RWUChar16 codeUnit) const;

Returns the index of the last occurrence of codeUnit, or RW_NPOS if that code unit is not found.

size_t
last(RWUChar32 codePoint) const;

Returns the index of the last occurrence of codePoint, or RW_NPOS if that code point is not found.

size_t
last(size_t offset, const RWBasicUString& codeUnitSet) const;

Returns the index of the last occurrence of any code unit in codeUnitSet within the specified range in self, or RW_NPOS is none of the code units in the set are found. The search begins at index position offset within self. The value of offset must be less than length().

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
last(size_t offset, const RWUChar16* codeUnitSet) const;

Returns the index of the last occurrence of any code unit in codeUnitSet within the specified range in self, or RW_NPOS if none of the code units in the set are found. The search begins at index position offset within self. The value of offset must be less than length(). The codeUnitSet array must be null-terminated.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
last(size_t offset, const RWUChar16* codeUnitSet, size_t numCodeUnits) const;

Returns the index of the last occurrence of any code unit in codeUnitSet within the specified range in self, or RW_NPOS if none of the code units in the set are found. The search begins at index position offset within self. The value of offset must be less than length(). The size of the codeUnitSet array is specified using numCodeUnits.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
last(size_t offset, const RWUChar32* codePointSet) const;

Returns the index of the last occurrence of any code point in codePointSet within the specified range of self, or RW_NPOS if none of the code points in the set are found. The search begins at index position offset within self. The value of offset must be less than length(). The codePointSet array must be null-terminated.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
last(size_t offset, const RWUChar32* codePointSet, size_t numCodePoints) const;

Returns the index of the last occurrence of any code point in codePointSet within the specified range in self, or RW_NPOS if none of the code points in the set are found. The search begins at index position offset within self. The value of offset must be less than length(). The size of the codePointSet is specified using numCodePoints.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
last(size_t offset, RWUChar16 codeUnit) const;

Returns the index of the last occurrence of codeUnit, within the specified range in self, or RW_NPOS if that code unit is not found. The search begins at index position offset within self. The value of offset must be less than length().

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
last(size_t offset, RWUChar32 codePoint) const;

Returns the index of the last occurrence of codePoint within the specified range in self, or RW_NPOS if that code point is not found. The search begins at index position offset within self. The value of offset must be less than length().

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
last(size_t offset, size_t length, const RWBasicUString& codeUnitSet) const;

Returns the index of the last occurrence of any code unit in codeUnitSet within the specified range in self, or RW_NPOS if none of the code units in the set are found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length().

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
last(size_t offset, size_t length, const RWUChar16* codeUnitSet) const;

Returns the index of the last occurrence of any code unit in codeUnitSet within the specified range in self, or RW_NPOS if none of the code units in the set are found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). The codeUnitSet array must be null-terminated.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
last(size_t offset, size_t length, const RWUChar16* codeUnitSet, size_t numCodeUnits) const;

Returns the index of the last occurrence of any code unit in codeUnitSet within the specified range in self, or RW_NPOS if none of the code units in the set are found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). The size of the codeUnitSet array is specified using numCodeUnits.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
last(size_t offset, size_t length, const RWUChar32* codePointSet) const;

Returns the index of the last occurrence of any code point in codePointSet within the specified range of self, or RW_NPOS if none of the code points in the set are found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). The codePointSet array must be null-terminated.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
last(size_t offset, size_t length, const RWUChar32* codePointSet, size_t numCodePoints) const;

Returns the index of the last occurrence of any code point in codePointSet within the specified range in self, or RW_NPOS if none of the code points in the set are found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length(). The size of the codePointSet is specified using numCodePoints.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
last(size_t offset, size_t length, RWUChar16 codeUnit) const;

Returns the index of the last occurrence of codeUnit within the specified range in self, or RW_NPOS if that code unit is not found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length().

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
last(size_t offset, size_t length, RWUChar32 codePoint) const;

Returns the index of the last occurrence of codePoint within the specified range in self, or RW_NPOS if that code point is not found. The search range starts at index offset within self, and extends for length code units. The sum of offset and length must be less than or equal to length().

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
length() const;

Returns the number of UTF-16 code units contained in self including embedded nulls. This method returns the same value as codeUnitLength(). Use codePointLength() to determine the number of Unicode code points contained in self.

size_t
max_size() const;

Returns the maximum number of code units that may be stored in an RWBasicUString instance.

RWBasicUString&
operator=(const RWBasicUString& source);

Replaces the contents of self with the contents of source.

RWBasicUString&
operator=(const RWUChar16* source);

Replaces the contents of self with the null-terminated contents of source and returns a reference to self.

RWBasicUString&
operator=(const RWUChar32* source);

Replaces the contents of self with the code unit sequence required to represent the null-terminated, UTF-32 encoded contents of source in the UTF-16 encoding form and returns a reference to self.

RWBasicUString&
operator=(RWUChar16 codeUnit);

Replaces the contents of self with the single code unit codeUnit.

RWBasicUString&
operator=(RWUChar32 codePoint);

Replaces the contents of self with the code unit sequence required to represent codePoint in the UTF-16 encoding form and returns a reference to self.

RWBasicUString&
operator+=(const RWBasicUString& source);

Appends the contents of source to the contents of self.

RWBasicUString&
operator+=(const RWUChar16* source);

Appends the contents of the null-terminated array source to the contents of self.

RWBasicUString&
operator+=(const RWUChar32* source);

Appends the contents of the null-terminated array source to the contents of self.

RWBasicUString&
operator+=(RWUChar16 codeUnit);

Appends codeUnit to the contents of self.

RWBasicUString&
operator+=(RWUChar32 codePoint);

Appends codePoint to the contents of self.

RWUChar16&
operator[](short offset);
RWUChar16&
operator[](int offset);
RWUChar16&
operator[](long offset);
RWUChar16&
operator[](unsigned short offset);
RWUChar16&
operator[](unsigned int offset);
RWUChar16&
operator[](unsigned long offset);
RWUChar16&
operator[](rwlonglong offset);
RWUChar16&
operator[](rwulonglong offset);

Returns a reference to the code unit at the position specified by offset. This non-const variant can be used as an l-value in an assignment expression. The value of offset must be less than length(). Note that an individual code unit may not represent a complete code point.

Throws RWBoundsErr if the sum of offset is greater than or equal to length().

RWUChar16
operator[](short offset) const;
RWUChar16
operator[](int offset) const;
RWUChar16
operator[](long offset) const;
RWUChar16
operator[](unsigned short offset) const;
RWUChar16
operator[](unsigned int offset) const;
RWUChar16
operator[](unsigned long offset) const;
RWUChar16
operator[](rwlonglong offset) const;
RWUChar16
operator[](rwulonglong offset) const;

Returns the code unit value at the position specified by offset. The value of offset must be less than length(). Note that an individual code unit may not represent a complete code point.

Throws RWBoundsErr if the sum of offset is greater than or equal to length().

RWUChar16&
operator()(size_t offset);

Returns a reference to the code unit at the position specified by offset. This non-const variant can be used as an l-value in an assignment expression. The value of offset must less than length(). Note that an individual code unit may not represent a complete code point.

Throws RWBoundsErr if the sum of offset is greater than or equal to length().

RWUChar16
operator()(size_t offset) const;

Returns the code unit value at the position specified by offset. The value of offset must be less than length(). Note that an individual code unit may not represent a complete code point.

Throws RWBoundsErr if the sum of offset is greater than or equal to length().

operator const
RWUChar16*() const;

Returns a pointer to the contents of self. This array is owned by RWBasicUString and may not be deleted or modified. The pointer becomes invalid if self is modified or destroyed.

The array may not be null-terminated if:

• the client provided the underlying buffer used for the array,

• the contents of that buffer were not null-terminated, and

• there was insufficient space for a found terminating null

In all other cases, the array will be null terminated. The array may also contain embedded nulls, in which case, the length of the code-unit sequence can be determined using length().

RWBasicUString&
prepend(const RWBasicUString& source);

Prepends the contents of source to the contents of self.

RWBasicUString&
prepend(const RWBasicUString& source, size_t sourceOffset, size_t sourceLength);

Prepends the contents of the specified range in source to the contents of self. The sum of sourceOffset and sourceLength must be less than or equal to source.length().

Throws RWBoundsErr if the sum of sourceOffset and sourceLength is greater than length().

RWBasicUString&
prepend(const RWUChar16* source);

Prepends the contents of the null-terminated array source to the contents of self.

RWBasicUString&
prepend(const RWUChar16* source, size_t sourceLength);

Prepends the contents of the array source to the contents of self. The size of the source array is specified using sourceLength. The source array may contain embedded nulls.

RWBasicUString&
prepend(const RWUChar32* source);

Converts the code points in the null-terminated array source into UTF-16 code units and prepends those code units to contents of self.

RWBasicUString&
prepend(const RWUChar32* source, size_t sourceLength);

Converts the code points in the array source into UTF-16 code units and prepends those code units to contents of self. The size of the source array is specified using sourceLength.

RWBasicUString&
prepend(RWUChar16 codeUnit, size_t repeat = 1);

Prepends repeat copies of codeUnit to the contents of self. The code unit may be zero or null.

RWBasicUString&
prepend(RWUChar32 codePoint, size_t repeat = 1);

Converts the UTF-32 codePoint into its equivalent UTF-16 representation and prepends repeat copies of the resultant code unit or surrogate pair of code units to the contents of self. The code point may be zero or null.

RWBasicUString&
remove(size_t offset = 0);

Removes the range of code units that start at offset and extend through the end of self. The value of offset must be less than length().

Throws RWBoundsErr if offset is greater than or equal to length().

RWBasicUString&
remove(size_t offset, size_t length);

Removes the specified range of code units from the contents of self, and collapses the contents as necessary to produce a contiguous result. The sum of offset and length must be less than or equal to length().

Throws RWBoundsErr if the sum of offset and length is greater than length().

RWBasicUString&
replace(size_t offset, size_t length, const RWBasicUString& source);

Replaces the specified range of code units in self with the contents of source. The sum of offset and length must be less than or equal to length().

Throws RWBoundsErr if the sum of offset and length is greater than length().

RWBasicUString&
replace(size_t offset, size_t length, const RWBasicUString& source, size_t sourceOffset, size_t sourceLength);

Replaces the specified range of code units in self with the specified range of code units in source. The sum of offset and length must be less than or equal to length(). The sum of sourceOffset and sourceLength must be less than or equal to source.length().

Throws RWBoundsErr if the sum of offset and length is greater than length() or the sum of sourceOffset and sourceLength is greater than source.length().

RWBasicUString&
replace(size_t offset, size_t length, const RWUChar16* source);

Replaces the specified range of code units in self with the contents of the null-terminated array source. The sum of offset and length must be less than or equal to length().

Throws RWBoundsErr if the sum of offset and length is greater than length().

RWBasicUString&
replace(size_t offset, size_t length, const RWUChar16* source, size_t sourceLength);

Replaces the specified range of code units in self with the contents of the array source. The sum of offset and length must be less than or equal to length(). The size of the source array is specified using sourceLength. The source array may contain embedded nulls.

Throws RWBoundsErr if the sum of offset and length is greater than length().

RWBasicUString&
replace(size_t offset, size_t length, const RWUChar32* source);

Converts the code points in the null-terminated array source into UTF-16 code units and replaces the specified range of code units in self with those code units. The sum of offset and length must be less than or equal to length().

Throws RWBoundsErr if the sum of offset and length is greater than length().

RWBasicUString&
replace(size_t offset, size_t length, const RWUChar32* source, size_t sourceLength);

Converts the code points in the array source into UTF-16 code units and replaces the specified range of code units in self with those code units. The sum of offset and length must be less than or equal to length(). The size of the source array is specified using sourceLength. The source array may contain embedded nulls.

Throws RWBoundsErr if the sum of offset and length is greater than length().

RWBasicUString&
replace(size_t offset, size_t length, RWUChar16 codeUnit, size_t repeat = 1);

Replaces the specified range of code units in self with repeat copies of codeUnit. The sum of offset and length must be less than or equal to length(). The code unit may be zero or null.

Throws RWBoundsErr if the sum of offset and length is greater than length().

RWBasicUString&
replace(size_t offset, size_t length, RWUChar32 codePoint, size_t repeat = 1);

Converts the UTF-32 codePoint into its equivalent UTF-16 representation and replaces the specified range of code units in self with repeat copies of the resultant code unit or surrogate pair of code units. The sum of offset and length must be less than or equal to length(). The code point may be zero or null.

Throws RWBoundsErr if the sum of offset and length is greater than length().

void
resize(size_t newCodeUnitLength, RWUChar16 codeUnit);

Pads or truncates the contents of self as required to produce a length() of newCodeUnitLength. If the new length is greater than the old length, codeUnit is used to pad the contents.

void
resize(size_t newCodePointLength, RWUChar32 codePoint);

Pads or truncates the contents of self as required to produce a length() of newCodePointLength. If the new length is greater than the old length, codePoint is used to pad the contents.

void
restoreFrom(RWvistream& vis);

Replaces the contents of self with the code unit sequence read from vis.

void
restoreFrom(RWFile& file);

Replaces the contents of self with the code unit sequence read from file.

size_t
rindex(const RWBasicUString& pattern) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. Returns an index value equal to length() if the pattern length is zero.

size_t
rindex(const RWBasicUString& pattern, size_t patternOffset, size_t patternLength) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The pattern range starts at index patternOffset, and extends for patternLength code units. Returns an index value equal to length() if the pattern length is zero.

Throws RWBoundsErr if the sum of patternOffset and patternLength is greater than pattern.length().

size_t
rindex(const RWUChar16* pattern) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The pattern must be null-terminated. Returns an index value equal to length() if the pattern length is zero.

size_t
rindex(const RWUChar16* pattern, size_t patternLength) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The size of the pattern is specified using patternLength. Returns an index value equal to length() if the pattern length is zero.

size_t
rindex(const RWUChar32* pattern) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The pattern must be null-terminated. Returns an index value equal to length() if the pattern length is zero.

size_t
rindex(const RWUChar32* pattern, size_t patternLength) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The size of the pattern is specified using patternLength. Returns an index value equal to length() if the pattern length is zero.

size_t
rindex(RWUChar16 codeUnit) const;

Returns the index of the last occurrence of codeUnit, or RW_NPOS if the code unit is not found. Equivalent to first(RWUChar16).

size_t
rindex(RWUChar32 codePoint) const;

Returns the index of the last occurrence of codePoint, or RW_NPOS if the code unit was not found. Equivalent to first(RWUChar32).

size_t
rindex(size_t offset, const RWBasicUString& pattern) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self and extends through the end of self. The value of offset length must be less than length(). Returns an index value equal to length() if the pattern length is zero.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
rindex(size_t offset, const RWBasicUString& pattern, size_t patternOffset, size_t patternLength) const;

Returns the index of the last occurrence of the specified range in pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self and extends through the end of self. The value of offset length must be less than length().

The pattern begins at index patternOffset within the supplied pattern and extends for patternLength code units. The sum of patternOffset and patternLength must be less than or equal to pattern.length(). Returns an index value equal to pattern.length() if the pattern length is zero.

Throws RWBoundsErr if offset is greater than or equal to length(), or the sum of patternOffset and patternLength is greater than length().

size_t
rindex(size_t offset, const RWUChar16* pattern) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self and extends through the end of self. The value of offset length must be less than length(). The pattern must be null-terminated. Returns an index value equal to length() if the pattern length is zero.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
rindex(size_t offset, const RWUChar16* pattern, size_t patternLength) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self and extends through the end of self. The value of offset length must be less than length(). The size of the pattern is specified using patternLength. Returns an index value equal to length() if the pattern length is zero.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
rindex(size_t offset, const RWUChar32* pattern) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self and extends through the end of self. The value of offset length must be less than length(). The pattern must be null-terminated. Returns an index value equal to length() if the pattern length is zero.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
rindex(size_t offset, const RWUChar32* pattern, size_t patternLength) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self and extends through the end of self. The value of offset length must be less than length(). The size of the pattern is specified using patternLength. Returns an index value equal to length() if the pattern length is zero.

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
rindex(size_t offset, RWUChar16 codeUnit) const;

Returns the index of the last occurrence of codeUnit, or RW_NPOS if the code unit is not found. The search begins at index offset within self and extends through the end of self. The value of offset length must be less than length(). This function will produce the same result as first(size_t,RWUChar16).

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
rindex(size_t offset, RWUChar32 codeUnit) const;

Returns the index of the last occurrence of codePoint, or RW_NPOS if the code unit is not found. The search begins at index offset within self and extends through the end of self. The value of offset length must be less than length(). This function will produce the same result as first(size_t,RWUChar32).

Throws RWBoundsErr if offset is greater than or equal to length().

size_t
rindex(size_t offset, size_t length, const RWBasicUString& pattern) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self and extends for length code units. The sum of offset and length must be less than or equal to length(). Returns an index value equal to the sum of offset and length if the pattern length is zero.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
rindex(size_t offset, size_t length, const RWBasicUString& pattern, size_t patternOffset, size_t patternLength) const;

Returns the index of the last occurrence of the specified range in pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self and extends for length code units. The sum of offset and length must be less than or equal to length().

The pattern begins at index patternOffset within self and extends for patternLength code units. The sum of patternOffset and patternLength must be less than or equal to length(). Returns an index value equal to the sum of offset and length if the pattern length is zero.

Throws RWBoundsErr if the sum of offset and length is greater than length(), or the sum of patternOffset and patternLength is greater than pattern.length().

size_t
rindex(size_t offset, size_t length, const RWUChar16* pattern) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self and extends for length code units. The sum of offset and length must be less than or equal to length(). The pattern must be null-terminated. Returns an index value equal to the sum of offset and length if the pattern length is zero.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
rindex(size_t offset, size_t length, const RWUChar16* pattern, size_t patternLength) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self and extends for length code units. The sum of offset and length must be less than or equal to length(). The size of the pattern is specified using patternLength. Returns an index value equal to the sum of offset and length if the pattern length is zero.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
rindex(size_t offset, size_t length, const RWUChar32* pattern) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self and extends for length code units. The sum of offset and length must be less than or equal to length(). The pattern must be null-terminated. Returns an index value equal to the sum of offset and length if the pattern length is zero.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
rindex(size_t offset, size_t length, const RWUChar32* pattern, size_t patternLength) const;

Returns the index of the last occurrence of pattern, or RW_NPOS if the pattern is not found. The search begins at index offset within self and extends for length code units. The sum of offset and length must be less than or equal to length(). The size of the pattern is specified using patternLength. Returns an index value equal to the sum of offset and length if the pattern length is zero.

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
rindex(size_t offset, size_t length, RWUChar16 codeUnit) const;

Returns the index of the last occurrence of codeUnit, or RW_NPOS if the code unit is not found. The search begins at index offset within self and extends for length code units. The sum of offset and length must be less than or equal to length(). Equivalent to first(size_t,RWUChar16).

Throws RWBoundsErr if the sum of offset and length is greater than length().

size_t
rindex(size_t offset, size_t length, RWUChar32 codeUnit) const;

Returns the index of the last occurrence of codeUnit, or RW_NPOS if the code unit is not found. The search begins at index offset within self and extends for length code units. The sum of offset and length must be less than or equal to length(). Equivalent to first(size_t,RWUChar32).

Throws RWBoundsErr if the sum of offset and length is greater than length().

void
saveOn(RWvostream& vos) const;

Writes the binary contents of self to vos as an array of 16-bit values.

void
saveOn(RWFile& file) const;

Writes the binary contents of self to file as an array of 16-bit values.

size_t
skipLeading(RWUChar32 codePoint =
                    static_cast<RWUChar32>('0x0020')) const;

Returns the offset of the code unit in self that immediately follows a prefix consisting of a repeated set of code units that correspond to codePoint. If no such prefix exists, a value of 0 is returned. If the contents of self consists entirely of a repeated sequence of codePoint, a value equal to length() is returned The skip code point defaults to U+0020, the ASCII space character.

size_t
skipTrailing(RWUChar32 codePoint = 
                     static_cast<RWUChar32>('0x0020')) const;

Returns the offset of the code unit in self that immediately precedes a suffix consisting of a repeated set of code units that correspond to codePoint. If no such suffix exists, a value length() is returned. If the contents of self consists entirely of a repeated sequence of codePoint, a value of RW_NPOS is returned The skip code point defaults to U+0020, the ASCII space character.

size_t
size() const;

Returns the size of the code unit sequence contained in self. This method produces the same result as length() and is provided to satisfy the Standard C++ requirements for a container.

void
swap(RWBasicUString& ustr);

Swaps the contents of self with that of ustr. This method is provided to satisfy the Standard C++ requirements for a container.

RW_SL_STD(basic_string<RWUChar32>)
toUtf32() const;

Returns a UTF-32 encoded representation of the contents of self.

Throws RWConversionErr if an illegal or truncated surrogate pair is encountered during the conversion.

RWCString
toUtf8(size_t numCodePoints = RW_NPOS) const;

Returns a UTF-8 encoded representation of the contents of self.

RWWString
toWide() const;

Returns an RWWString containing a UTF-16 or UTF-32 representation of the contents of self, depending on the size of wchar_t. If sizeof(wchar_t) is 2, the RWWString is encoded in UTF-16. If sizeof(wchar_t) is 4, the RWWString is encoded in UTF-32.

This method produces Unicode-encoded wide-character strings. This encoding may not match that of the execution environment. The "native" encoding for wchar_t strings may be determined by the current ANSI/POSIX LC_CTYPE locale and the execution environment. Many environments use Unicode (ISO-10646) as the native encoding for wchar_t. For those that do, the choice of encoding is typically made based on the size of wchar_t.

Throws RWConversionErr if an illegal or truncated surrogate pair is encountered during the conversion to UTF-32. Such errors are ignored if the result is encoded as UTF-16.

bool
operator<(const RWUChar16* lhs, const RWBasicUString& rhs)

Returns true if lhs is lexically less than rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the shorter array is considered less than the longer array. The lhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodeUnits() in that case.

bool
operator<(const RWBasicUString& lhs, const RWUChar16* rhs)

Returns true if lhs is lexically less than rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the shorter array is considered less than the longer array. The rhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodeUnits() in that case.

bool
operator<(const RWBasicUString& lhs, const RWBasicUString& rhs)

Returns true if lhs is lexically less than rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the shorter array is considered less than the longer array.

bool
operator<(const RWUChar32* lhs, const RWBasicUString& rhs)

Returns true if lhs is lexically less than rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the shorter array is considered less than the longer array. The lhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodePoints() in that case.

bool
operator<(const RWBasicUString& lhs, const RWUChar32* rhs)

Returns true if lhs is lexically less than rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the shorter array is considered less than the longer array. The rhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodePoints() in that case.

ostream&
operator<<( RW_SL_IO_STD(ostream&) os, const RWBasicUString& ustr);
RWFile&
operator<<(RWFile& file, const RWBasicUString& ustr);
RWbostream&
operator<<(RWbostream& bos, const RWBasicUString& ustr);
RWpostream&
operator<<(RWpostream& pos, const RWBasicUString& ustr);
RWeostream&
operator<<(RWeostream& eos, const RWBasicUString& ustr);
RWXDRostream&
operator<<(RWXDRostream& xos, const RWBasicUString& ustr);

Converts the contents of ustr into a UTF-8 sequence and writes that sequence to ostream. The output sequence may contain embedded nulls.

If os.width() is greater than the number of code points contained in the source string, the ouput is padded using a single space fill character [U+0020]. If os.width() is less than the number of code points contained the source string, the entire contents of the string is inserted into the output stream. Any padding is inserted after the string if the ios_base::left format flag is set, or before if ios_base::right is set or neither flag is set.

Throws RWConversionErr to report conversion errors. Throws std::ios_base::failure to report any errors detected while performing stream operations.

bool
operator<=(const RWUChar16* lhs, const RWBasicUString& rhs)

Returns true if lhs is lexically less than or equal to rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the shorter array is considered less than the longer array. The lhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodeUnits() in that case.

bool
operator<=(const RWBasicUString& lhs, const RWUChar16* rhs)

Returns true if lhs is lexically less than or equal to rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the shorter array is considered less than the longer array. The rhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodeUnits() in that case.

bool
operator<=(const RWBasicUString& lhs, const RWBasicUString& rhs)

Returns true if lhs is lexically less than or equal to rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the shorter array is considered less than the longer array.

bool
operator<=(const RWUChar32* lhs, const RWBasicUString& rhs)

Returns true if lhs is lexically less than or equal to rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the shorter array is considered less than the longer array. The lhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodePoints() in that case.

bool
operator<=(const RWBasicUString& lhs, const RWUChar32* rhs)

Returns true if lhs is lexically less than or equal to rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the shorter array is considered less than the longer array. The rhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodePoints() in that case.

bool
operator==(const RWUChar16* lhs, const RWBasicUString& rhs)

Returns true if lhs has the same length and is lexically identical to rhs; otherwise, false. The lhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodeUnits() in that case.

bool
operator==(const RWBasicUString& lhs, const RWUChar16* rhs)

Returns true if lhs has the same length and is lexically identical to rhs; otherwise, false. The rhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodeUnits() in that case.

bool
operator==(const RWBasicUString& lhs, const RWBasicUString& rhs)

Returns true if lhs has the same length and is lexically identical to rhs; otherwise, false.

bool
operator==(const RWUChar32* lhs, const RWBasicUString& rhs)

Returns true if lhs has the same length and is lexically identical to rhs; otherwise, false. The lhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodePoints() in that case.

bool
operator==(const RWBasicUString& lhs, const RWUChar32* rhs)

Returns true if lhs has the same length and is lexically identical to rhs; otherwise, false. The rhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodePoints() in that case.

bool
operator!=(const RWUChar16* lhs, const RWBasicUString& rhs)

Returns true if lhs does not have the same length as, or lexically differs from rhs; otherwise, false. The lhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodeUnits() in that case. This operator represents the logical negation of operator==.

bool
operator!=(const RWBasicUString& lhs, const RWUChar16* rhs)

Returns true if lhs does not have the same length as, or lexically differs from rhs; otherwise, false. The rhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodeUnits() in that case. This operator represents the logical negation of operator==.

bool
operator!=(const RWBasicUString& lhs, const RWBasicUString& rhs)

Returns true if lhs does not have the same length as, or lexically differs from rhs; otherwise, false. This operator represents the logical negation of operator==.

bool
operator!=(const RWUChar32* lhs, const RWBasicUString& rhs)

Returns true if lhs does not have the same length as, or lexically differs from rhs; otherwise, false. The lhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodePoints() in that case. This operator represents the logical negation of operator==.

bool
operator!=(const RWBasicUString& lhs, const RWUChar32* rhs)

Returns true if lhs is lexically greater than or equal to rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the longer array is considered greater than the shorter array. The rhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodePoints() in that case. This operator represents the logical negation of operator==.

bool
operator>=(const RWUChar16* lhs, const RWBasicUString& rhs)

Returns true if lhs is lexically greater than or equal to rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the longer array is considered greater than the shorter array. The lhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodeUnits() in that case.

bool
operator>=(const RWBasicUString& lhs, const RWUChar16* rhs)

Returns true if lhs is lexically greater than or equal to rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the longer array is considered greater than the shorter array. The rhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodeUnits() in that case.

bool
operator>=(const RWBasicUString& lhs, const RWBasicUString& rhs)

Returns true if lhs is lexically greater than or equal to rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the longer array is considered greater than the shorter array.

bool
operator>=(const RWUChar32* lhs, const RWBasicUString& rhs)

Returns true if lhs is lexically greater than or equal to rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the longer array is considered greater than the shorter array. The lhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodePoints() in that case.

bool
operator>=(const RWBasicUString& lhs, const RWUChar32* rhs)

Returns true if lhs does not have the same length as, or lexically differs from rhs; otherwise, false. The rhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodePoints() in that case.

bool
operator>(const RWUChar16* lhs, const RWBasicUString& rhs)

Returns true if lhs is lexically greater than rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the longer array is considered greater than the shorter array. The lhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodeUnits() in that case.

bool
operator>(const RWBasicUString& lhs, const RWUChar16* rhs)

Returns true if lhs is lexically greater than rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the longer array is considered greater than the shorter array. The rhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodeUnits() in that case.

bool
operator>(const RWBasicUString& lhs, const RWBasicUString& rhs)

Returns true if lhs is lexically greater than rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the longer array is considered greater than the shorter array.

bool
operator>(const RWUChar32* lhs, const RWBasicUString& rhs)

Returns true if lhs is lexically greater than rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the longer array is considered greater than the shorter array. The lhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodePoints() in that case.

bool
operator>(const RWBasicUString& lhs, const RWUChar32* rhs)

Returns true if lhs is lexically greater than rhs; otherwise, false. If the two arrays are identical over the length of the shortest array, then the longer array is considered greater than the shorter array. The rhs array must be null-terminated. This method cannot be used to compare arrays containing embedded nulls. Use RWBasicUString::compareCodePoints() in that case.

istream&
operator>>(RW_SL_IO_STD(istream&) os, RWBasicUString& ustr);
RWFile&
operator>>(RWFile& file, RWBasicUString& ustr);
RWFile&
operator>>(RWFile& file, RWBasicUString*& ustrp);
RWvistream&
operator>>(RWvistream& vis, RWBasicUString& ustr);
RWvistream&
operator>>(RWvistream& vis, RWBasicUString*& ustrp);
RWbistream&
operator>>(RWbistream& bis, RWBasicUString& ustr);
RWpistream&
operator>>(RWpistream& pis, RWBasicUString& ustr);
RWeistream&
operator>>(RWeistream& eis, RWBasicUString& ustr);
RWbistream&
operator>>(RWbistream& bis, RWBasicUString*& ustrp);
RWpistream&
operator>>(RWpistream& pis, RWBasicUString*& ustrp);
RWeistream&
operator>>(RWeistream& eis, RWBasicUString*& ustrp);
RWXDRistream&
operator>>(RWXDRistream& xis, RWBasicUString& ustr);
RWXDRistream&
operator>>(RWXDRistream& xis, RWBasicUString*& ustrp);

Reads a UTF-8 encoded string from istream. Leading white space is always skipped before storing any code points, regardless of the ios::skipws format flag setting. Code points are then extracted until:

• os.width() code points have been read, if os.width() is greater than zero

• a whitespace code point has been read

• the end of the input sequence has been reached

The following Unicode characters are treated as whitespace delimiters:

• U+0009 HORIZONTAL TABULATION

• U+000A LINE FEED

• U+000B VERTICAL TABULATION

• U+000C FORM FEED

• U+000D CARRIAGE RETURN

• U+001C FILE SEPARATOR

• U+001D GROUP SEPARATOR

• U+001E RECORD SEPARATOR

• U+001F UNIT SEPARATOR

• U+0020 SPACE

• U+0085 NEXT LINE

• U+1680 OGHAM SPACE MARK

• U+2000 EN QUAD

• U+2001 EM QUAD

• U+2002 EN SPACE

• U+2003 EM SPACE

• U+2004 THREE-PER-EM SPACE

• U+2005 FOUR-PER-EM SPACE

• U+2006 SIX-PER-EM SPACE

• U+2007 FIGURE SPACE

• U+2008 PUNCTUATION SPACE

• U+2009 THIN SPACE

• U+200A HAIR SPACE

• U+200B ZERO WIDTH SPACE

• U+2028 LINE SEPARATOR

• U+2029 PARAGRAPH SEPARATOR

• U+3000 IDEOGRAPHIC SPACE

Unlike standard extractors, this extractor must consume and discard the trailing whitespace delimiter. This behavior is due to the nature of the UTF-8 encoding scheme, which requires multiple bytes to encode some whitespace characters.

For the same reason, this extractor cannot support the the noskipws condition where the ios_base::skipws formate flag has been cleared because each extraction would consume one whitespace character. A whitespace manipulator is not provided either, since such a manipulater would consume the first non-whitespace character following a sequence of whitespace characters.

Throws RWConversionErr to report conversion errors. Throws std::ios_base::failure to report any errors detected while performing stream operations.

If the virtual stream or file experience an error while extracting the string, the operator returns the original string contents unmodified. Check the virtual stream or file to determine if an error occurred on extraction.

Description

Deallocator acts as an abstract base class for subclasses that release client-allocated storage.

Deallocator objects are required because RWBasicUString cannot assume that local invocation of methods such as delete[] or free() manipulate the same heap as that of the client, as might be the case when an application contains some libraries that use debug versions of heap management routines while others do not.

A Deallocator subclass must override both doDeallocation() methods to avoid the ambiguities produced should the subclass declaration "hide" one of the superclass declarations of these functions.

Constructor

Deallocator();

Defined only to prevent direct instantiation of this class.

Destructor

virtual
~Deallocator();

Required for virtual destruction.

Protected Member Functions

void
deallocate(RWUChar16* p);

Forwards a deallocation request to a subclass-defined non-const deallocation method.

void
deallocate(RWUChar16* p) const;

Forwards a deallocation request to a subclass-defined const deallocation method.

virtual void
doDeallocate(RWUChar16* p);

A virtual function that must be implemented in each subclass. A subclass implementation should take whatever actions are required to deallocate the storage identified by p. The default implementation of this function simply forwards to the const version.

virtual void
doDeallocate(RWUChar16* p) const = 0;

A pure virtual function that must be implemented in each subclass. A subclass implementation should take whatever actions are required to deallocate the storage identified by p.

Description

StaticDeallocator forwards deallocation requests to a simple, client-defined, static callback method of the form:

void (*deallocator)(RWUChar16*)

Constructor

StaticDeallocator(void (*deallocator)(RWUChar16*), bool destroyAfterDeallocate = false);

Constructs and initializes an instance with a pointer to a client-supplied deallocation function. The destroyAfterDeallocate is used to control the life-span of a StaticDeallocator instance. A value of true will cause the StaticDeallocator to delete itself immediately after calling the deallocator function.

Destructor

virtual
~StaticDeallocator();

Required for virtual destruction.

Protected Member Functions

virtual void
doDeallocate(RWUChar16* p);
virtual void
doDeallocate(RWUChar16* p) const;

Forwards deallocation requests to the client-supplied deallocator method.

Description

Defines an iostream manipulator that can be used to insert the contents of ustr into the output stream os, padding that string with the specified fill character codePoint until os.width() code points have been written to the stream. If the length of ustr is greater than os.width(), the string is truncated and no padding occurs. If os.width() is zero, the entire contents of the string are inserted into the stream and no padding occurs.

A Pad instance is only valid as long as the source string remains unchanged. Do not create persistent instances of this class; it should only be instantiated as a temporary in an insertion expression.

RWUString ustr = ...;
std::cout << RWUBasicString::Pad(ustr,
   static_cast<RWUChar32>('.')) << std::endl;

Constructor

Pad(const RWBasicUString& ustr, RWUChar32 codePoint =
     RWBasicUString::DefaultFillCharacter); 

Constructs a manipulator instance.

Public Member Data

const RWUChar16* data_;

The string to pad.

size_t length_; 

The code unit length of the array referenced by ustr_.

RWUChar32 codePoint_;

The code point used to pad the string.

© 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.