IFastTextIterator

The IFastTextIterator provides a high-performance forward iterator for IText. This class is similiar to ITextIterator, but is designed for higher performance. ITextIterator is designed to know about the styles and the reference-counting scheme and to do things in a way that works correctly with both. In addition, an ITextIterator has to be persistent. For example inserting text character by character with an iterator like the following example has to work.

 while (thisIter != thisEnd)
  that.insert(thatIter++, *thisIter++);

These requirements place a performance burden on ITextIterator, so we added another class, IFastTextIterator, that is not bound by these requirements. It ignores reference-counting so you need to ensure that the IText being iterated across does not share storage with any other ITexts if you want to change the characters with an IFastTextIterator. You can do this by passing true for the constructor's willWrite parameter. This class also ignores styles, so you have to take that into account if you change the characters with an IFastTextIterator. This class follows the protocol for an STL-compatible random-access iterator, and can be used with STL routines.

Special considerations:


IFastTextIterator - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


[view class]
~IFastTextIterator
public:
~IFastTextIterator()
Destroys the IFastTextIterator object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IFastTextIterator
Constructs an IFastTextIterator that is initialized to the given values.


Overload 1
public:
IFastTextIterator( const ITextIterator& that, bool willWrite = true )
Use this constructor to creates an IFastTextIterator that refers to the same character as the iterator passed in. This enables expressions like the following:
   IFastTextIterator iter = (IFastTextIterator)(text.begin());
that
The ITextIterator whose iterator position is copied.
willWrite
If true, constructing the iterator forces the IText under iteration traversal to guarantee that its storage is not shared, preventing changes made through the iterator from accidentally affecting other IText objects. If false, nothing special is done to the IText. This indicates a promise on the caller's behalf to use the iterator for read-only access. The default is true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IFastTextIterator()
Use this default constructor to create an IFastTextIterator object that leaves the iterator in an undefined state. The assignment operator must be called before a default-constructed iterator can be used.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IFastTextIterator( const IConstTextIterator& that, bool willWrite = true )
Use this constructor to create an IFastTextIterator object that refers to the same character as the iterator passed in. This enables expressions such as the following:
   IFastTextIterator iter = (IFastTextIterator)(text.begin());
that
The IConstTextIterator whose iterator position is copied.
willWrite
If true, constructing the iterator forces the IText under iteration traversal to guarantee that its storage is not shared, preventing changes made through the iterator from accidentally affecting other IText objects. If false, nothing special is done to the IText. This indicates a promise on the caller's behalf to use the iterator for read-only access. The default is true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IFastTextIterator(const IFastTextIterator& that)
Constructs an object of class IFastTextIterator which is copied from the given one.
that
The IFastTextIterator that is copied.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Assignment Operator


[view class]
operator =
public:
IFastTextIterator& operator =( const IFastTextIterator& that )
Points this, the current, iterator to the same character position in the same IText as the one given by that points to.
that
The IFastTextIterator object whose value replaces the current one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Comparisons

Use these operators to obtain the number of character positions between the two iterators or to compare the positions of the given iterator and the current one.


[view class]
operator !=
public:
bool operator !=(const IFastTextIterator& that) const
Returns true if the iterators refer to different character positions in the same IText. This is a straight pointer comparison. No error checking is performed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator -
public:
long operator -(const IFastTextIterator& that) const
Returns the number of character positions between the two iterators. This is a simple pointer subtraction; there is no error checking.
that
The IFastTextIterator object whose iterator position is compared with the position of the current one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator <
public:
bool operator <(const IFastTextIterator& that) const
Returns true if this, the current iterator, refers to a character with a lower offset than does the given one. This operator performs a straight pointer comparison, there is no error checking.
that
The IFastTextIterator object whose iterator position is compared with the position of the current one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator <=
public:
bool operator <=(const IFastTextIterator& that) const
Returns true if this, the current iterator, refers to the same character as does the given one or if it refers to one with a lower offset. This operator performs a straight pointer comparison, there is no error checking.
that
The IFastTextIterator object whose iterator position is compared with the position of the current one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ==
public:
bool operator ==(const IFastTextIterator& that) const
Returns true if both iterators refer to the same character position in the same IText. This is a straight pointer comparison. No error checking is performed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator >
public:
bool operator >(const IFastTextIterator& that) const
Returns true if this, the current iterator, refers to a character with a higher offset than does the current one. This operator performs a straight pointer comparison, there is no error checking.
that
The IFastTextIterator object whose iterator position is compared with the position of the current one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator >=
public:
bool operator >=(const IFastTextIterator& that) const
Returns true if this, the current iterator, refers to the same character as does the given one or if it refers to one with a higher offset. This operator performs a straight pointer comparison, there is no error checking.
that
The IFastTextIterator object whose iterator position is compared with the position of the current one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Incrementing and Decrementing


[view class]
operator ++
Advances the iterator to the next character position, that is, the position with the next-higher offset.


Overload 1
public:
IFastTextIterator operator ++(int)
Returns a copy of the iterator before it was advanced.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IFastTextIterator& operator ++()
Returns a reference to this.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator +=
public:
IFastTextIterator& operator +=(long distance)
Advances the iterator the number of character positions toward the end of the text, that is, toward higher character offsets, specified by distance. Returns a reference to this.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator -
public:
IFastTextIterator operator -(long distance) const
Returns an iterator that refers to the character at the position that occurs the number of positions specified by distance before the position of the current iterator. This is a simple pointer subtraction; there is no error checking.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator --
Advances the iterator to the previous character position, that is, the position with the next lower offset.


Overload 1
public:
IFastTextIterator& operator --()
Returns a reference to this.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IFastTextIterator operator --(int)
Returns a copy of the iterator before it was advanced.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator -=
public:
IFastTextIterator& operator -=(long distance)
Advances the iterator toward the beginning of the text, that is, toward lower character offsets, the number of character positions specified by distance. Returns a reference to this.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Obtaining a Reference to a Character

Use these functions to obtain a reference to a character whose position the iterator refers to.


[view class]
operator *
public:
UniChar& operator *() const
Returns a reference to the character the iterator refers to. This is a straight pointer dereference; there is no error checking.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator []
public:
UniChar& operator [](long offset) const
Returns a reference to the character the number of positions, specified by offset, away from the one the iterator currently refers to. Here is an example of how this iterator operator works: if iter points to position 2 in your function, iter[3] will return the character at position 5, not the character at position 3. The iterator itself is left unchanged by this operation. This is a straight pointer dereference; there is no error checking.
offset
The displacement or number of positions away from the position of the character the iterator currently refers to.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IFastTextIterator - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data