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 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 include 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.

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
getIndex()) is the match position if one was found.

Causes the current thread to wait until another thread invokes the
notify() method or the
notifyAll() method for this object, or
some other thread interrupts the current thread, or a certain
amount of real time has elapsed.

Protected constructors

SearchIterator

Protected constructor for use by subclasses.
Initializes the iterator with the argument target text for searching
and sets the BreakIterator.
See class documentation for more details on the use of the target text
and BreakIterator.

Parameters

target

CharacterIterator: The target text to be searched.

breaker

BreakIterator: A BreakIterator that is used to determine the
boundaries of a logical match. This argument can be null.

Public methods

first

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 getIndex()) is the match position if one
was found.
If a match is not found, DONE will be returned and
the iterator will be adjusted to the index DONE.

Returns

int

The character index of the first match, or
DONE if there are no matches.

following

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 getIndex()) is the
match position if one was found.
If a match is not found, DONE will be returned and the
iterator will be adjusted to the index DONE.

Parameters

position

int: where search if to start from.

Returns

int

The character index of the first match following
position, or DONE if there are no matches.

getMatchLength

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
DONE, this method will return 0.

Returns

int

The length of the match in the target text, or 0 if there
is no match currently.

getMatchStart

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
DONE, this method will return DONE.

getMatchedText

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 DONE has been returned,
returns an empty string.

last

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 getIndex()) is the match position if one was
found.
If a match is not found, DONE will be returned and
the iterator will be adjusted to the index DONE.

next

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
getIndex()) is the match position if one was found.
If a match is not found, DONE will be returned and
the iterator will be adjusted to a position after the end of the text
string.

Returns

int

The index of the next match after the current position,
or DONE if there are no more matches.

preceding

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 getIndex()) is the match
position if one was found. If a match is not found,
DONE will be returned and the iterator will be
adjusted to the index DONE

When the overlapping option (isOverlapping()) is off, the last index of the
result match is always less than position.
When the overlapping option is on, the result match may span across
position.

Parameters

position

int: where search is to start from.

Returns

int

The character index of the first match preceding
position, or DONE if there are
no matches.

previous

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
getIndex()) is the match position if one was found.
If a match is not found, DONE will be returned and
the iterator will be adjusted to the index DONE.

Returns

int

The index of the previous match before the current position,
or DONE if there are no more matches.

reset

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.

setBreakIterator

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

Parameters

breakiter

BreakIterator: A 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.

Protected methods

handleNext

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(int) with the number of characters
in the target text that make up the match. If no match is found, the
method should return DONE.

Parameters

start

int: The index in the target text at which the search
should start.

Returns

int

index at which the match starts, else if match is not found
DONE is returned

handlePrevious

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(int) with the number of characters
in the target text that make up the match. If no match is found, the
method should return DONE.

Parameters

startAt

int: The index in the target text at which the search
should start.

Returns

int

index at which the match starts, else if match is not found
DONE is returned