Class: TCharacterIterator

Declaration: TextIterator.h

Taxonomy Categories:

Member Functions:

IsValid
SetIteratorAt
ResyncAt
GetCurrentIndex
First
Last
Current
CurrentAndIncrement
CurrentAndDecrement
Next
Previous
SetCurrent
SetCurrentAndIncrement
SetCurrentAndDecrement
~TCharacterIterator
operator=
GetText
SetText
operator-=
operator+=
TCharacterIterator

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

Iterates over just the character information in a text object. If you are interested in style information too, see class TTextIterator 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.

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: TCharacterIterator::IsValid

bool IsValid ()

Interface Category:

API.

Purpose:

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

Calling Context:

Call IsValid after calling First, Last, Next, Previous, or Current to determine if the returned character 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 character position is valid.

Parameters:

Takes no parameters.

Return Value:

Returns true if the current character 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 characters. 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: TCharacterIterator::SetIteratorAt

void SetIteratorAt (TTextIndex index)

Interface Category:

API.

Purpose:

Sets the current character 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 character position. Also, call this member function to reposition the iterator when sequential iteration is not desired.

Parameters:

TTextIndex index -The new character position for the iterator.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterIterator::ResyncAt

void ResyncAt (TTextIndex index, bool updateCaches =true)

Interface Category:

API.

Purpose:

Sets the current character 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:

TTextIndex index -The new character position for the iterator.
bool updateCaches =true -Whether to resynchronize with the associated text object or not. The default is to always force things to be in sync. However, you can override this default by passing false for this parameter. In that case, this function works exactly like SetIteratorAt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterIterator::GetCurrentIndex

TTextIndex GetCurrentIndex ()

Interface Category:

API.

Purpose:

Gets the current character position of the iterator.

Calling Context:

Call when you want to know the current character position.

Parameters:

Takes no parameters.

Return Value:

The TTextIndex representing the current character 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: TCharacterIterator::First

UniChar First ()
void First (UniChar & ucode)

Interface Category:

API.

Purpose:

Sets the iterator to the first character position and returns the first character.

Calling Context:

Call when you want to get the character as the return value.
Call when you want to pass in your own character reference to be filled in.

Parameters:

Takes no parameters.
UniChar & ucode -The output character that gets set with the character at the current character position.

Return Value:

The first character of the associated text object.
None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TCharacterIterator::Last

UniChar Last ()
void Last (UniChar & ucode)

Interface Category:

API.

Purpose:

Sets the iterator to the last character position and returns the last character.

Calling Context:

Call when you want to get the character as the return value.
Call when you want to pass in your own character reference to be filled in.

Parameters:

Takes no parameters.
UniChar & ucode -The output character that gets set with the character at the current character position.

Return Value:

The last character of the associated text object.
None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TCharacterIterator::Current

UniChar Current ()
void Current (UniChar & ucode)

Interface Category:

API.

Purpose:

Gets the character at the current character position of the iterator.

Calling Context:

Call when you want to get the character as the return value.
Call when you want to pass in your own character reference to be filled in.

Parameters:

Takes no parameters.
UniChar & ucode -The output character that gets set with the character at the current character position.

Return Value:

The current character of the associated text object.
None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The returned character will be invalid if the current character 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 character.

Member Function: TCharacterIterator::CurrentAndIncrement

UniChar CurrentAndIncrement ()
void CurrentAndIncrement (UniChar & ucode)

Interface Category:

API.

Purpose:

Gets the character at the current character position and increments the iterator to the next character position.

Calling Context:

Call when you want to get the character as the return value.
Call when you want to pass in your own character reference to be filled in.

Parameters:

Takes no parameters.
UniChar & ucode -The output character that gets set with the character at the current character position.

Return Value:

The current character of the associated text object.
None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TCharacterIterator::CurrentAndDecrement

UniChar CurrentAndDecrement ()
void CurrentAndDecrement (UniChar & ucode)

Interface Category:

API.

Purpose:

Gets the character at the current character position and decrement the iterator to the previous character position.

Calling Context:

Call when you want to get the character as the return value.
Call when you want to pass in your own character reference to be filled in.

Parameters:

Takes no parameters.
UniChar & ucode -The output character that gets set with the character at the current character position.

Return Value:

The current character of the associated text object.
None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TCharacterIterator::Next

UniChar Next ()
void Next (UniChar & ucode)

Interface Category:

API.

Purpose:

Increments the iterator to the next character position and return the character at the new character position.

Calling Context:

Call when you want to get the character as the return value.
Call when you want to pass in your own character reference to be filled in.

Parameters:

Takes no parameters.
UniChar & ucode -The output character that gets set with the character at the new character position.

Return Value:

The next character of the associated text object.
None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TCharacterIterator::Previous

UniChar Previous ()
void Previous (UniChar & ucode)

Interface Category:

API.

Purpose:

Decrements the iterator to the previous character position and return the character at the new character position.

Calling Context:

Call when you want to get the character as the return value.
Call when you want to pass in your own character reference to be filled in.

Parameters:

Takes no parameters.
UniChar & ucode -The output character that gets set with the character at the new character position.

Return Value:

The previous character of the associated text object.
None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TCharacterIterator::SetCurrent

void SetCurrent (UniChar newValue)

Interface Category:

API.

Purpose:

Set the character at the current character position.

Calling Context:

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

Parameters:

UniChar newValue -The new value for the current character.

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 character position is a valid one. Before attempting to set the current character, you should call IsValid to verify that the current character position is a valid one.

Member Function: TCharacterIterator::SetCurrentAndIncrement

void SetCurrentAndIncrement (UniChar newValue)

Interface Category:

API.

Purpose:

Set the current character and increments the iterator to the next character 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:

UniChar newValue -The new value for the current character.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TCharacterIterator::SetCurrentAndDecrement

void SetCurrentAndDecrement (UniChar newValue)

Interface Category:

API.

Purpose:

Sets the current character and decrements the iterator to the previous character 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:

UniChar newValue -The new value for the current character.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TCharacterIterator::~TCharacterIterator

~ TCharacterIterator ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterIterator::operator=

TCharacterIterator & operator =(const TCharacterIterator & that)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TCharacterIterator & that -The source object for the assignment.

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

Takes no 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: TCharacterIterator::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:

TText * text -The new text that the iterator will be iterating over.

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: TCharacterIterator::operator-=

TCharacterIterator & operator -=(TTextCount delta)

Interface Category:

API.

Purpose:

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

Calling Context:

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

Parameters:

TTextCount delta -The amount to subtract from the current character position.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterIterator::operator+=

TCharacterIterator & operator += (TTextCount delta)

Interface Category:

API.

Purpose:

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

Calling Context:

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

Parameters:

TTextCount delta -The amount to add to the current character position.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterIterator::TCharacterIterator

TCharacterIterator (TText * text)
TCharacterIterator (const TCharacterIterator & that)

Interface Category:

API.

Purpose:

Constructs a character iterator for the specified text object.
Copy constructor.

Calling Context:

Construct one of these to iterate over just the characters. Use a TTextIterator to iterate over both the characters and styles at the same time. Use the TText::StylesAt member function to iterate over just the styles.
Called to copy an object.

Parameters:

TText * text -The text object to be iterated over.
const TCharacterIterator & that -The object to copy.

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 character iterator. Therefore, a character 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.