RWUSubString

Module:  Internationalization Module   Group:  Unicode String Processing

Does Not Inherit

• Local Index
• Header File
• Description
• Example
• Public Constructors
• Global Operators
• Public Member Operators
• Public Member Functions

Members

boundsCheckIndex() data() isNull()

length() operator()() operator=()

operator[]() RWUSubString() start()

Non-Members

operator!=() operator>>()

operator>() operator>=()

operator<<() operator<()

operator<=() operator==()

#include <rw/i18n/RWUSubString.h> 

RWUSubString allows read-write access to a range of code units within a referenced RWUString. The range is defined by a starting position and an length within the referenced string. For example, the 7th through the 11th elements, inclusive, would have a starting position of 7 and an extent of 5.

There are no public constructors. RWUSubStrings are constructed by various functions of the RWUString class. Typically, substrings are created and used anonymously, then destroyed immediately.

RWUSubString performs bounds checking in all methods that accept an offset value. These methods throw an RWBoundsErr exception if an offset exceeds the current bounds of the substring.

#include <rw/i18n/RWUString.h>
#include <rw/i18n/RWUSubString.h>
#include <rw/i18n/RWUConversionContext.h>
#include <iostream>

using std::cout;
using std::endl;

int
main()
{
  // Indicate that source and target strings are
  // encoded as ISO8859-1.
  RWUConversionContext context("ISO8859-1");

  // Initialize a Unicode string.
  RWUString str("Encoded as Latin-1");

  // Modify a substring.
  str(11, 5) = "ISO8859";

  // Print the result.
  cout << str << endl;

  return 0;
} // main

Results:
========

Encoded as ISO8859-1

RWUSubString(const RWUSubString& source);

Constructs an RWUSubString from source.

RW_SL_IO_STD(ostream&)
operator<<(RW_SL_IO_STD(ostream&) os,
           const RWUSubString& ustr);

Writes the sequence of bytes to ostream that are produced when the contents of ustr are converted into the character encoding scheme specified by the currently active target RWUFromUnicodeConversionContext.

If os.width() is greater than the number of code points contained in the source string, the output 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 are 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 if neither flag is set.

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

RW_SL_IO_STD(istream&)
operator>>(RW_SL_IO_STD(istream&) is, RWUSubString& ustr);

Reads an encoded byte stream from istream. The byte sequence is converted into UTF-16 using the currently active RWUToUnicodeConversionContext. Leading whitespace 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 are read, if os.width() is greater than zero

• a whitespace code point is read

• the end of the input sequence is 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 noskipws condition where the ios_base::skipws format flag has been cleared; each extraction will consume one whitespace character. Nor is a whitespace manipulator provided, since such a manipulator would consume the first non-whitespace character following a sequence of whitespace characters.

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

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

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

The lhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodeUnits() in that case.

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

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

The rhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodeUnits() in that case.

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

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

The lhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodePoints() in that case.

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

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

The rhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodePoints() in that case.

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

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

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

Returns true if lhs has the same length and is lexigraphically identical to rhs; otherwise, false. If the two strings are identical over the length of the shortest string, then the shorter string is considered less than the longer string.

The lhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodeUnits() in that case.

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

Returns true if lhs has the same length and is lexigraphically identical to rhs; otherwise, false. If the two strings are identical over the length of the shortest string, then the shorter string is considered less than the longer string.

The rhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodeUnits() in that case.

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

Returns true if lhs has the same length and is lexigraphically identical to rhs; otherwise, false. If the two strings are identical over the length of the shortest string, then the shorter string is considered less than the longer string.

The lhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodePoints() in that case.

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

Returns true if lhs has the same length and is lexigraphically identical to rhs; otherwise, false. If the two strings are identical over the length of the shortest string, then the shorter string is considered less than the longer string.

The rhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodePoints() in that case.

bool
operator<=(const RWUSubString& lhs, const RWUSubString& rhs);

Returns true if lhs has the same length and is lexigraphically identical to rhs; otherwise, false. Returns true if both substrings are null. If the two strings are identical over the length of the shortest string, then the shorter string is considered less than the longer string.

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

Returns true if lhs has the same length and is lexigraphically identical to rhs; otherwise, false. If the two strings are identical over the length of the shortest string, then the shorter string is considered less than the longer string.

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

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

The lhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodeUnits() in that case.

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

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

The rhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodeUnits() in that case.

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

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

The lhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodePoints() in that case.

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

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

The rhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodePoints() in that case.

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

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

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

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

The lhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodeUnits() in that case.

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

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

The rhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodeUnits() in that case.

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

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

The lhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodePoints() in that case.

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

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

The rhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodePoints() in that case.

bool
operator!=(const RWUSubString& lhs, const RWUSubString& rhs);

Returns true if lhs does not have the same length as, or lexigraphically differs from, rhs; otherwise, false. Also returns false if both substrings are invalid. This operator represents the logical negation of operator==.

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

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

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

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

The rhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodeUnits() in that case.

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

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

The lhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodeUnits() in that case.

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

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

The rhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodePoints() in that case.

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

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

The lhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodePoints() in that case.

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

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

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

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

The lhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodeUnits() in that case.

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

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

The rhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodeUnits() in that case.

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

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

The lhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodePoints() in that case.

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

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

The rhs string must be null-terminated. This method cannot be used to compare strings containing embedded nulls; use RWBasicUString::compareCodePoints() in that case.

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

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

RWUChar16
operator[](size_t offset) const; 

Returns the code unit located at index offset within self. The value of offset must be less than length().

Throws RWBoundsErr if self is a null substring, or if offset is greater than or equal to length().

RWUChar16&
operator[](size_t offset);

Returns a reference object that provides read-write access to the code unit located at index offset within self. The result can be used as an RWUChar16 value, or as an l-value in an RWUChar16 assignment expression. The value of offset must be less than length().

Throws RWBoundsErr if self is a null substring, or if offset is greater than or equal to length().

RWUChar16
operator()(size_t offset) const; 

Returns the code unit located at index offset within self. The value of offset must be less than length().

Throws RWBoundsErr if self is a null substring, or if offset is greater than or equal to length().

RWUChar16&
operator()(size_t offset); 

Returns a reference object that provides read-write access to the code unit located at index offset within self. The result can be used as an RWUChar16 value, or as an l-value in an RWUChar16 assignment expression. The value of offset must be less than length().

Throws RWBoundsErr if self is a null substring, or if offset is greater than or equal to length().

RWUSubString&
operator=(const RWBasicUString& source); 

Replaces the substring defined by self with source.

RWUSubString&
operator=(const RWUSubString& source);

Replaces the substring defined by self with source.

RWUSubString&
operator=(const RWUConstSubString& source);

Replaces the substring defined by self with source.

RWUSubString&
operator=(const RWUChar16* source);

Replaces the substring defined by self with the null-terminated array source.

RWUSubString&
operator=(const RWUChar32* source);

Replaces the substring defined by self with the null-terminated array source.

RWUSubString&
operator=(RWUChar16 codeUnit);

Replaces the substring defined by self with codeUnit.

RWUSubString&
operator=(RWUChar32 codePoint);

Replaces the substring defined by self with codeUnit.

size_t
boundsCheckIndex(size_t offset) const;

Throws RWBoundsErr exception if self is a null substring, or if offset is greater than or equal to length(); otherwise, simply returns offset.

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

const RWUChar16*
data() const;

Returns a pointer to the string contents referenced by self.

The storage referenced by this pointer is owned by the RWUString associated with this substring. This storage may not be deleted or modified. The pointer becomes invalid if the RWUString is modified or destroyed.

Throws RWBoundsErr if self is a null substring.

bool
isNull() const;

Returns true if the substring defined by self is null or empty; otherwise, false.

size_t
length() const; 

Returns the number of code units in the substring defined by self.

size_t
start() const; 

Returns the start position of the substring defined by self within the RWUString referenced by self. A return value of RW_NPOS indicates that self is a null substring.

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