Class: TTextPatternIterator

Declaration: TextComparison.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TStandardTextPatternIterator TExactTextPatternIterator TSpanTextPatternIterator

Purpose:

TTextPatternIterator is the abstract base class for all text pattern iterators. Concrete derived classes provide protocol for language-sensitive and language-insensitive pattern matching.

Instantiation:

TTextPatternIterator is an abstract class that cannot be directly instantiated.

Deriving Classes:

The system provides the following derived classes: TStandardTextPatternIterator performs language-sensitive matching, TExactTextPatternIterator performs language-insensitive matching, and TSpanTextPatternIterator performs string span functions.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TTextPatternIterator::~TTextPatternIterator

virtual ~ TTextPatternIterator ()

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: TTextPatternIterator::First

virtual TTextOffset First ()
virtual TTextOffset First (TTextRange & foundRange)

Interface Category:

API.

Purpose:

Finds the first occurrence of the text pattern within the text being iterated over. Returns the offset of the first character of the match.
Finds the first occurrence of the text pattern within the text being iterated over. Returns the offset of the first character of the match and the range defining the position of the match.

Calling Context:

Called by clients.

Parameters:

Takes no parameters.
TTextRange & foundRange -The range of the located pattern.

Return Value:

The offset of the first character of the located pattern within the text object. Returns kNotFoundOffset if the pattern is not found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextPatternIterator::Last

virtual TTextOffset Last ()
virtual TTextOffset Last (TTextRange & foundRange)

Interface Category:

API.

Purpose:

Finds the last occurrence of the text pattern within the text being iterated over. Returns the offset of the first character of the match.
Finds the last occurrence of the text pattern within the text being iterated over. Returns the offset of the first character of the match and the range defining the position of the match.

Calling Context:

Called by clients.

Parameters:

Takes no parameters.
TTextRange & foundRange -The range of the located pattern.

Return Value:

The offset of the first character of the located pattern within the text object. Returns kNotFoundOffset if the pattern is not found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextPatternIterator::Next

virtual TTextOffset Next ()
virtual TTextOffset Next (TTextRange & foundRange)

Interface Category:

API.

Purpose:

Finds the next occurrence of the text pattern within the text being iterated over. Returns the offset of the first character of the match.
Finds the next occurrence of the text pattern within the text being iterated over. Returns the offset of the first character of the match and the range defining the position of the match.

Calling Context:

Called by clients.

Parameters:

Takes no parameters.
TTextRange & foundRange -The range of the located pattern.

Return Value:

The offset of the first character of the located pattern within the text object. Returns kNotFoundOffset if the pattern is not found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

You must initialize the iterator by calling First before calling this function.

Member Function: TTextPatternIterator::Previous

virtual TTextOffset Previous ()
virtual TTextOffset Previous (TTextRange & foundRange)

Interface Category:

API.

Purpose:

Finds the previous occurrence of the text pattern within the text being iterated over. Returns the offset of the first character of the match.
Finds the previous occurrence of the text pattern within the text being iterated over. Returns the offset of the first character of the match and the range defining the position of the match.

Calling Context:

Called by clients.

Parameters:

Takes no parameters.
TTextRange & foundRange -The range of the located pattern.

Return Value:

The offset of the first character of the located pattern within the text object. Returns kNotFoundOffset if the pattern is not found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

You must initialize the iterator by calling Last before calling this function.

Member Function: TTextPatternIterator::SetPattern

virtual void SetPattern (const TText & pattern)

Interface Category:

API.

Purpose:

Specifies the pattern for the iterator to search for.

Calling Context:

Called by clients.

Parameters:

const TText & pattern -The pattern for the iterator to search for.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextPatternIterator::GetPattern

void GetPattern (TStandardText & pattern) const

Interface Category:

API.

Purpose:

Gets the pattern the iterator is searching for.

Calling Context:

Called by clients.

Parameters:

TStandardText & pattern -The pattern the iterator is searching for.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextPatternIterator::SetRange

virtual void SetRange (const TTextRange & searchRange)

Interface Category:

API.

Purpose:

Specifies the range of the text object the iterator should search through.

Calling Context:

Called by clients.

Parameters:

const TTextRange & searchRange -The range of the text object the iterator should search through.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextPatternIterator::GetRange

void GetRange (TTextRange & searchRange)

Interface Category:

API.

Purpose:

Gets the range of the text object the iterator is searching through.

Calling Context:

Called by clients.

Parameters:

TTextRange & searchRange -The range of the text object the iterator should search through.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextPatternIterator::TTextPatternIterator

TTextPatternIterator (const TText * text, const TText & pattern, const TTextRange & searchRange)
TTextPatternIterator (const TTextPatternIterator & toCopy)

Interface Category:

API.

Purpose:

Constructs an iterator for the specified text object, pattern, and range. This constructor is protected.
Copy constructor. This constructor is protected.

Calling Context:

Called to instantiate this class.
Called to copy an object.

Parameters:

const TText * text -The text to iterate through.
const TText & pattern -The pattern to search for.
const TTextRange & searchRange -The range of the text to iterate through.
const TTextPatternIterator & toCopy -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextPatternIterator::operator=

TTextPatternIterator & operator =(const TTextPatternIterator & toCopy)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TTextPatternIterator & toCopy -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:

This function is protected.

Member Function: TTextPatternIterator::FindForward

virtual bool FindForward (const TTextRange & searchRange, TTextRange & foundRange) const

Interface Category:

API.

Purpose:

Iterates forward through the text object to find the next occurrence.

Calling Context:

Called by the First and Next functions.

Parameters:

const TTextRange & searchRange -The valid range for searching.
TTextRange & foundRange -The range of the located pattern.

Return Value:

Returns true if the pattern is found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a protected pure virtual function and needs to be overridden.

Member Function: TTextPatternIterator::FindBackward

virtual bool FindBackward (const TTextRange & searchRange, TTextRange & foundRange) const

Interface Category:

API.

Purpose:

Iterates backward through the text object to find the previous occurrence.

Calling Context:

Called by the Last and Previous functions.

Parameters:

const TTextRange & searchRange -The valid range for searching.
TTextRange & foundRange -The range of the located pattern.

Return Value:

Returns true if the pattern is found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a protected pure virtual function and needs to be overridden.

Member Function: TTextPatternIterator::GetText

const TText * GetText () const

Interface Category:

API.

Purpose:

Returns the text on which a pattern search, if requested, will be performed.

Calling Context:

Called by clients.

Parameters:

Takes no parameters.

Return Value:

The text on which a pattern search, if requested, will be performed.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextPatternIterator::SetText

virtual void SetText (const TText * text, const TTextRange & searchRange)

Interface Category:

API.

Purpose:

Sets the text on which a pattern search, if requested, will be performed.

Calling Context:

Called by clients.

Parameters:

const TText * text -The text.
const TTextRange & searchRange -The search range within the text.

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.