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:
- If the caller uses an IFastTextIterator for writing, he must initialize it passing true for its
willWrite parameter (this is the default). If you pass false for willWrite, but still
write through the iterator, you may accidentally change other ITexts as well.
- IFastTextIterator does not do anything to styles. You must keep this in mind when
using an IFastTextIterator to make changes to a styled IText.
- Do not initialize another IText from the IText under iteration or assign the IText under
iteration to another IText while an IFastTextIterator is in effect. This could cause changes
to the IText under iteration to affect the other IText.
- Do not call any non-const methods (or c_str() or data()) on the IText under iteration while
an IFastTextIterator is in effect. The iterator is not guaranteed to remain valid across such
calls.
- Do not derive from this class.