Added in API level 24

SearchIterator

abstract class SearchIterator
kotlin.Any
   ↳ android.icu.text.SearchIterator

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.

<code>
  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());
  }
  </code>

Summary

Nested classes

Option to control how collation elements are compared.

Constants
static Int

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 constructors

Protected constructor for use by subclasses.

Public methods
Int

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

Int
following(position: Int)

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

open BreakIterator!

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

open SearchIterator.ElementComparisonType!

Returns the collation element comparison type.

abstract Int

Return the current index in the text being searched.

open Int

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

open Int

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

open String!

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

open CharacterIterator!

Return the string text to be searched.

open Boolean

Return true if the overlapping property has been set.

Int

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

open Int

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.

Int
preceding(position: Int)

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

open Int

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

open Unit

Resets the iteration.

open Unit

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

open Unit

Sets the collation element comparison type.

open Unit
setIndex(position: Int)

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

open Unit
setOverlapping(allowOverlap: Boolean)

Determines whether overlapping matches are returned.

open Unit

Set the target text to be searched.

Protected methods
abstract Int
handleNext(start: Int)

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

abstract Int
handlePrevious(startAt: Int)

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

open Unit

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

Properties
BreakIterator!

The BreakIterator to define the boundaries of a logical match.

Int

Length of the most current match in target text.

CharacterIterator!

Target text for searching.

Constants

DONE

Added in API level 24
static val DONE: Int

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.

Value: -1

See Also

Protected constructors

SearchIterator

Added in API level 24
protected SearchIterator(
    target: CharacterIterator!,
    breaker: BreakIterator!)

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
java.lang.IllegalArgumentException thrown when argument target is null, or of length 0

Public methods

first

Added in API level 24
fun first(): Int

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.

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

See Also

following

Added in API level 24
fun following(position: Int): Int

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.
Return
Int The character index of the first match following position, or DONE if there are no matches.
Exceptions
java.lang.IndexOutOfBoundsException If position is less than or greater than the text range for searching.

See Also

getBreakIterator

Added in API level 24
open fun getBreakIterator(): BreakIterator!

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.

Return
BreakIterator! the BreakIterator set to restrict logic matches

getElementComparisonType

Added in API level 24
open fun getElementComparisonType(): SearchIterator.ElementComparisonType!

Returns the collation element comparison type.

getIndex

Added in API level 24
abstract fun getIndex(): Int

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.

Return
Int current index in the text being searched.

getMatchLength

Added in API level 24
open fun getMatchLength(): Int

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.

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

getMatchStart

Added in API level 24
open fun getMatchStart(): Int

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.

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

getMatchedText

Added in API level 24
open fun getMatchedText(): String!

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.

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

getTarget

Added in API level 24
open fun getTarget(): CharacterIterator!

Return the string text to be searched.

Return
CharacterIterator! text string to be searched.

isOverlapping

Added in API level 24
open fun isOverlapping(): Boolean

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

Return
Boolean true if the overlapping property has been set, false otherwise

See Also

last

Added in API level 24
fun last(): Int

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.

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

See Also

next

Added in API level 24
open fun next(): Int

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.

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

See Also

preceding

Added in API level 24
fun preceding(position: Int): Int

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.
Return
Int The character index of the first match preceding position, or DONE if there are no matches.
Exceptions
java.lang.IndexOutOfBoundsException If position is less than or greater than the text range for searching

See Also

previous

Added in API level 24
open fun previous(): Int

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.

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

See Also

reset

Added in API level 24
open fun reset(): Unit

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

Added in API level 24
open fun setBreakIterator(breakiter: BreakIterator!): Unit

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.

setElementComparisonType

Added in API level 24
open fun setElementComparisonType(type: SearchIterator.ElementComparisonType!): Unit

Sets the collation element comparison type.

The default comparison type is ElementComparisonType#STANDARD_ELEMENT_COMPARISON.

setIndex

Added in API level 24
open fun setIndex(position: Int): Unit

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
java.lang.IndexOutOfBoundsException thrown if argument position is out of the target text range.

See Also

setOverlapping

Added in API level 24
open fun setOverlapping(allowOverlap: Boolean): Unit

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

See Also

setTarget

Added in API level 24
open fun setTarget(text: CharacterIterator!): Unit

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
java.lang.IllegalArgumentException thrown when text is null or has 0 length

See Also

Protected methods

handleNext

Added in API level 24
protected abstract fun handleNext(start: Int): Int

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.
Return
Int index at which the match starts, else if match is not found DONE is returned

See Also

handlePrevious

Added in API level 24
protected abstract fun handlePrevious(startAt: Int): Int

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.
Return
Int index at which the match starts, else if match is not found DONE is returned

See Also

setMatchLength

Added in API level 24
protected open fun setMatchLength(length: Int): Unit

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

Properties

breakIterator

Added in API level 24
protected var breakIterator: BreakIterator!

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

matchLength

Added in API level 24
protected var matchLength: Int

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

targetText

Added in API level 24
protected var targetText: CharacterIterator!

Target text for searching.