Class: TTextIterator

Declaration: TextIterator.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

Iterates over the character and/or character-based styles in a text object. If you are interested in only the character information, see class TCharacterIterator instead. During each iteration, clients are required to call IsValid before using the returned character information. Only use the returned information when IsValid returns true. Immediately after construction, clients must call either First, Last, or SetIteratorAt in order to initialize the iterator to a valid state. Currently TTextIterator only supports character-based styles (see description of TCharacterStyleKind). Use TText::StylesAt to iterate through any other types of styles that may be applied to the text.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class is not designed for deriving.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TTextIterator::IsValid

bool IsValid ()

Interface Category:

API.

Purpose:

Determines if the iterator is currently at a valid text position. Immediately after construction, the iterator is invalid until First, Last, or SetIteratorAt is called. A valid iterator becomes invalid when the current text position is the first one and you decrement the text position. Similarly, a valid iterator becomes invalid when the current text position is the last one and you increment the text position.

Calling Context:

Call IsValid after calling First, Last, Next, Previous, or Current to determine if the returned text information is valid. Only call the functions that set the current character or get the current character and increment/decrement after first making certain the current text position is valid.

Parameters:

Return Value:

Returns true if the current text position is valid.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

An optimization technique is used internally that may be of interest to external clients with similar requirements for the fastest performance possible when iterating over large numbers of characters. Although calling IsValid is the only guaranteed way to verify the returned data from each iteration, calling this function for every iteration is not the fastest way to safely iterate over text. When the iterator is in an invalid state, TUnicodeSpecial::kNull is the returned character value. However, you can't assume that because a TUnicodeSpecial::kNull was returned that the iterator is invalid. Rather, this character will occur rarely if at all within normal text objects. So, you can check for the TUnicodeSpecial::kNull and only call IsValid on the rare occasions that this character is returned. For most text objects, this will save many calls to IsValid.

Member Function: TTextIterator::SetIteratorAt

void SetIteratorAt (TTextIndex index)

Interface Category:

API.

Purpose:

Sets the current text position at the specified index.

Calling Context:

Call immediately after constructing an iterator to initialize it to a position other than the first or last text position. Also, call this member function to reposition the iterator when sequential iteration is not desired.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextIterator::ResyncAt

void ResyncAt (TTextIndex index, bool updateCaches =true)

Interface Category:

API.

Purpose:

Sets the current text position at the specified index and resynchronizes with the associated text object.

Calling Context:

Call this member function instead of SetIteratorAt when the associated text object was modified in some way other than the character setting member functions provided by the iterator.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextIterator::GetCurrentIndex

TTextIndex GetCurrentIndex ()

Interface Category:

API.

Purpose:

Gets the current text position of the iterator.

Calling Context:

Call when you want to know the current text position.

Parameters:

Return Value:

The TTextIndex representing the current text position.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The returned index is only guaranteed to be valid if IsValid is called and returns true immediately before or after calling this function. Otherwise, it is possible the index returned is less than zero or greater than the last valid index for the associated text object.

Member Function: TTextIterator::First

  1. UniChar First ()
  2. void First (UniChar & ucode)
  3. void First (TStyleSet & set)
  4. void First (UniChar & ucode, TStyleSet & set)

Interface Category:

API.

Purpose:

Sets the iterator to the first text position. Then, gets the first character and/or styles.

Calling Context:

  1. Call when you want to get the character as the return value.
  2. Call when you want to pass in a character reference to be filled in.
  3. Call when you want to pass in a style set reference to be filled in.
  4. Call when you want to pass in a character reference and a style set reference to be filled in.

Parameters:

Return Value:

  1. The first character of the associated text object.
  2. None.
  3. None.
  4. None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The returned information will be invalid if the associated text object is empty. After calling this member function, you must call IsValid to determine if the returned information is valid.

Member Function: TTextIterator::Last

  1. UniChar Last ()
  2. void Last (UniChar & ucode)
  3. void Last (TStyleSet & set)
  4. void Last (UniChar & ucode, TStyleSet & set)

Interface Category:

API.

Purpose:

Sets the iterator to the last text position. Then, gets the last character and/or styles.

Calling Context:

  1. Call when you want to get the character as the return value.
  2. Call when you want to pass in a character reference to be filled in.
  3. Call when you want to pass in a style set reference to be filled in.
  4. Call when you want to pass in a character reference and a style set reference to be filled in.

Parameters:

Return Value:

  1. The last character of the associated text object.
  2. None.
  3. None.
  4. None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The returned information will be invalid if the associated text object is empty. After calling this member function, you must call IsValid to determine if the returned information is valid.

Member Function: TTextIterator::Current

  1. UniChar Current ()
  2. void Current (UniChar & ucode)
  3. void Current (TStyleSet & set)
  4. void Current (UniChar & ucode, TStyleSet & set)

Interface Category:

API.

Purpose:

Gets the current character and/or styles.

Calling Context:

  1. Call when you want to get the character as the return value.
  2. Call when you want to pass in a character reference to be filled in.
  3. Call when you want to pass in a style set reference to be filled in.
  4. Call when you want to pass in a character reference and a style set reference to be filled in.

Parameters:

Return Value:

  1. The current character of the associated text object.
  2. None.
  3. None.
  4. None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The returned information will be invalid if the current text position is beyond either end of the associated text object. Before or after calling this member function, you must call IsValid to determine the validity of the returned information.

Member Function: TTextIterator::CurrentAndIncrement

  1. UniChar CurrentAndIncrement ()
  2. void CurrentAndIncrement (UniChar & ucode)
  3. void CurrentAndIncrement (TStyleSet & set)
  4. void CurrentAndIncrement (UniChar & ucode, TStyleSet & set)

Interface Category:

API.

Purpose:

Gets the current character and/or styles. Then, increments the iterator to the next text position.

Calling Context:

  1. Call when you want to get the character as the return value.
  2. Call when you want to pass in a character reference to be filled in.
  3. Call when you want to pass in a style set reference to be filled in.
  4. Call when you want to pass in a character reference and a style set reference to be filled in.

Parameters:

Return Value:

  1. The current character of the associated text object.
  2. None.
  3. None.
  4. None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The returned information will be invalid if the current text position is beyond either end of the associated text object. Before calling this member function, you must call IsValid() to determine the validity of the returned information.

Member Function: TTextIterator::CurrentAndDecrement

  1. UniChar CurrentAndDecrement ()
  2. void CurrentAndDecrement (UniChar & ucode)
  3. void CurrentAndDecrement (TStyleSet & set)
  4. void CurrentAndDecrement (UniChar & ucode, TStyleSet & set)

Interface Category:

API.

Purpose:

Gets the current character and/or styles. Then, decrements the iterator to the previous text position.

Calling Context:

  1. Call when you want to get the character as the return value.
  2. Call when you want to pass in a character reference to be filled in.
  3. Call when you want to pass in a style set reference to be filled in.
  4. Call when you want to pass in a character reference and a style set reference to be filled in.

Parameters:

Return Value:

  1. The current character of the associated text object.
  2. None.
  3. None.
  4. None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The returned information will be invalid if the current text position is beyond either end of the associated text object. Before calling this member function, you must call IsValid to determine the validity of the returned information.

Member Function: TTextIterator::Next

  1. UniChar Next ()
  2. void Next (UniChar & ucode)
  3. void Next (TStyleSet & set)
  4. void Next (UniChar & ucode, TStyleSet & set)

Interface Category:

API.

Purpose:

Increments the iterator to the next text position. Then, gets the character and/or styles at the new text position.

Calling Context:

  1. Call when you want to get the character as the return value.
  2. Call when you want to pass in a character reference to be filled in.
  3. Call when you want to pass in a style set reference to be filled in.
  4. Call when you want to pass in a character reference and a style set reference to be filled in.

Parameters:

Return Value:

  1. The next character of the associated text object.
  2. None.
  3. None.
  4. None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The returned information will be invalid if the new text position is beyond the end of the associated text object. After calling this member function, you must call IsValid to determine if the returned information is valid.

Member Function: TTextIterator::Previous

  1. UniChar Previous ()
  2. void Previous (UniChar & ucode)
  3. void Previous (TStyleSet & set)
  4. void Previous (UniChar & ucode, TStyleSet & set)

Interface Category:

API.

Purpose:

Decrements the iterator to the previous text position. Then, gets the character and/or styles at the new text position.

Calling Context:

  1. Call when you want to get the character as the return value.
  2. Call when you want to pass in a character reference to be filled in.
  3. Call when you want to pass in a style set reference to be filled in.
  4. Call when you want to pass in a character reference and a style set reference to be filled in.

Parameters:

Return Value:

  1. The previous character of the associated text object.
  2. None.
  3. None.
  4. None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The returned information will be invalid if the new text position is before the beginning of the associated text object. After calling this member function, you must call IsValid to determine if the returned information is valid.

Member Function: TTextIterator::SetCurrent

void SetCurrent (UniChar newValue)

Interface Category:

API.

Purpose:

Sets the character at the current text position.

Calling Context:

Call when you want to set the character at the current text position to a new character value.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

It doesn't make sense to set the current character unless the current text position is a valid one. Before attempting to set the current character, you should call IsValid to verify that the current text position is a valid one.

Member Function: TTextIterator::SetCurrentAndIncrement

void SetCurrentAndIncrement (UniChar newValue)

Interface Category:

API.

Purpose:

Sets the current character and increment the iterator to the next text position.

Calling Context:

When you want to set multiple characters while sequentially iterating forward through the text, call this member function within a looping construct.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

It doesn't make sense to set the current character unless the current text position is a valid one. Before attempting to set the current character, you should call IsValid to verify that the current text position is a valid one.

Member Function: TTextIterator::SetCurrentAndDecrement

void SetCurrentAndDecrement (UniChar newValue)

Interface Category:

API.

Purpose:

Sets the current character and decrements the iterator to the previous text position.

Calling Context:

When you want to set multiple characters while sequentially iterating backward through the text, call this member function within a looping construct.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

It doesn't make sense to set the current character unless the current text position is a valid one. Before attempting to set the current character, you should call IsValid to verify that the current text position is a valid one.

Member Function: TTextIterator::GetChunkLastIndex

TTextIndex GetChunkLastIndex ()

Interface Category:

API.

Purpose:

Returns the last index of the currently selected range in the text object.

Calling Context:

Call to get the last index of the currently selected range in the text object.

Parameters:

Return Value:

The last index of the currently selected range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The style information for all characters in the currently selected range is identical.

Member Function: TTextIterator::GetChunkFirstIndex

TTextIndex GetChunkFirstIndex ()

Interface Category:

API.

Purpose:

Returns the first index of the currently selected range in the text object.

Calling Context:

Call to get the first index of the currently selected range in the text object.

Parameters:

Return Value:

The first index of the currently selected range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The style information for all characters in the currently selected range are identical.

Member Function: TTextIterator::~TTextIterator

~ TTextIterator ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextIterator::operator=

TTextIterator & operator =(const TTextIterator & that)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextIterator::GetText

const TText * GetText () const

Interface Category:

API.

Purpose:

Obtains a pointer to the text that the iterator is iterating over.

Calling Context:

Called to get a pointer to the text that the iterator is iterating over.

Parameters:

Return Value:

Returns a const pointer to the text that the iterator is iterating over.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextIterator::SetText

void SetText (TText * text)

Interface Category:

API.

Purpose:

Changes the text that the iterator is iterating over. This member function resets the iterator after changing the text, so you do not need to call ResyncAt after calling this member function. If you have a member function whose argument list contains a TText that the member function needs to iterator over, a performance optimization is to cache the iterator and call SetText on the iterator each time the member function is called. It is faster to call this member function than to create the iterator each time.

Calling Context:

Called to change the text that the iterator is iterating over.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The iterator assumes that the object passed into this member function will remain valid while it is being iterated over.

Member Function: TTextIterator::operator-=

TTextIterator & operator -=(TTextCount delta)

Interface Category:

API.

Purpose:

Shifts the text position from its current location by subtracting the specified amount.

Calling Context:

For repositioning the current text position in a relative manner. Use SetIteratorAt or ReSyncAt to reposition the iterator in an absolute manner.

Parameters:

Return Value:

A reference to this iterator after shifting the current text position by subtracting the specified amount.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextIterator::operator+=

TTextIterator & operator += (TTextCount delta)

Interface Category:

API.

Purpose:

Shifts the text position from its current location by adding the specified amount.

Calling Context:

For repositioning the current text position in a relative manner. Use SetIteratorAt or ReSyncAt to reposition the iterator in an absolute manner.

Parameters:

Return Value:

A reference to this iterator after shifting the current text position by adding the specified amount.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextIterator::TTextIterator

  1. TTextIterator (TText * text)
  2. TTextIterator (const TTextIterator & that)

Interface Category:

API.

Purpose:

  1. Constructs a text iterator for the specified text object.
  2. Copy constructor.

Calling Context:

  1. Construct one of these to iterate over characters and styles. Use a TCharacterIterator to iterate over only the characters. Use the TText::StylesAt member function to iterate over just the styles.
  2. Called to copy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Immediately after construction, clients must call either First, Last, or SetIteratorAt in order to initialize the iterator to a valid state. A reference to the input text object is used throughout the life of a text iterator. Therefore, a text iterator is only valid as long as the associated text object is in existence. Similarly, the ReSyncAt member functions must be called to synchronize the iterator with the associated text object when the text object is changed in any way besides the character setting functions provided.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.