Class: TTextRegionIterator

Declaration: TextRegion.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

Provides read-only sequential iteration over the text ranges that define a text region. It iterates over the ranges in increasing order, for example range[n].GetEnd() < range[n+1].GetBegin(). You must supply the text region at the time of construction. An invariant of this class is that no text range is ever returned with a length of zero.

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

TTextRegionIterator (const TTextRegion & region)

Interface Category:

API.

Purpose:

Constructs a region iterator for the specified region.

Calling Context:

When you want to get the contiguous ranges that define a potentially discontiguous region.

Parameters:

const TTextRegion & region -The region to be iterated over.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

A reference to the input region is used throughout the life of a region iterator. Therefore, a region iterator is only valid as long as the associated region is in existence. Similarly, the First or Last member functions must be called to synchronize the iterator with the associated region after any change has been made to the region.

Member Function: TTextRegionIterator::First

const TTextRange * First ()

Interface Category:

API.

Purpose:

Gets the first range in the associated region.

Calling Context:

When you want to get the first range in the associated region. Usually, this is when you are about to iterate over all the ranges in the associated region starting with the first range and moving forwards over the remaining ranges until you reach the end.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the first range or NIL when the region is an empty one. When NIL is not returned, you can assume that the returned range has a length greater than zero.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

You must call this function or Last before calling Next or Previous for the first time. Calling First or Last initializes the iterator for subsequent calls to Next or Previous. If the associated region changes in the middle of iterating, you must call First or Last and begin iterating sequentially from either end. Otherwise, it is not guaranteed that you will get back all the indexes currently in the associated region.

Member Function: TTextRegionIterator::Last

const TTextRange * Last ()

Interface Category:

API.

Purpose:

Gets the last range in the associated region.

Calling Context:

When you want to get the last range in the associated region. Usually, this is when you are about to iterate over all the ranges in the associated region starting with the last range and moving backwards over the remaining ranges until you reach the beginning.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the last range or NIL when the region is an empty one. When NIL is not returned, you can assume that the returned range has a length greater than zero.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

You must call this function or First before calling Next or Previous for the first time. Calling First or Last initializes the iterator for subsequent calls to Next or Previous. If the associated region changes in the middle of iterating, you must call First or Last and begin iterating sequentially from either end. Otherwise, it is not guaranteed that you will get back all the indexes currently in the associated region.

Member Function: TTextRegionIterator::Next

const TTextRange * Next ()

Interface Category:

API.

Purpose:

Gets the next range in the associated region.

Calling Context:

Usually after the initial call to First or after a previous call to Next.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the next range or NIL when there is no next range. When NIL is not returned, you can assume that the returned range has a length greater than zero.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TTextRegionIterator::Previous

const TTextRange * Previous ()

Interface Category:

API.

Purpose:

Gets the previous range in the associated region.

Calling Context:

Usually after the initial call to Last or after a previous call to Previous.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the previous range or NIL when there is no next range. When NIL is not returned, you can assume that the returned range has a length greater than zero.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TTextRegionIterator::~TTextRegionIterator

virtual ~ TTextRegionIterator ()

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.

Click the icon to mail questions or corrections about this material to Taligent personnel.