Text and Style Run Iteration

Unicode Text Framework provides a set of iterators for accessing the character data in an IText object. These iterators all have the properties of a random-access iterator as described by most recent version of the C++ standard.

Character Iteration

The framework provides five iterators for iterating through the characters in an IText object. These iterators are compatible with the iterator classes provided by the C++ Standard Library:

These iterators all follow the protocol for random-access iterators. You can start the iteration at any position in the IText object and iterate forward, backward, and so on. With the exception of IFastTextIterator, you should not construct iterators directly, but use the IText iterator functions begin, end, rbegin, and rend.

The iterators use the class ICharacterReference to return non-const references to UniChar values. This ensures that both the reference-counting mechanism used for IText storage and the paragraph style propagation are not disturbed.

This figure shows the basic protocol for the text iterators. Only ITextIterator is shown:

If you want to use IFastTextIterator, construct it from another text iterator. IFastTextIterator is different than the other text iterators in that it doesn't consider the styling mechanism or the shared storage mechanism. You can use IFastTextIterator when you want faster iteration. However, if you want to modify characters while using an IFastTextIterator, you need to ensure that the IText you are iterating over does not share storage with another IText. When using an IFastTextIterator:

Style Run Iteration

The framework provides an additional iterator, ITextStyleRunIterator, that lets you iterate over the style runs in a styled IText object. A style run is a range of characters with identical styling information--that is, the same set of style objects with the same values. For example, the text string shown here has four style runs:

When using ITextStyleRunIterator, you can specify whether to iterate over character styles, paragraph styles, or both. The iterator considers both types of styles by default.

This figure shows the ITextStyleRunIterator interface:

When you construct the iterator, it points to the first style run.


Iterating through Characters in an IText Object
Iterating through Style Runs in an IText Object
Querying and Modifying Styles in an IText Object