SourcePro® API Reference Guide

 
Loading...
Searching...
No Matches

Bidirectional iterator that provides read-write access to the code points encoded by the code units within an RWUString. More...

#include <rw/i18n/RWUStringIterator.h>

Classes

class  RWUChar32Reference
 Provides transparent read-write access to a code point referenced by an RWUStringIterator. More...
 

Public Types

typedef int difference_type
 
typedef std::bidirectional_iterator_tag iterator_category
 
typedef RWUChar32Referencepointer
 
typedef RWUChar32Reference reference
 
typedef size_t size_type
 
typedef RWUChar32 value_type
 

Public Member Functions

 RWUStringIterator ()
 
 RWUStringIterator (const RWUStringIterator &iter)
 
 RWUStringIterator (RWBasicUString &ustr)
 
void advanceCodePoints (int offset)
 
const RWUChar16data () const
 
 operator size_t () const
 
RWUChar32Reference operator* ()
 
RWUChar32 operator* () const
 
RWUStringIteratoroperator++ ()
 
RWUStringIterator operator++ (int)
 
RWUStringIteratoroperator-- ()
 
RWUStringIterator operator-- (int)
 
RWUStringIteratoroperator= (const RWUStringIterator &iter)
 

Friends

class RWUConstStringIterator
 
class RWUString
 

Related Symbols

(Note that these are not member symbols.)

bool operator!= (const RWUStringIterator &lhs, const RWUConstStringIterator &rhs)
 
bool operator!= (const RWUStringIterator &lhs, const RWUStringIterator &rhs)
 
bool operator== (const RWUStringIterator &lhs, const RWUConstStringIterator &rhs)
 
bool operator== (const RWUStringIterator &lhs, const RWUStringIterator &rhs)
 

Detailed Description

RWUStringIterator provides read-write access to the code points encoded by the code units within an RWUString. Code points within a given string are accessed in forward or reverse order, starting from the beginning or end of the string, respectively.

Attempting to dereference or advance an iterator that is positioned past the end of the string, such as the iterator returned by RWUString::endCodePointIterator(), throws RWBoundsErr.

The code points in an RWBasicUString can be changed using an RWUStringIterator. For example, consider an RWUStringIterator iter, and a code point stored in an RWUChar32 named codePoint. This statement changes the code point referenced by iter to the value in codePoint:

*iter = codePoint;

Note that this operation may change the length of the original string if a surrogate pair (two 16-bit code units) is replaced with a single 16-bit code point, or vice-versa.

Bounds Checking

Bounds checking always occurs when repositioning or dereferencing an iterator. Any attempt to dereference an iterator that is in the past-the-end condition throws RWBoundsErr.

Conversion Errors

An RWUStringIterator converts code units into code points. Code points with scalar values greater than 0xFFFF are encoded as a pair of surrogate code units within the string. An RWUStringIterator cannot advance over or dereference an incomplete surrogate pair. RWUStringIterator throws RWConversionErr if an incomplete surrogate pair is encountered.

Example
#include <rw/i18n/RWUString.h>
#include <rw/i18n/RWUStringIterator.h>
#include <iostream>
int main() {
// "Hello,\n world.\n";
RWUChar16 buf[16] = {0x0048, 0x0065, 0x006c, 0x006c, 0x006f, 0x002c,
0x000d, 0x0020, 0x0077, 0x006f, 0x0072, 0x006c,
0x0064, 0x002e, 0x000d, 0x0000};
// Create the RWUString from the buffer
RWUString str(buf);
RWUStringIterator it = str.beginCodePointIterator();
// Replace all carriage return characters with NULL characters
for (; it != str.endCodePointIterator(); ++it) {
if (*it == RWUChar32(0x000d)) {
*it = RWUChar32(0x0000);
}
} // for
// Iterate forward over all code points in the string
for (it = str.beginCodePointIterator();
it != str.endCodePointIterator(); ++it) {
std::cout << std::hex << int(*it) << std::endl;
} // for
return 0;
} // main
Bidirectional iterator that provides read-write access to the code points encoded by the code units w...
Definition RWUStringIterator.h:136
Stores and manipulates Unicode character sequences encoded as UTF-16 code units.
Definition RWUString.h:187
unspecified_32bit_type RWUChar32
Definition uchar.h:91
unspecified_16bit_type RWUChar16
Definition uchar.h:66

Program Output:

48
65
6c
6c
6f
2c
0
20
77
6f
72
6c
64
2e
0
See also
RWBasicUString, RWUString, RWUConstStringIterator

Member Typedef Documentation

◆ difference_type

Declares an alias for the type used to represent iterator offsets and differences.

◆ iterator_category

typedef std::bidirectional_iterator_tag RWUStringIterator::iterator_category

Declares this class to be a C++ Standard Library-compatible bidirectional iterator.

◆ pointer

Declares an alias for the value_type pointer.

◆ reference

Declares an alias for the value_type reference.

◆ size_type

Declares an alias for the type used to represent sizes and indices.

◆ value_type

Declares an alias for the value type returned by this iterator class.

Constructor & Destructor Documentation

◆ RWUStringIterator() [1/3]

RWUStringIterator::RWUStringIterator ( )
inline

Constructs a null, non-dereferencable iterator. The instance cannot be used until a dereferencable iterator is assigned to it. Any attempt to reposition or dereference a null iterator will cause an RWBoundsErr exception to be thrown.

◆ RWUStringIterator() [2/3]

RWUStringIterator::RWUStringIterator ( RWBasicUString & ustr)

Constructs an RWUStringIterator that is positioned at the first element of ustr, or past-the-end of ustr if ustr is empty.

◆ RWUStringIterator() [3/3]

RWUStringIterator::RWUStringIterator ( const RWUStringIterator & iter)
inline

Constructs an RWUStringIterator that references the same string and offset as iter.

Member Function Documentation

◆ advanceCodePoints()

void RWUStringIterator::advanceCodePoints ( int offset)

Advances self by offset code points.

Exceptions
RWBoundsErrThrown if self is advanced before the first element or after one past the last element in the string. If offset is negative, the iterator is left pointing at the first element in the string. If offset is positive, the iterator is left pointing one past the last element in the string. RWBoundsErr is also thrown if self is null.
RWConversionErrThrown if an incomplete surrogate pair is encountered where either the high surrogate or the low surrogate code unit is missing. If offset is negative, the iterator is positioned at the code unit immediately preceding the unpaired surrogate code unit, or at the first code unit of the string if the unpaired surrogate is the first code unit in the string. If offset is positive, the iterator is positioned at the code unit immediately following the unpaired surrogate code unit, or one past the last code unit of the string if the unpaired surrogate is the last code unit in the string.

◆ data()

const RWUChar16 * RWUStringIterator::data ( ) const

Returns a pointer to the string contents at the location referenced by self.

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

◆ operator size_t()

RWUStringIterator::operator size_t ( ) const
inline

Returns the current code unit offset of self.

◆ operator*() [1/2]

RWUStringIterator::RWUChar32Reference RWUStringIterator::operator* ( )
inline

Returns a reference object that provides read-write access to the code point located at the current iterator position. Invoked when dereferencing non-const RWUStringIterator objects. The result can be used as an RWUChar32 value, or as an l-value in an RWUChar32 assignment expression.

This method does not throw any exceptions, even if self is non-dereferencable or refers to a malformed surrogate pair. However, the reference object throws RWBoundsErr or RWConversionErr if self is used as an r-value or l-value in an expression and these conditions are detected.

◆ operator*() [2/2]

RWUChar32 RWUStringIterator::operator* ( ) const

Returns the value of the code point currently referenced by self.

Exceptions
RWBoundsErrThrown if self is null or otherwise references a position outside the bounds of the string.
RWConversionErrThrown if the code unit sequence found at the current iterator position contains an incomplete surrogate pair where either the high surrogate or the low surrogate code unit is missing.

◆ operator++() [1/2]

RWUStringIterator & RWUStringIterator::operator++ ( )

Advances self to the next code point in the string and returns a reference to self.

Exceptions
RWBoundsErrThrown if self is already positioned one past the last code point in the string, or if self is null. The iterator position is left unchanged.
RWConversionErrThrown if the code unit sequence found at the current iterator position contains an incomplete surrogate pair where either the high surrogate or the low surrogate code unit is missing. Self is left pointing at the code unit immediately following the unpaired surrogate code unit, or one past the last code unit of the string if the unpaired surrogate is the last code unit in the string.

◆ operator++() [2/2]

RWUStringIterator RWUStringIterator::operator++ ( int )
inline

Advances self to the next code point in the string, and returns a copy of the previous value of self.

Exceptions
RWBoundsErrThrown if self is already positioned one past the last code point in the string, or if self is null. The iterator position is left unchanged.
RWConversionErrThrown if the code unit sequence found at the current iterator position contains an incomplete surrogate pair where either the high surrogate or the low surrogate code unit is missing. Self is left pointing at the code unit immediately following the unpaired surrogate code unit, or one past the last code unit of the string if the unpaired surrogate is the last code unit in the string.

◆ operator--() [1/2]

RWUStringIterator & RWUStringIterator::operator-- ( )

Advances self to the preceding code point in the string and returns a reference to self.

Exceptions
RWBoundsErrThrown if self is already positioned at the beginning of the string, or if self is null. The iterator position is left unchanged.
RWConversionErrThrown if the code unit sequence found at the current iterator position contains an incomplete surrogate pair where either the high surrogate or the low surrogate code unit is missing. Self is left pointing at the unpaired code unit.

◆ operator--() [2/2]

RWUStringIterator RWUStringIterator::operator-- ( int )
inline

Advances self to the preceding code point in the string and returns a copy of the previous value of self.

Exceptions
RWBoundsErrThrown if self is already positioned at the beginning of the string, or if self is null. The iterator position is left unchanged.
RWConversionErrThrown if the code unit sequence found at the current iterator position contains an incomplete surrogate pair where either the high surrogate or the low surrogate code unit is missing. Self is left pointing at the unpaired code unit.

◆ operator=()

RWUStringIterator & RWUStringIterator::operator= ( const RWUStringIterator & iter)
inline

Changes self so it references the same string and offset as iter, and returns a reference to self.

Friends And Related Symbol Documentation

◆ operator!=() [1/2]

bool operator!= ( const RWUStringIterator & lhs,
const RWUConstStringIterator & rhs )
related

Returns true if the two iterators reference different RWBasicUString objects, or if the code point offsets referenced by the iterators are different; otherwise, false.

◆ operator!=() [2/2]

bool operator!= ( const RWUStringIterator & lhs,
const RWUStringIterator & rhs )
related

Returns true if the two iterators reference different RWBasicUString objects, or if the code point offsets referenced by the iterators are different; otherwise, false.

◆ operator==() [1/2]

bool operator== ( const RWUStringIterator & lhs,
const RWUConstStringIterator & rhs )
related

Returns true if both iterators reference the same RWBasicUString, and are positioned at the same code point offset within RWBasicUString; otherwise, false.

◆ operator==() [2/2]

bool operator== ( const RWUStringIterator & lhs,
const RWUStringIterator & rhs )
related

Returns true if both iterators reference the same RWBasicUString, and are positioned at the same code point offset within the RWBasicUString; otherwise, false.

Copyright © 2024 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.