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

  - 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.

### IFastTextIterator - Member Functions and Data by Group

### Constructors & Destructor

You can construct and destruct objects of this class.

~IFastTextIterator

      public:
      ~IFastTextIterator()

  Destroys the IFastTextIterator object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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.

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None