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 scan over
* the target text, returning the indices the pattern is matched
* and the length of each match.
*
* SearchIterator is an abstract base class that defines a
* protocol for text searching. Subclasses provide concrete implementations of
* various search algorithms. For example, {@link StringSearch}
* implements language-sensitive pattern matching based on the comparison rules
* defined in a {@link RuleBasedCollator} object.
*
* Internally, SearchIterator scans text using a
* {@link CharacterIterator}, and is thus able to scan text held
* by any object implementing that protocol. A StringCharacterIterator
* is used to scan String objects passed to setText.
*
* 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 occurances 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);
*
* for (int pos = iter->first(); pos != SearchIterator::DONE; pos = iter->next()) {
* printf("Found match at %d pos, length is %d\n", pos, iter.getMatchLength());
* }
* DONE if one was not.
*
* @return The character index of the first match, or DONE if there
* are no matches.
*/
int32_t first(void);
/**
* Return the first index greater than pos at which the target
* text matches the search pattern. The iterator is adjusted so that its current index
* (as returned by {@link #getIndex}) is the match posisition if one was found
* and DONE if one was not.
*
* @return The character index of the first match following pos,
* or DONE if there are no matches.
*/
int32_t following(int32_t pos);
/**
* Return the last index in the target text at which it matches
* the search pattern and adjusts the iteration to point to that position.
*
* @return The index of the first match, or DONE if there
* are no matches.
*/
int32_t last(void);
/**
* Return the first index less than pos at which the target
* text matches the search pattern. The iterator is adjusted so that its current index
* (as returned by {@link #getIndex}) is the match posisition if one was found
* and DONE if one was not.
*
* @return The character index of the first match preceding pos,
* or DONE if there are no matches.
*/
int32_t preceding(int32_t pos);
/**
* Return the index of the next point at which the text matches the
* search pattern, starting from the current position
*
* @return The index of the next match after the current position,
* or DONE if there are no more matches.
*
* @see #first
*/
int32_t next(void);
/**
* Return the index of the previous point at which the text matches
* the search pattern, starting at the current position
*
* @return The index of the previous match before the current position,
* or DONE if there are no more matches.
*/
int32_t previous(void);
/**
* 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),
* {@link #DONE} is returned.
*/
int32_t getIndex(void) const;
/**
* Determines whether overlapping matches are returned. If this
* property is true, matches that begin within the
* boundry of the previous match are considered valid and will
* be returned. For example, when searching for "abab" in the
* target text "ababab", both offsets 0 and 2 will be returned
* as valid matches if this property is true.
*
* The default setting of this property is true
*/
void setOverlapping(UBool allowOverlap);
/**
* Determines whether overlapping matches are returned.
*
* @see #setOverlapping
*/
UBool isOverlapping(void) const;
/**
* Returns the length of text in the target which matches the search
* pattern. This call returns a valid result only after a successful
* call to {@link #first}, {@link #next}, {@link #previous}, or {@link #last}.
* Just after construction, or after a searching method returns
* DONE, this method will return 0.
*
* @return The length of the match in the target text, or 0 if there
* is no match currently.
*/
int32_t getMatchLength(void) const;
/**
* Set the BreakIterator that will be used to restrict the points
* at which matches are detected.
*
* @param breaker A {@link java.text.BreakIterator 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.
*
* @see #getBreakIterator
*/
/* HSYS : Check, aliasing or owning */
void setBreakIterator(const BreakIterator* iterator);
/**
* 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.
*
* @see #setBreakIterator
*/
const BreakIterator& getBreakIterator(void) const;
/**
* Set the target text which should be searched and resets the
* iterator's position to point before the start of the target text.
* This method is useful if you want to re-use an iterator to
* search for the same pattern within a different body of text.
*
* @see #getTarget
*/
virtual void setTarget(const UnicodeString& newText);
/**
* Set the target text which should be searched and resets the
* iterator's position to point before the start of the target text.
* This method is useful if you want to re-use an iterator to
* search for the same pattern within a different body of text.
*
* @see #getTarget
*/
virtual void adoptTarget(CharacterIterator* iterator);
/**
* Return the target text which is being searched
*
* @see #setTarget
*/
const CharacterIterator& getTarget(void) const;
/** Reset the iteration.
*/
virtual void reset(void);
/**
* Returns the text that was matched by the most recent call to
* {@link #first}, {@link #next}, {@link #previous}, or {@link #last}.
* If the iterator is not pointing at a valid match (e.g. just after
* construction or after DONE has been returned, returns
* an empty string.
*/
void getMatchedText(UnicodeString& result);
//-------------------------------------------------------------------
// Protected interface for subclasses
//-------------------------------------------------------------------
protected:
SearchIterator();
/**
* Constructor for use by subclasses
*
* @param target The target text to be searched. This is for internal * use by this class. Subclasses need to maintain their * own reference to or iterator over the target text * for use by their {@link #handleNext handleNext} and * {@link #handlePrev handlePrev} methods. The target will * be adopted and owned by the SearchIterator object. * * @param breaker A {@link 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. * */ SearchIterator(CharacterIterator* target, BreakIterator* breaker); /** * 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 {@link #setMatchLength setMatchLength} * with the number of characters in the target * text that make up the match. If no match is found, the method * should return DONE and should not call setMatchLength. *
* @param startAt The index in the target text at which the search * should start. * * @see #setMatchLength */ virtual int32_t handleNext(int32_t startAt, UErrorCode& status) = 0; /** * 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 {@link #setMatchLength setMatchLength} * with the number of characters in the target * text that make up the match. If no match is found, the method * should return DONE and should not call setMatchLength. *
* @param startAt The index in the target text at which the search
* should start.
*
* @see #setMatchLength
*/
virtual int32_t handlePrev(int32_t startAt, UErrorCode& status) = 0;
/**
* Sets the length of the currently matched string in the target text.
* Subclasses' handleNext and handlePrev
* methods should call this when they find a match in the target text.
*/
void setMatchLength(int32_t length);
//-------------------------------------------------------------------
// Privates
//
private:
/**
* Class ID
*/
static char fgClassID;
private:
/**
* Private value indicating that the iterator is pointing
* before the beginning of the target text.
*/
static const int32_t BEFORE;
/**
* Internal method used by preceding and following. Sets the index
* to point to the given position, and clears any state that's
* affected.
*/
void setIndex(int32_t pos);
/**
* Determine whether the target text bounded by start and
* end is one or more whole units of text as determined by
* the current BreakIterator.
*/
UBool isBreakUnit(int32_t start, int32_t end);
//-------------------------------------------------------------------------
// Private data...
//-------------------------------------------------------------------------
int32_t index; // Current position in the target text
int32_t length; // Length of matched text, or 0
UBool overlap; // Return overlapping matches?
CharacterIterator* target; // Target text to be searched
BreakIterator* breaker; // Break iterator to constrain matches
UBool backward;
};
inline UBool SearchIterator::operator!=(const SearchIterator& that) const
{
return !operator==(that);
}
#endif