Top Description Inners Fields Constructors Methods
com.ibm.icu.text

public abstract Class SearchIterator

extends Object
Class Inheritance
Known Direct Subclasses
com.ibm.icu.text.StringSearch
Imports
java.text.CharacterIterator
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. 


String target = "The quick brown fox jumped over the lazy fox";
String pattern = "fox";
SearchIterator iter = new StringSearch(pattern, target);
for (int pos = iter.first(); pos != SearchIterator.DONE;
        pos = iter.next()) {
    System.out.println("Found match at " + pos +
            ", length is " + iter.getMatchLength());
}
Author
Laura Werner, synwee
ICU Status
Stable since ICU 2.0.
See Also
BreakIterator, RuleBasedCollator

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
SearchIterator.ElementComparisonType

Option to control how collation elements are compared.

pack-priv class
SearchIterator.Search

Java port of ICU4C struct USearch (usrchimp.h)

Note

ICU4J already exposed some protected members such as targetText, breakIterator and matchedLength as a part of stable APIs.

Field Summary

Modifier and TypeField and Description
protected BreakIterator
breakIterator

The BreakIterator to define the boundaries of a logical match.

public static final int
DONE

DONE is returned by previous() and next() after all valid matches have been returned, and by first() and last() if there are no matches at all.

protected int
matchLength

Length of the most current match in target text.

pack-priv SearchIterator.Search
search_

protected CharacterIterator
targetText

Target text for searching.

Constructor Summary

AccessConstructor and Description
protected
SearchIterator(CharacterIterator
The target text to be searched.
target, BreakIterator
A BreakIterator that is used to determine the boundaries of a logical match. This argument can be null.
breaker)

Protected constructor for use by subclasses.

Method Summary

Modifier and TypeMethod and Description
public final int

Returns:

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

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

public final int

Returns:

The character index of the first match following position, or DONE if there are no matches.
following(int
where search if to start from.
position)

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

public BreakIterator

Returns:

the BreakIterator set to restrict logic matches
getBreakIterator()

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

public SearchIterator.ElementComparisonType
getElementComparisonType()

Returns the collation element comparison type.

public abstract int

Returns:

current index in the text being searched.
getIndex()

Return the current index in the text being searched.

public String

Returns:

the substring in the target test of the most recent match, or null if there is no match currently.
getMatchedText()

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

public int

Returns:

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

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

public int

Returns:

index of a substring within the text string that is being searched.
getMatchStart()

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

public CharacterIterator

Returns:

text string to be searched.
getTarget()

Return the string text to be searched.

protected abstract int

Returns:

index at which the match starts, else if match is not found DONE is returned
handleNext(int
The index in the target text at which the search should start.
start)

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

protected abstract int

Returns:

index at which the match starts, else if match is not found DONE is returned
handlePrevious(int
The index in the target text at which the search should start.
startAt)

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

public boolean

Returns:

true if the overlapping property has been set, false otherwise
isOverlapping()

Return true if the overlapping property has been set.

public final int

Returns:

The index of the first match, or DONE if there are no matches.
last()

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

public int

Returns:

The index of the next match after the current position, or DONE if there are no more matches.
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.

public final int

Returns:

The character index of the first match preceding position, or DONE if there are no matches.
preceding(int
where search is to start from.
position)

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

public int

Returns:

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

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

public void
reset()

Resets the iteration.

public void
setBreakIterator(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.
breakiter)

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

public void
setElementComparisonType(SearchIterator.ElementComparisonType type)

Sets the collation element comparison type.

public void
setIndex(int
position from which to start the next search
position)

Sets the position in the target text at which the next search will start.

protected void
setMatchLength(int
new length to set
length)

Sets the length of the most recent match in the target text.

protected void
setMatchNotFound()

Deprecated This API is ICU internal only.
public void
setOverlapping(boolean
flag indicator if overlapping matches are allowed
allowOverlap)

Determines whether overlapping matches are returned.

public void
setTarget(CharacterIterator
new text iterator to look for match,
text)

Set the target text to be searched.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

breakIteratorback to summary
protected BreakIterator breakIterator

The BreakIterator to define the boundaries of a logical match. This value can be a null. See class documentation for more information.

ICU Status
Stable since ICU 2.0.
See Also
setBreakIterator(BreakIterator), getBreakIterator, BreakIterator
DONEback to summary
public static final int DONE

DONE is returned by previous() and next() after all valid matches have been returned, and by first() and last() if there are no matches at all.

ICU Status
Stable since ICU 2.0.
See Also
previous, next
matchLengthback to summary
protected int matchLength

Length of the most current match in target text. Value 0 is the default value.

ICU Status
Stable since ICU 2.0.
See Also
setMatchLength, getMatchLength
search_back to summary
pack-priv SearchIterator.Search search_
targetTextback to summary
protected CharacterIterator targetText

Target text for searching.

ICU Status
Stable since ICU 2.0.
See Also
setTarget(CharacterIterator), getTarget

Constructor Detail

SearchIteratorback to summary
protected SearchIterator(CharacterIterator target, BreakIterator breaker)

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.

Exceptions
IllegalArgumentException:
thrown when argument target is null, or of length 0
ICU Status
Stable since ICU 2.0.
See Also
BreakIterator

Method Detail

firstback to summary
public final int 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.

ICU Status
Stable since ICU 2.0.
See Also
getIndex
followingback to summary
public final int following(int position)

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.

Exceptions
IndexOutOfBoundsException:
If position is less than or greater than the text range for searching.
ICU Status
Stable since ICU 2.0.
See Also
getIndex
getBreakIteratorback to summary
public BreakIterator getBreakIterator()

Returns the BreakIterator that is used to restrict the indexes at which matches are detected. This will be the same object that was passed to the constructor or to setBreakIterator. If the BreakIterator has not been set, null will be returned. See setBreakIterator for more information.

Returns:BreakIterator

the BreakIterator set to restrict logic matches

ICU Status
Stable since ICU 2.0.
See Also
setBreakIterator, BreakIterator
getElementComparisonTypeback to summary
public SearchIterator.ElementComparisonType getElementComparisonType()

Returns the collation element comparison type.

ICU Status
Stable since ICU 53.
See Also
ElementComparisonType, setElementComparisonType(ElementComparisonType)
getIndexback to summary
public abstract int getIndex()

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), DONE is returned.

Returns:int

current index in the text being searched.

ICU Status
Stable since ICU 2.8.
getMatchedTextback to summary
public String 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.

Returns:String

the substring in the target test of the most recent match, or null if there is no match currently.

ICU Status
Stable since ICU 2.0.
See Also
first, next, previous, last
getMatchLengthback to summary
public int 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.

ICU Status
Stable since ICU 2.0.
See Also
first, next, previous, last
getMatchStartback to summary
public int 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.

Use getMatchLength to get the matched string length.

Returns:int

index of a substring within the text string that is being searched.

ICU Status
Stable since ICU 2.0.
See Also
first, next, previous, last
getTargetback to summary
public CharacterIterator getTarget()

Return the string text to be searched.

Returns:CharacterIterator

text string to be searched.

ICU Status
Stable since ICU 2.0.
handleNextback to summary
protected abstract int handleNext(int start)

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

ICU Status
Stable since ICU 2.0.
See Also
setMatchLength
handlePreviousback to summary
protected abstract int handlePrevious(int startAt)

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

ICU Status
Stable since ICU 2.0.
See Also
setMatchLength
isOverlappingback to summary
public boolean isOverlapping()

Return true if the overlapping property has been set. See setOverlapping(boolean) for more information.

Returns:boolean

true if the overlapping property has been set, false otherwise

ICU Status
Stable since ICU 2.8.
See Also
setOverlapping
lastback to summary
public final int 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.

Returns:int

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

ICU Status
Stable since ICU 2.0.
See Also
getIndex
nextback to summary
public int 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.

ICU Status
Stable since ICU 2.0.
See Also
getIndex
precedingback to summary
public final int preceding(int position)

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.

Exceptions
IndexOutOfBoundsException:
If position is less than or greater than the text range for searching
ICU Status
Stable since ICU 2.0.
See Also
getIndex
previousback to summary
public int 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.

ICU Status
Stable since ICU 2.0.
See Also
getIndex
resetback to summary
public void 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.

ICU Status
Stable since ICU 2.0.
setBreakIteratorback to summary
public void setBreakIterator(BreakIterator breakiter)

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.

ICU Status
Stable since ICU 2.0.
See Also
BreakIterator
setElementComparisonTypeback to summary
public void setElementComparisonType(SearchIterator.ElementComparisonType type)

Sets the collation element comparison type.

The default comparison type is ElementComparisonType#STANDARD_ELEMENT_COMPARISON.

ICU Status
Stable since ICU 53.
See Also
ElementComparisonType, getElementComparisonType()
setIndexback to summary
public void setIndex(int position)

Sets the position in the target text at which the next search will start. This method clears any previous match.

Parameters
position:int

position from which to start the next search

Exceptions
IndexOutOfBoundsException:
thrown if argument position is out of the target text range.
ICU Status
Stable since ICU 2.8.
See Also
getIndex
setMatchLengthback to summary
protected void setMatchLength(int length)

Sets the length of the most recent match in the target text. Subclasses' handleNext() and handlePrevious() methods should call this after they find a match in the target text.

Parameters
length:int

new length to set

ICU Status
Stable since ICU 2.0.
See Also
handleNext, handlePrevious
setMatchNotFoundback to summary
protected void setMatchNotFound()

Deprecated

This API is ICU internal only.

Annotations
@Deprecated
ICU Status
Internal ICU component.
setOverlappingback to summary
public void setOverlapping(boolean allowOverlap)

Determines whether overlapping matches are returned. See the class documentation for more information about overlapping matches.

The default setting of this property is false

Parameters
allowOverlap:boolean

flag indicator if overlapping matches are allowed

ICU Status
Stable since ICU 2.8.
See Also
isOverlapping
setTargetback to summary
public void setTarget(CharacterIterator text)

Set the target text to be searched. Text iteration will then begin at the start of the text string. This method is useful if you want to reuse an iterator to search within a different body of text.

Parameters
text:CharacterIterator

new text iterator to look for match,

Exceptions
IllegalArgumentException:
thrown when text is null or has 0 length
ICU Status
Stable since ICU 2.4.
See Also
getTarget
com.ibm.icu.text back to summary

public final Enum SearchIterator.ElementComparisonType

extends Enum<SearchIterator.ElementComparisonType>
Class Inheritance
Option to control how collation elements are compared. The default value will be STANDARD_ELEMENT_COMPARISON.

PATTERN_BASE_WEIGHT_IS_WILDCARD supports "asymmetric search" as described in UTS #10 Unicode Collation Algorithm, while ANY_BASE_WEIGHT_IS_WILDCARD supports a related option in which "unmarked" characters in either the pattern or the searched text are treated as wildcards that match marked or unmarked versions of the same character.

ICU Status
Stable since ICU 53.
See Also
setElementComparisonType(ElementComparisonType), getElementComparisonType()

Field Summary

Modifier and TypeField and Description
public static final SearchIterator.ElementComparisonType
ANY_BASE_WEIGHT_IS_WILDCARD

Collation element comparison is modified to effectively provide behavior between the specified strength and strength - 1.

public static final SearchIterator.ElementComparisonType
PATTERN_BASE_WEIGHT_IS_WILDCARD

Collation element comparison is modified to effectively provide behavior between the specified strength and strength - 1.

public static final SearchIterator.ElementComparisonType
STANDARD_ELEMENT_COMPARISON

Standard collation element comparison at the specified collator strength.

Constructor Summary

AccessConstructor and Description
private
ElementComparisonType()

Method Summary

Modifier and TypeMethod and Description
public static SearchIterator.ElementComparisonType
valueOf(String name)

public static SearchIterator.ElementComparisonType[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

ANY_BASE_WEIGHT_IS_WILDCARDback to summary
public static final SearchIterator.ElementComparisonType ANY_BASE_WEIGHT_IS_WILDCARD

Collation element comparison is modified to effectively provide behavior between the specified strength and strength - 1.

Collation elements in either the pattern or the searched text that have the base weight for the specified strength are treated as "wildcards" that match an element with any other weight at that collation level. For example, with a secondary-strength English collator, a plain 'e' in the pattern will match a plain e or an e with any diacritic in the searched text, but an e with diacritic in the pattern will only match an e with the same diacritic or a plain e in the searched text.

ICU Status
Stable since ICU 53.
PATTERN_BASE_WEIGHT_IS_WILDCARDback to summary
public static final SearchIterator.ElementComparisonType PATTERN_BASE_WEIGHT_IS_WILDCARD

Collation element comparison is modified to effectively provide behavior between the specified strength and strength - 1.

Collation elements in the pattern that have the base weight for the specified strength are treated as "wildcards" that match an element with any other weight at that collation level in the searched text. For example, with a secondary-strength English collator, a plain 'e' in the pattern will match a plain e or an e with any diacritic in the searched text, but an e with diacritic in the pattern will only match an e with the same diacritic in the searched text.

ICU Status
Stable since ICU 53.
STANDARD_ELEMENT_COMPARISONback to summary
public static final SearchIterator.ElementComparisonType STANDARD_ELEMENT_COMPARISON

Standard collation element comparison at the specified collator strength.

ICU Status
Stable since ICU 53.

Constructor Detail

ElementComparisonTypeback to summary
private ElementComparisonType()

Method Detail

valueOfback to summary
public static SearchIterator.ElementComparisonType valueOf(String name)
valuesback to summary
public static SearchIterator.ElementComparisonType[] values()