ICU 72.1 72.1
Public Member Functions | Protected Member Functions | Protected Attributes
icu::SearchIterator Class Referenceabstract

SearchIterator is an abstract base class that provides methods to search for a pattern within a text string. More...

#include <search.h>

Inheritance diagram for icu::SearchIterator:
icu::UObject icu::UMemory icu::StringSearch

Public Member Functions

 SearchIterator (const SearchIterator &other)
 Copy constructor that creates a SearchIterator instance with the same behavior, and iterating over the same text. More...
 
virtual ~SearchIterator ()
 Destructor. More...
 
virtual void setOffset (int32_t position, UErrorCode &status)=0
 Sets the index to point to the given position, and clears any state that's affected. More...
 
virtual int32_t getOffset (void) const =0
 Return the current index in the text being searched. More...
 
void setAttribute (USearchAttribute attribute, USearchAttributeValue value, UErrorCode &status)
 Sets the text searching attributes located in the enum USearchAttribute with values from the enum USearchAttributeValue. More...
 
USearchAttributeValue getAttribute (USearchAttribute attribute) const
 Gets the text searching attributes. More...
 
int32_t getMatchedStart (void) const
 Returns the index to the match in the text string that was searched. More...
 
int32_t getMatchedLength (void) const
 Returns the length of text in the string which matches the search pattern. More...
 
void getMatchedText (UnicodeString &result) const
 Returns the text that was matched by the most recent call to first, next, previous, or last. More...
 
void setBreakIterator (BreakIterator *breakiter, UErrorCode &status)
 Set the BreakIterator that will be used to restrict the points at which matches are detected. More...
 
const BreakIteratorgetBreakIterator (void) const
 Returns the BreakIterator that is used to restrict the points at which matches are detected. More...
 
virtual void setText (const UnicodeString &text, UErrorCode &status)
 Set the string text to be searched. More...
 
virtual void setText (CharacterIterator &text, UErrorCode &status)
 Set the string text to be searched. More...
 
const UnicodeStringgetText (void) const
 Return the string text to be searched. More...
 
virtual bool operator== (const SearchIterator &that) const
 Equality operator. More...
 
bool operator!= (const SearchIterator &that) const
 Not-equal operator. More...
 
virtual SearchIteratorsafeClone (void) const =0
 Returns a copy of SearchIterator with the same behavior, and iterating over the same text, as this one. More...
 
int32_t first (UErrorCode &status)
 Returns the first index at which the string text matches the search pattern. More...
 
int32_t following (int32_t position, UErrorCode &status)
 Returns the first index equal or greater than position at which the string text matches the search pattern. More...
 
int32_t last (UErrorCode &status)
 Returns the last index in the target text at which it matches the search pattern. More...
 
int32_t preceding (int32_t position, UErrorCode &status)
 Returns the first index less than position at which the string text matches the search pattern. More...
 
int32_t next (UErrorCode &status)
 Returns the index of the next point at which the text matches the search pattern, starting from the current position The iterator is adjusted so that its current index (as returned by getOffset) is the match position if one was found. More...
 
int32_t previous (UErrorCode &status)
 Returns the index of the previous point at which the string text matches the search pattern, starting at the current position. More...
 
virtual void reset ()
 Resets the iteration. More...
 
- Public Member Functions inherited from icu::UObject
virtual ~UObject ()
 Destructor. More...
 
virtual UClassID getDynamicClassID () const
 ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class. More...
 

Protected Member Functions

 SearchIterator ()
 Default constructor. More...
 
 SearchIterator (const UnicodeString &text, BreakIterator *breakiter=NULL)
 Constructor for use by subclasses. More...
 
 SearchIterator (CharacterIterator &text, BreakIterator *breakiter=NULL)
 Constructor for use by subclasses. More...
 
SearchIteratoroperator= (const SearchIterator &that)
 Assignment operator. More...
 
virtual int32_t handleNext (int32_t position, UErrorCode &status)=0
 Abstract method which subclasses override to provide the mechanism for finding the next match in the target text. More...
 
virtual int32_t handlePrev (int32_t position, UErrorCode &status)=0
 Abstract method which subclasses override to provide the mechanism for finding the previous match in the target text. More...
 
virtual void setMatchLength (int32_t length)
 Sets the length of the currently matched string in the text string to be searched. More...
 
virtual void setMatchStart (int32_t position)
 Sets the offset of the currently matched string in the text string to be searched. More...
 
void setMatchNotFound ()
 sets match not found More...
 

Protected Attributes

USearchm_search_
 C search data struct. More...
 
BreakIteratorm_breakiterator_
 Break iterator. More...
 
UnicodeString m_text_
 Unicode string version of the search text. More...
 

Detailed Description

SearchIterator is an abstract base class that provides methods to search for a pattern within a text string.

Instances of SearchIterator maintain a current position and scans over the target text, returning the indices the pattern is matched and the length of each match.

SearchIterator defines a protocol for text searching. Subclasses provide concrete implementations of various search algorithms. For example, StringSearch implements language-sensitive pattern matching based on the comparison rules defined in a RuleBasedCollator object.

Other options for searching includes using a BreakIterator to restrict the points at which matches are detected.

SearchIterator provides an API that is similar to that of other text iteration classes such as BreakIterator. Using this class, it is easy to scan through text looking for all occurrences of a given pattern. The following example uses a StringSearch object to find all instances of "fox" in the target string. Any other subclass of SearchIterator can be used in an identical manner.


UnicodeString target("The quick brown fox jumped over the lazy fox");
UnicodeString pattern("fox");

SearchIterator *iter  = new StringSearch(pattern, target);
UErrorCode      error = U_ZERO_ERROR;
for (int pos = iter->first(error); pos != USEARCH_DONE; 
                              pos = iter->next(error)) {
    printf("Found match at %d pos, length is %d\n", pos, iter.getMatchedLength());
}
See also
StringSearch
RuleBasedCollator

Definition at line 82 of file search.h.

Constructor & Destructor Documentation

◆ SearchIterator() [1/4]

icu::SearchIterator::SearchIterator ( const SearchIterator other)

Copy constructor that creates a SearchIterator instance with the same behavior, and iterating over the same text.

Parameters
otherthe SearchIterator instance to be copied.
Stable:
ICU 2.0

◆ ~SearchIterator()

virtual icu::SearchIterator::~SearchIterator ( )
virtual

Destructor.

Cleans up the search iterator data struct.

Stable:
ICU 2.0

◆ SearchIterator() [2/4]

icu::SearchIterator::SearchIterator ( )
protected

Default constructor.

Initializes data to the default values.

Stable:
ICU 2.0

◆ SearchIterator() [3/4]

icu::SearchIterator::SearchIterator ( const UnicodeString text,
BreakIterator breakiter = NULL 
)
protected

Constructor for use by subclasses.

Parameters
textThe target text to be searched.
breakiterA BreakIterator that is used to restrict the points at which matches are detected. If handleNext or handlePrev finds a match, but the match's start or end index is not a boundary as determined by the BreakIterator, the match is rejected and handleNext or handlePrev is called again. If this parameter is NULL, no break detection is attempted.
See also
handleNext
handlePrev
Stable:
ICU 2.0

◆ SearchIterator() [4/4]

icu::SearchIterator::SearchIterator ( CharacterIterator text,
BreakIterator breakiter = NULL 
)
protected

Constructor for use by subclasses.

Note: No parsing of the text within the CharacterIterator will be done during searching for this version. The block of text in CharacterIterator will be used as it is.

Parameters
textThe target text to be searched.
breakiterA BreakIterator that is used to restrict the points at which matches are detected. If handleNext or handlePrev finds a match, but the match's start or end index is not a boundary as determined by the BreakIterator, the match is rejected and handleNext or handlePrev is called again. If this parameter is NULL, no break detection is attempted.
See also
handleNext
handlePrev
Stable:
ICU 2.0

Member Function Documentation

◆ first()

int32_t icu::SearchIterator::first ( UErrorCode status)

Returns the first index at which the string text matches the search pattern.

The iterator is adjusted so that its current index (as returned by getOffset) is the match position if one was found. If a match is not found, USEARCH_DONE will be returned and the iterator will be adjusted to the index USEARCH_DONE

Parameters
statusfor errors if it occurs
Returns
The character index of the first match, or USEARCH_DONE if there are no matches.
See also
getOffset
Stable:
ICU 2.0

◆ following()

int32_t icu::SearchIterator::following ( int32_t  position,
UErrorCode status 
)

Returns the first index equal or greater than position at which the string text matches the search pattern.

The iterator is adjusted so that its current index (as returned by getOffset) is the match position if one was found. If a match is not found, USEARCH_DONE will be returned and the iterator will be adjusted to the index USEARCH_DONE.

Parameters
positionwhere search if to start from. If position is less than or greater than the text range for searching, an U_INDEX_OUTOFBOUNDS_ERROR will be returned
statusfor errors if it occurs
Returns
The character index of the first match following position, or USEARCH_DONE if there are no matches.
See also
getOffset
Stable:
ICU 2.0

◆ getAttribute()

USearchAttributeValue icu::SearchIterator::getAttribute ( USearchAttribute  attribute) const

Gets the text searching attributes.

Parameters
attributetext attribute (enum USearchAttribute) to be retrieve
Returns
text attribute value
Stable:
ICU 2.0

◆ getBreakIterator()

const BreakIterator * icu::SearchIterator::getBreakIterator ( void  ) const

Returns the BreakIterator that is used to restrict the points at which matches are detected.

This will be the same object that was passed to the constructor or to setBreakIterator. Note that NULL is a legal value; it means that break detection should not be attempted.

Returns
BreakIterator used to restrict matchings.
See also
setBreakIterator
Stable:
ICU 2.0

◆ getMatchedLength()

int32_t icu::SearchIterator::getMatchedLength ( void  ) const

Returns the length of text in the string which matches the search pattern.

This call returns a valid result only after a successful call to first, next, previous, or last. Just after construction, or after a searching method returns USEARCH_DONE, this method will return 0.

Returns
The length of the match in the target text, or 0 if there is no match currently.
See also
first
next
previous
last
Stable:
ICU 2.0

◆ getMatchedStart()

int32_t icu::SearchIterator::getMatchedStart ( void  ) const

Returns the index to the match in the text string that was searched.

This call returns a valid result only after a successful call to first, next, previous, or last. Just after construction, or after a searching method returns USEARCH_DONE, this method will return USEARCH_DONE.

Use getMatchedLength to get the matched string length.

Returns
index of a substring within the text string that is being searched.
See also
first
next
previous
last
Stable:
ICU 2.0

◆ getMatchedText()

void icu::SearchIterator::getMatchedText ( UnicodeString result) const

Returns the text that was matched by the most recent call to first, next, previous, or last.

If the iterator is not pointing at a valid match (e.g. just after construction or after USEARCH_DONE has been returned, returns an empty string.

Parameters
resultstores the matched string or an empty string if a match is not found.
See also
first
next
previous
last
Stable:
ICU 2.0

◆ getOffset()

virtual int32_t icu::SearchIterator::getOffset ( void  ) const
pure virtual

Return the current index in the text being searched.

If the iteration has gone past the end of the text (or past the beginning for a backwards search), USEARCH_DONE is returned.

Returns
current index in the text being searched.
Stable:
ICU 2.0

Implemented in icu::StringSearch.

◆ getText()

const UnicodeString & icu::SearchIterator::getText ( void  ) const

Return the string text to be searched.

Returns
text string to be searched.
Stable:
ICU 2.0

◆ handleNext()

virtual int32_t icu::SearchIterator::handleNext ( int32_t  position,
UErrorCode status 
)
protectedpure virtual

Abstract method which subclasses override to provide the mechanism for finding the next match in the target text.

This allows different subclasses to provide different search algorithms.

If a match is found, the implementation should return the index at which the match starts and should call setMatchLength with the number of characters in the target text that make up the match. If no match is found, the method should return USEARCH_DONE.

Parameters
positionThe index in the target text at which the search should start.
statusfor error codes if it occurs.
Returns
index at which the match starts, else if match is not found USEARCH_DONE is returned
See also
setMatchLength
Stable:
ICU 2.0

Implemented in icu::StringSearch.

◆ handlePrev()

virtual int32_t icu::SearchIterator::handlePrev ( int32_t  position,
UErrorCode status 
)
protectedpure virtual

Abstract method which subclasses override to provide the mechanism for finding the previous match in the target text.

This allows different subclasses to provide different search algorithms.

If a match is found, the implementation should return the index at which the match starts and should call setMatchLength with the number of characters in the target text that make up the match. If no match is found, the method should return USEARCH_DONE.

Parameters
positionThe index in the target text at which the search should start.
statusfor error codes if it occurs.
Returns
index at which the match starts, else if match is not found USEARCH_DONE is returned
See also
setMatchLength
Stable:
ICU 2.0

Implemented in icu::StringSearch.

◆ last()

int32_t icu::SearchIterator::last ( UErrorCode status)

Returns the last index in the target text at which it matches the search pattern.

The iterator is adjusted so that its current index (as returned by getOffset) is the match position if one was found. If a match is not found, USEARCH_DONE will be returned and the iterator will be adjusted to the index USEARCH_DONE.

Parameters
statusfor errors if it occurs
Returns
The index of the first match, or USEARCH_DONE if there are no matches.
See also
getOffset
Stable:
ICU 2.0

◆ next()

int32_t icu::SearchIterator::next ( UErrorCode status)

Returns the index of the next point at which the text matches the search pattern, starting from the current position The iterator is adjusted so that its current index (as returned by getOffset) is the match position if one was found.

If a match is not found, USEARCH_DONE will be returned and the iterator will be adjusted to a position after the end of the text string.

Parameters
statusfor errors if it occurs
Returns
The index of the next match after the current position, or USEARCH_DONE if there are no more matches.
See also
getOffset
Stable:
ICU 2.0

◆ operator!=()

bool icu::SearchIterator::operator!= ( const SearchIterator that) const
inline

Not-equal operator.

Parameters
thatSearchIterator instance to be compared.
Returns
false if operator== returns true, and vice versa.
Stable:
ICU 2.0

Definition at line 569 of file search.h.

References icu::operator==().

◆ operator=()

SearchIterator & icu::SearchIterator::operator= ( const SearchIterator that)
protected

Assignment operator.

Sets this iterator to have the same behavior, and iterate over the same text, as the one passed in.

Parameters
thatinstance to be copied.
Stable:
ICU 2.0

◆ operator==()

virtual bool icu::SearchIterator::operator== ( const SearchIterator that) const
virtual

Equality operator.

Parameters
thatSearchIterator instance to be compared.
Returns
true if both BreakIterators are of the same class, have the same behavior, terates over the same text and have the same attributes. false otherwise.
Stable:
ICU 2.0

Reimplemented in icu::StringSearch.

◆ preceding()

int32_t icu::SearchIterator::preceding ( int32_t  position,
UErrorCode status 
)

Returns the first index less than position at which the string text matches the search pattern.

The iterator is adjusted so that its current index (as returned by getOffset) is the match position if one was found. If a match is not found, USEARCH_DONE will be returned and the iterator will be adjusted to the index USEARCH_DONE

When USEARCH_OVERLAP option is off, the last index of the result match is always less than position. When USERARCH_OVERLAP is on, the result match may span across position.

Parameters
positionwhere search is to start from. If position is less than or greater than the text range for searching, an U_INDEX_OUTOFBOUNDS_ERROR will be returned
statusfor errors if it occurs
Returns
The character index of the first match preceding position, or USEARCH_DONE if there are no matches.
See also
getOffset
Stable:
ICU 2.0

◆ previous()

int32_t icu::SearchIterator::previous ( UErrorCode status)

Returns the index of the previous point at which the string text matches the search pattern, starting at the current position.

The iterator is adjusted so that its current index (as returned by getOffset) is the match position if one was found. If a match is not found, USEARCH_DONE will be returned and the iterator will be adjusted to the index USEARCH_DONE

Parameters
statusfor errors if it occurs
Returns
The index of the previous match before the current position, or USEARCH_DONE if there are no more matches.
See also
getOffset
Stable:
ICU 2.0

◆ reset()

virtual void icu::SearchIterator::reset ( )
virtual

Resets the iteration.

Search will begin at the start of the text string if a forward iteration is initiated before a backwards iteration. Otherwise if a backwards iteration is initiated before a forwards iteration, the search will begin at the end of the text string.

Stable:
ICU 2.0

Reimplemented in icu::StringSearch.

◆ safeClone()

virtual SearchIterator * icu::SearchIterator::safeClone ( void  ) const
pure virtual

Returns a copy of SearchIterator with the same behavior, and iterating over the same text, as this one.

Note that all data will be replicated, except for the text string to be searched.

Returns
cloned object
Stable:
ICU 2.0

Implemented in icu::StringSearch.

◆ setAttribute()

void icu::SearchIterator::setAttribute ( USearchAttribute  attribute,
USearchAttributeValue  value,
UErrorCode status 
)

Sets the text searching attributes located in the enum USearchAttribute with values from the enum USearchAttributeValue.

USEARCH_DEFAULT can be used for all attributes for resetting.

Parameters
attributetext attribute (enum USearchAttribute) to be set
valuetext attribute value
statusfor errors if it occurs
Stable:
ICU 2.0

◆ setBreakIterator()

void icu::SearchIterator::setBreakIterator ( BreakIterator breakiter,
UErrorCode status 
)

Set the BreakIterator that will be used to restrict the points at which matches are detected.

The user is responsible for deleting the breakiterator.

Parameters
breakiterA BreakIterator that will be used to restrict the points at which matches are detected. If a match is found, but the match's start or end index is not a boundary as determined by the BreakIterator, the match will be rejected and another will be searched for. If this parameter is NULL, no break detection is attempted.
statusfor errors if it occurs
See also
BreakIterator
Stable:
ICU 2.0

◆ setMatchLength()

virtual void icu::SearchIterator::setMatchLength ( int32_t  length)
protectedvirtual

Sets the length of the currently matched string in the text string to be searched.

Subclasses' handleNext and handlePrev methods should call this when they find a match in the target text.

Parameters
lengthlength of the matched text.
See also
handleNext
handlePrev
Stable:
ICU 2.0

◆ setMatchNotFound()

void icu::SearchIterator::setMatchNotFound ( )
protected

sets match not found

Stable:
ICU 2.0

◆ setMatchStart()

virtual void icu::SearchIterator::setMatchStart ( int32_t  position)
protectedvirtual

Sets the offset of the currently matched string in the text string to be searched.

Subclasses' handleNext and handlePrev methods should call this when they find a match in the target text.

Parameters
positionstart offset of the matched text.
See also
handleNext
handlePrev
Stable:
ICU 2.0

◆ setOffset()

virtual void icu::SearchIterator::setOffset ( int32_t  position,
UErrorCode status 
)
pure virtual

Sets the index to point to the given position, and clears any state that's affected.

This method takes the argument index and sets the position in the text string accordingly without checking if the index is pointing to a valid starting point to begin searching.

Parameters
positionwithin the text to be set. If position is less than or greater than the text range for searching, an U_INDEX_OUTOFBOUNDS_ERROR will be returned
statusfor errors if it occurs
Stable:
ICU 2.0

Implemented in icu::StringSearch.

◆ setText() [1/2]

virtual void icu::SearchIterator::setText ( CharacterIterator text,
UErrorCode status 
)
virtual

Set the string text to be searched.

Text iteration will hence begin at the start of the text string. This method is useful if you want to re-use an iterator to search for the same pattern within a different body of text.

Note: No parsing of the text within the CharacterIterator will be done during searching for this version. The block of text in CharacterIterator will be used as it is. The user is responsible for deleting the text.

Parameters
textstring iterator to be searched.
statusfor errors if any. If the text length is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned.
Stable:
ICU 2.0

Reimplemented in icu::StringSearch.

◆ setText() [2/2]

virtual void icu::SearchIterator::setText ( const UnicodeString text,
UErrorCode status 
)
virtual

Set the string text to be searched.

Text iteration will hence begin at the start of the text string. This method is useful if you want to re-use an iterator to search for the same pattern within a different body of text. The user is responsible for deleting the text.

Parameters
textstring to be searched.
statusfor errors. If the text length is 0, an U_ILLEGAL_ARGUMENT_ERROR is returned.
Stable:
ICU 2.0

Reimplemented in icu::StringSearch.

Field Documentation

◆ m_breakiterator_

BreakIterator* icu::SearchIterator::m_breakiterator_
protected

Break iterator.

Currently the C++ breakiterator does not have getRules etc to reproduce another in C. Hence we keep the original around and do the verification at the end of the match. The user is responsible for deleting this break iterator.

Stable:
ICU 2.0

Definition at line 428 of file search.h.

◆ m_search_

USearch* icu::SearchIterator::m_search_
protected

C search data struct.

Stable:
ICU 2.0

Definition at line 418 of file search.h.

◆ m_text_

UnicodeString icu::SearchIterator::m_text_
protected

Unicode string version of the search text.

Stable:
ICU 2.0

Definition at line 434 of file search.h.


The documentation for this class was generated from the following file: