RWUConstStringIterator Class Reference

Provides read-only access to the code points encoded by the code units within an RWBasicUString. More...

#include <rw/i18n/RWUConstStringIterator.h>

Public Types
typedef int	difference_type
typedef std::bidirectional_iterator_tag	iterator_category
typedef value_type *	pointer
typedef value_type &	reference
typedef size_t	size_type
typedef RWUChar32	value_type

Public Member Functions
	RWUConstStringIterator ()
	RWUConstStringIterator (const RWBasicUString &ustr)
	RWUConstStringIterator (const RWUConstStringIterator &iter)
	RWUConstStringIterator (const RWUStringIterator &iter)
void	advanceCodePoints (int offset)
const RWUChar16 *	data () const
	operator size_t () const
RWUChar32	operator* () const
RWUConstStringIterator &	operator++ ()
RWUConstStringIterator	operator++ (int)
RWUConstStringIterator &	operator-- ()
RWUConstStringIterator	operator-- (int)
RWUConstStringIterator &	operator= (const RWUConstStringIterator &iter)

Friends
class	RWUString
class	RWUStringIterator

Related Symbols
(Note that these are not member symbols.)
bool	operator!= (const RWUConstStringIterator &lhs, const RWUConstStringIterator &rhs)
bool	operator!= (const RWUConstStringIterator &lhs, const RWUStringIterator &rhs)
bool	operator== (const RWUConstStringIterator &lhs, const RWUConstStringIterator &rhs)
bool	operator== (const RWUConstStringIterator &lhs, const RWUStringIterator &rhs)

Detailed Description

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

• Access the beginning of a string using RWUString::beginCodePointIterator(). Use operator*() on a begin iterator to return the first code point in the string.
• Access the end of a string using RWUString::endCodePointIterator(). The end iterator references the location just after the last code point in the string.
• Use RWUString::beginCodePointIterator() and RWUString::endCodePointIterator() and the comparison operators to determine whether an iterator has reached the beginning or end of the string.

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.

Instances of RWUConstStringIterator are returned from const RWUString objects, and from instances of classes such as RWUBreakSearch. These classes return RWUConstStringIterator instances because the instances cannot be used to modify the source string.

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 produces an RWBoundsErr exception.

Conversion Errors

An RWUConstStringIterator converts code units into code points. Code points 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. An iterator throws an RWConversionErr exception if an incomplete surrogate pair is encountered.

Example

#include <rw/i18n/RWUConstStringIterator.h>
#include <rw/i18n/RWUString.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);
  const RWUString& strRef = str;
 
  // Iterate backward over all code points in the string
  RWUConstStringIterator it = strRef.endCodePointIterator();
  while (it != strRef.beginCodePointIterator()) {
    --it;
    std::cout << std::hex << int(*it) << std::endl;
  }
 
  return 0;
}

Program Output:

d
2e
64
6c
72
6f
77
20
d
2c
6f
6c
6c
65
48

See also

RWBasicUString, RWUString, RWUStringIterator, RWUBreakSearch

Member Typedef Documentation

difference_type

typedef int RWUConstStringIterator::difference_type

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

iterator_category

typedef std::bidirectional_iterator_tag RWUConstStringIterator::iterator_category

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

pointer

typedef value_type* RWUConstStringIterator::pointer

Declares an alias for the value_type pointer.

reference

typedef value_type& RWUConstStringIterator::reference

Declares an alias for the value_type reference.

size_type

typedef size_t RWUConstStringIterator::size_type

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

value_type

typedef RWUChar32 RWUConstStringIterator::value_type

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

Constructor & Destructor Documentation

RWUConstStringIterator() [1/4]

RWUConstStringIterator::RWUConstStringIterator ( )

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.

RWUConstStringIterator() [2/4]

RWUConstStringIterator::RWUConstStringIterator

(

const RWBasicUString &

ustr

)

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

RWUConstStringIterator() [3/4]

RWUConstStringIterator::RWUConstStringIterator ( const RWUConstStringIterator & iter )

inline

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

RWUConstStringIterator() [4/4]

RWUConstStringIterator::RWUConstStringIterator

(

const RWUStringIterator &

iter

)

Constructs an RWUConstStringIterator from the given RWUStringIterator iter.

Note

There is no corresponding conversion from RWUConstStringIterator to RWUStringIterator. This preserves const correctness for the iterator classes.

Member Function Documentation

advanceCodePoints()

void RWUConstStringIterator::advanceCodePoints

(

int

offset

)

Advances self by offset code points.

Exceptions

RWBoundsErr

Thrown 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 and not dereferencable.

RWConversionErr

Thrown 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 * RWUConstStringIterator::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()

RWUConstStringIterator::operator size_t ( ) const

inline

Returns the current code unit offset of self.

operator*()

RWUChar32 RWUConstStringIterator::operator*

(

)

const

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

Exceptions

RWBoundsErr	Thrown if self is null or otherwise references a position outside the bounds of the string.
RWConversionErr	Thrown 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]

RWUConstStringIterator & RWUConstStringIterator::operator++

(

)

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

Exceptions

RWBoundsErr	Thrown 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.
RWConversionErr	Thrown 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]

RWUConstStringIterator RWUConstStringIterator::operator++ ( int )

inline

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

Exceptions

RWBoundsErr	Thrown 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.
RWConversionErr	Thrown 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]

RWUConstStringIterator & RWUConstStringIterator::operator--

(

)

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

Exceptions

RWBoundsErr	Thrown if self is already positioned at the beginning of the string, or if self is null. The iterator position is left unchanged.
RWConversionErr	Thrown 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]

RWUConstStringIterator RWUConstStringIterator::operator-- ( int )

inline

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

Exceptions

RWBoundsErr	Thrown if self is already positioned at the beginning of the string, or if self is null. The iterator position is left unchanged.
RWConversionErr	Thrown 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=()

RWUConstStringIterator & RWUConstStringIterator::operator= ( const RWUConstStringIterator & 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 RWUConstStringIterator & lhs, const RWUConstStringIterator & rhs )

related

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

operator!=() [2/2]

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

related

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

operator==() [1/2]

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

related

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

operator==() [2/2]

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

related

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