### 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:

- ITextIterator provides iteration through the characters in an IText object.
- IReverseTextIterator provides backwards iteration through the characters in an IText object.
- IConstTextIterator is a variation on ITextIterator that doesn't allow you to modify the characters.
- IReverseConstTextIterator is a variation on IReverseTextIterator that doesn't allow you to modify the characters.
- IFastTextIterator provides faster iteration than the iterators listed above but fewer safety assurances. For example, the iterator is not guaranteed to stay valid if the underlying text is modified.

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:

- Do not initialize another IText object from the IText under iteration or assign the IText to another IText while the IFastTextIterator is in effect.
- Do not call non-`const` functions on the IText under iteration while the IFastTextIterator is in effect.
- Keep in mind that IFastTextIterator ignores styles when iterating over styled text. Paragraph styles will not be repropagated, and character styles will not be manipulated with their associated characters.
- Set the willWrite parameter to `false` if you want to use the iterator for read-only access of characters.

#### 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:

- operator* and operator-> return the set of styles on the current style run. operator* returns a reference to the style set, while operator-> provides direct access to the members of the style set.
- runLength and runStart return the length and starting offset of the current style run.
- operator++ and operator-- advance to the next or previous style set.
- operator bool indicates when iteration is complete.
- setCharacterOffset points the iterator to the style run that contains the specified offset.

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