# SearchIterator

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  
Summary:[Constants](https://developer.android.com/reference/android/icu/text/SearchIterator#constants)\|[Fields](https://developer.android.com/reference/android/icu/text/SearchIterator#lfields)\|[Protected Ctors](https://developer.android.com/reference/android/icu/text/SearchIterator#proctors)\|[Methods](https://developer.android.com/reference/android/icu/text/SearchIterator#pubmethods)\|[Protected Methods](https://developer.android.com/reference/android/icu/text/SearchIterator#promethods)\|[Inherited Methods](https://developer.android.com/reference/android/icu/text/SearchIterator#inhmethods)  

# SearchIterator

*** ** * ** ***

[Kotlin](https://developer.android.com/reference/kotlin/android/icu/text/SearchIterator "View this page in Kotlin")\|Java

`
public


abstract
class
SearchIterator
`  
`

extends `[Object](https://developer.android.com/reference/java/lang/Object)`


``


`

|---|---------------------------------|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.icu.text.SearchIterator |

|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Known direct subclasses [StringSearch](https://developer.android.com/reference/android/icu/text/StringSearch) |---------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [StringSearch](https://developer.android.com/reference/android/icu/text/StringSearch) | StringSearchis a[SearchIterator](https://developer.android.com/reference/android/icu/text/SearchIterator)that provides language-sensitive text searching based on the comparison rules defined in a[RuleBasedCollator](https://developer.android.com/reference/android/icu/text/RuleBasedCollator)object. | |

<br />

*** ** * ** ***

SearchIteratoris an abstract base class that provides methods to search for a pattern within a text string. Instances ofSearchIteratormaintain a current position and scan over the target text, returning the indices the pattern is matched and the length of each match.

SearchIteratordefines a protocol for text searching. Subclasses provide concrete implementations of various search algorithms. For example,StringSearchimplements language-sensitive pattern matching based on the comparison rules defined in aRuleBasedCollatorobject.

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

SearchIteratorprovides an API that is similar to that of other text iteration classes such asBreakIterator. Using this class, it is easy to scan through text looking for all occurrences of a given pattern. The following example uses aStringSearchobject to find all instances of "fox" in the target string. Any other subclass ofSearchIteratorcan 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());
     }
     
<br />

**See also:**

- [BreakIterator](https://developer.android.com/reference/android/icu/text/BreakIterator)
- [RuleBasedCollator](https://developer.android.com/reference/android/icu/text/RuleBasedCollator)

## Summary

|                                                                                                                ### Constants                                                                                                                ||
|-------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `int` | [DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#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. |

|                                                                                                                                  ### Fields                                                                                                                                  ||
|-------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ` protected `[BreakIterator](https://developer.android.com/reference/android/icu/text/BreakIterator)  | [breakIterator](https://developer.android.com/reference/android/icu/text/SearchIterator#breakIterator) The BreakIterator to define the boundaries of a logical match. |
| ` protected int`                                                                                      | [matchLength](https://developer.android.com/reference/android/icu/text/SearchIterator#matchLength) Length of the most current match in target text.                   |
| ` protected `[CharacterIterator](https://developer.android.com/reference/java/text/CharacterIterator) | [targetText](https://developer.android.com/reference/android/icu/text/SearchIterator#targetText) Target text for searching.                                           |

|                                                                                                                                                                                                     ### Protected constructors                                                                                                                                                                                                      ||
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|
| ` `[SearchIterator](https://developer.android.com/reference/android/icu/text/SearchIterator#SearchIterator(java.text.CharacterIterator,%20android.icu.text.BreakIterator))`(`[CharacterIterator](https://developer.android.com/reference/java/text/CharacterIterator)` target, `[BreakIterator](https://developer.android.com/reference/android/icu/text/BreakIterator)` breaker) ` Protected constructor for use by subclasses. |

|                                                                                                                                                                                                                                                                                                                                             ### Public methods                                                                                                                                                                                                                                                                                                                                             ||
|------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ` final int`                                                                                                                             | ` `[first](https://developer.android.com/reference/android/icu/text/SearchIterator#first())`() ` Returns the first index at which the string text matches the search pattern.                                                                                                                                                                                                                                                                                                                                                                                    |
| ` final int`                                                                                                                             | ` `[following](https://developer.android.com/reference/android/icu/text/SearchIterator#following(int))`(int position) ` Returns the first index equal or greater thanpositionat which the string text matches the search pattern.                                                                                                                                                                                                                                                                                                                                |
| ` `[BreakIterator](https://developer.android.com/reference/android/icu/text/BreakIterator)                                               | ` `[getBreakIterator](https://developer.android.com/reference/android/icu/text/SearchIterator#getBreakIterator())`() ` Returns the BreakIterator that is used to restrict the indexes at which matches are detected.                                                                                                                                                                                                                                                                                                                                             |
| ` `[SearchIterator.ElementComparisonType](https://developer.android.com/reference/android/icu/text/SearchIterator.ElementComparisonType) | ` `[getElementComparisonType](https://developer.android.com/reference/android/icu/text/SearchIterator#getElementComparisonType())`() ` Returns the collation element comparison type.                                                                                                                                                                                                                                                                                                                                                                            |
| ` abstract int`                                                                                                                          | ` `[getIndex](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())`() ` Return the current index in the text being searched.                                                                                                                                                                                                                                                                                                                                                                                                      |
| ` int`                                                                                                                                   | ` `[getMatchLength](https://developer.android.com/reference/android/icu/text/SearchIterator#getMatchLength())`() ` Returns the length of text in the string which matches the search pattern.                                                                                                                                                                                                                                                                                                                                                                    |
| ` int`                                                                                                                                   | ` `[getMatchStart](https://developer.android.com/reference/android/icu/text/SearchIterator#getMatchStart())`() ` Returns the index to the match in the text string that was searched.                                                                                                                                                                                                                                                                                                                                                                            |
| ` `[String](https://developer.android.com/reference/java/lang/String)                                                                    | ` `[getMatchedText](https://developer.android.com/reference/android/icu/text/SearchIterator#getMatchedText())`() ` Returns the text that was matched by the most recent call to[first()](https://developer.android.com/reference/android/icu/text/SearchIterator#first()),[next()](https://developer.android.com/reference/android/icu/text/SearchIterator#next()),[previous()](https://developer.android.com/reference/android/icu/text/SearchIterator#previous()), or[last()](https://developer.android.com/reference/android/icu/text/SearchIterator#last()). |
| ` `[CharacterIterator](https://developer.android.com/reference/java/text/CharacterIterator)                                              | ` `[getTarget](https://developer.android.com/reference/android/icu/text/SearchIterator#getTarget())`() ` Return the string text to be searched.                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ` boolean`                                                                                                                               | ` `[isOverlapping](https://developer.android.com/reference/android/icu/text/SearchIterator#isOverlapping())`() ` Return true if the overlapping property has been set.                                                                                                                                                                                                                                                                                                                                                                                           |
| ` final int`                                                                                                                             | ` `[last](https://developer.android.com/reference/android/icu/text/SearchIterator#last())`() ` Returns the last index in the target text at which it matches the search pattern.                                                                                                                                                                                                                                                                                                                                                                                 |
| ` int`                                                                                                                                   | ` `[next](https://developer.android.com/reference/android/icu/text/SearchIterator#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()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())) is the match position if one was found.                                                                                                                                  |
| ` final int`                                                                                                                             | ` `[preceding](https://developer.android.com/reference/android/icu/text/SearchIterator#preceding(int))`(int position) ` Returns the first index less thanpositionat which the string text matches the search pattern.                                                                                                                                                                                                                                                                                                                                            |
| ` int`                                                                                                                                   | ` `[previous](https://developer.android.com/reference/android/icu/text/SearchIterator#previous())`() ` Returns the index of the previous point at which the string text matches the search pattern, starting at the current position.                                                                                                                                                                                                                                                                                                                            |
| ` void`                                                                                                                                  | ` `[reset](https://developer.android.com/reference/android/icu/text/SearchIterator#reset())`() ` Resets the iteration.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ` void`                                                                                                                                  | ` `[setBreakIterator](https://developer.android.com/reference/android/icu/text/SearchIterator#setBreakIterator(android.icu.text.BreakIterator))`(`[BreakIterator](https://developer.android.com/reference/android/icu/text/BreakIterator)` breakiter) ` Set the BreakIterator that will be used to restrict the points at which matches are detected.                                                                                                                                                                                                            |
| ` void`                                                                                                                                  | ` `[setElementComparisonType](https://developer.android.com/reference/android/icu/text/SearchIterator#setElementComparisonType(android.icu.text.SearchIterator.ElementComparisonType))`(`[SearchIterator.ElementComparisonType](https://developer.android.com/reference/android/icu/text/SearchIterator.ElementComparisonType)` type) ` Sets the collation element comparison type.                                                                                                                                                                              |
| ` void`                                                                                                                                  | ` `[setIndex](https://developer.android.com/reference/android/icu/text/SearchIterator#setIndex(int))`(int position) ` <br /> Sets the position in the target text at which the next search will start.                                                                                                                                                                                                                                                                                                                                                           |
| ` void`                                                                                                                                  | ` `[setOverlapping](https://developer.android.com/reference/android/icu/text/SearchIterator#setOverlapping(boolean))`(boolean allowOverlap) ` Determines whether overlapping matches are returned.                                                                                                                                                                                                                                                                                                                                                               |
| ` void`                                                                                                                                  | ` `[setTarget](https://developer.android.com/reference/android/icu/text/SearchIterator#setTarget(java.text.CharacterIterator))`(`[CharacterIterator](https://developer.android.com/reference/java/text/CharacterIterator)` text) ` Set the target text to be searched.                                                                                                                                                                                                                                                                                           |

|                                                                                                                          ### Protected methods                                                                                                                          ||
|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ` abstract int` | ` `[handleNext](https://developer.android.com/reference/android/icu/text/SearchIterator#handleNext(int))`(int start) ` Abstract method which subclasses override to provide the mechanism for finding the next match in the target text.               |
| ` abstract int` | ` `[handlePrevious](https://developer.android.com/reference/android/icu/text/SearchIterator#handlePrevious(int))`(int startAt) ` Abstract method which subclasses override to provide the mechanism for finding the previous match in the target text. |
| ` void`         | ` `[setMatchLength](https://developer.android.com/reference/android/icu/text/SearchIterator#setMatchLength(int))`(int length) ` Sets the length of the most recent match in the target text.                                                           |

| ### Inherited methods |
|-----------------------|---|
| From class` `[java.lang.Object](https://developer.android.com/reference/java/lang/Object)` ` |--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ` `[Object](https://developer.android.com/reference/java/lang/Object)          | ` `[clone](https://developer.android.com/reference/java/lang/Object#clone())`() ` Creates and returns a copy of this object.                                                                                                                                                      | | ` boolean`                                                                     | ` `[equals](https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object))`(`[Object](https://developer.android.com/reference/java/lang/Object)` obj) ` Indicates whether some other object is "equal to" this one.                                           | | ` void`                                                                        | ` `[finalize](https://developer.android.com/reference/java/lang/Object#finalize())`() ` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.                                                          | | ` final `[Class](https://developer.android.com/reference/java/lang/Class)`<?>` | ` `[getClass](https://developer.android.com/reference/java/lang/Object#getClass())`() ` Returns the runtime class of this`Object`.                                                                                                                                                | | ` int`                                                                         | ` `[hashCode](https://developer.android.com/reference/java/lang/Object#hashCode())`() ` Returns a hash code value for the object.                                                                                                                                                 | | ` final void`                                                                  | ` `[notify](https://developer.android.com/reference/java/lang/Object#notify())`() ` Wakes up a single thread that is waiting on this object's monitor.                                                                                                                            | | ` final void`                                                                  | ` `[notifyAll](https://developer.android.com/reference/java/lang/Object#notifyAll())`() ` Wakes up all threads that are waiting on this object's monitor.                                                                                                                         | | ` `[String](https://developer.android.com/reference/java/lang/String)          | ` `[toString](https://developer.android.com/reference/java/lang/Object#toString())`() ` Returns a string representation of the object.                                                                                                                                            | | ` final void`                                                                  | ` `[wait](https://developer.android.com/reference/java/lang/Object#wait(long,%20int))`(long timeoutMillis, int nanos) ` Causes the current thread to wait until it is awakened, typically by being*notified* or*interrupted*, or until a certain amount of real time has elapsed. | | ` final void`                                                                  | ` `[wait](https://developer.android.com/reference/java/lang/Object#wait(long))`(long timeoutMillis) ` Causes the current thread to wait until it is awakened, typically by being*notified* or*interrupted*, or until a certain amount of real time has elapsed.                   | | ` final void`                                                                  | ` `[wait](https://developer.android.com/reference/java/lang/Object#wait())`() ` Causes the current thread to wait until it is awakened, typically by being*notified* or*interrupted*.                                                                                             | ||

## Constants

### DONE

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

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

<br />

**See also:**

- [previous()](https://developer.android.com/reference/android/icu/text/SearchIterator#previous())
- [next()](https://developer.android.com/reference/android/icu/text/SearchIterator#next())

Constant Value: -1 (0xffffffff)

## Fields

### breakIterator

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

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

<br />

**See also:**

- [setBreakIterator(BreakIterator)](https://developer.android.com/reference/android/icu/text/SearchIterator#setBreakIterator(android.icu.text.BreakIterator))
- [getBreakIterator()](https://developer.android.com/reference/android/icu/text/SearchIterator#getBreakIterator())
- [BreakIterator](https://developer.android.com/reference/android/icu/text/BreakIterator)  

### matchLength

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
protected int matchLength
```

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

<br />

**See also:**

- [setMatchLength(int)](https://developer.android.com/reference/android/icu/text/SearchIterator#setMatchLength(int))
- [getMatchLength()](https://developer.android.com/reference/android/icu/text/SearchIterator#getMatchLength())  

### targetText

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
protected CharacterIterator targetText
```

Target text for searching.

<br />

**See also:**

- [setTarget(CharacterIterator)](https://developer.android.com/reference/android/icu/text/SearchIterator#setTarget(java.text.CharacterIterator))
- [getTarget()](https://developer.android.com/reference/android/icu/text/SearchIterator#getTarget())

## Protected constructors

### SearchIterator

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
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](https://developer.android.com/reference/android/icu/text/BreakIterator).

<br />

|                                                                                                     Parameters                                                                                                     ||
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `target`  | `CharacterIterator`: The target text to be searched. <br />                                                                                                                                             |
| `breaker` | `BreakIterator`: A[BreakIterator](https://developer.android.com/reference/android/icu/text/BreakIterator)that is used to determine the boundaries of a logical match. This argument can be null. <br /> |

|                                                                           Throws                                                                            ||
|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| [IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException) | thrown when argument target is null, or of length 0 |

**See also:**

- [BreakIterator](https://developer.android.com/reference/android/icu/text/BreakIterator)

## Public methods

### first

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
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()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())) is the match position if one was found. If a match is not found,[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)will be returned and the iterator will be adjusted to the index[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE).

<br />

|                                                                               Returns                                                                                ||
|-------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `int` | The character index of the first match, or[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)if there are no matches. <br /> |

**See also:**

- [getIndex()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())  

### following

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public final int following (int position)
```

Returns the first index equal or greater thanpositionat which the string text matches the search pattern. The iterator is adjusted so that its current index (as returned by[getIndex()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())) is the match position if one was found. If a match is not found,[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)will be returned and the iterator will be adjusted to the index[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE).

<br />

|                        Parameters                        ||
|------------|----------------------------------------------|
| `position` | `int`: where search if to start from. <br /> |

|                                                                                        Returns                                                                                         ||
|-------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `int` | The character index of the first match followingposition, or[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)if there are no matches. <br /> |

|                                                                                      Throws                                                                                      ||
|----------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| [IndexOutOfBoundsException](https://developer.android.com/reference/java/lang/IndexOutOfBoundsException) | If position is less than or greater than the text range for searching. |

**See also:**

- [getIndex()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())  

### getBreakIterator

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
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(BreakIterator)](https://developer.android.com/reference/android/icu/text/SearchIterator#setBreakIterator(android.icu.text.BreakIterator)). If the[BreakIterator](https://developer.android.com/reference/android/icu/text/BreakIterator)has not been set,nullwill be returned. See[setBreakIterator(BreakIterator)](https://developer.android.com/reference/android/icu/text/SearchIterator#setBreakIterator(android.icu.text.BreakIterator))for more information.

<br />

|                                                                     Returns                                                                     ||
|-----------------------------------------------------------------------------------------|--------------------------------------------------------|
| [BreakIterator](https://developer.android.com/reference/android/icu/text/BreakIterator) | the BreakIterator set to restrict logic matches <br /> |

**See also:**

- [setBreakIterator(BreakIterator)](https://developer.android.com/reference/android/icu/text/SearchIterator#setBreakIterator(android.icu.text.BreakIterator))
- [BreakIterator](https://developer.android.com/reference/android/icu/text/BreakIterator)  

### getElementComparisonType

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public SearchIterator.ElementComparisonType getElementComparisonType ()
```

Returns the collation element comparison type.

<br />

|                                                                    Returns                                                                    ||
|---------------------------------------------------------------------------------------------------------------------------------------|--------|
| [SearchIterator.ElementComparisonType](https://developer.android.com/reference/android/icu/text/SearchIterator.ElementComparisonType) | <br /> |

**See also:**

- [SearchIterator.ElementComparisonType](https://developer.android.com/reference/android/icu/text/SearchIterator.ElementComparisonType)
- [setElementComparisonType(ElementComparisonType)](https://developer.android.com/reference/android/icu/text/SearchIterator#setElementComparisonType(android.icu.text.SearchIterator.ElementComparisonType))  

### getIndex

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
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](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)is returned.

<br />

|                         Returns                         ||
|-------|--------------------------------------------------|
| `int` | current index in the text being searched. <br /> |

### getMatchLength

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
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()](https://developer.android.com/reference/android/icu/text/SearchIterator#first()),[next()](https://developer.android.com/reference/android/icu/text/SearchIterator#next()),[previous()](https://developer.android.com/reference/android/icu/text/SearchIterator#previous()), or[last()](https://developer.android.com/reference/android/icu/text/SearchIterator#last()). Just after construction, or after a searching method returns[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE), this method will return 0.

<br />

|                                            Returns                                             ||
|-------|-----------------------------------------------------------------------------------------|
| `int` | The length of the match in the target text, or 0 if there is no match currently. <br /> |

**See also:**

- [first()](https://developer.android.com/reference/android/icu/text/SearchIterator#first())
- [next()](https://developer.android.com/reference/android/icu/text/SearchIterator#next())
- [previous()](https://developer.android.com/reference/android/icu/text/SearchIterator#previous())
- [last()](https://developer.android.com/reference/android/icu/text/SearchIterator#last())  

### getMatchStart

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
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()](https://developer.android.com/reference/android/icu/text/SearchIterator#first()),[next()](https://developer.android.com/reference/android/icu/text/SearchIterator#next()),[previous()](https://developer.android.com/reference/android/icu/text/SearchIterator#previous()), or[last()](https://developer.android.com/reference/android/icu/text/SearchIterator#last()). Just after construction, or after a searching method returns[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE), this method will return[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE).

Use[getMatchLength()](https://developer.android.com/reference/android/icu/text/SearchIterator#getMatchLength())to get the matched string length.

<br />

|                                      Returns                                      ||
|-------|----------------------------------------------------------------------------|
| `int` | index of a substring within the text string that is being searched. <br /> |

**See also:**

- [first()](https://developer.android.com/reference/android/icu/text/SearchIterator#first())
- [next()](https://developer.android.com/reference/android/icu/text/SearchIterator#next())
- [previous()](https://developer.android.com/reference/android/icu/text/SearchIterator#previous())
- [last()](https://developer.android.com/reference/android/icu/text/SearchIterator#last())  

### getMatchedText

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public String getMatchedText ()
```

Returns the text that was matched by the most recent call to[first()](https://developer.android.com/reference/android/icu/text/SearchIterator#first()),[next()](https://developer.android.com/reference/android/icu/text/SearchIterator#next()),[previous()](https://developer.android.com/reference/android/icu/text/SearchIterator#previous()), or[last()](https://developer.android.com/reference/android/icu/text/SearchIterator#last()). If the iterator is not pointing at a valid match (e.g. just after construction or after[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)has been returned, returns an empty string.

<br />

|                                                                                    Returns                                                                                    ||
|--------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| [String](https://developer.android.com/reference/java/lang/String) | the substring in the target test of the most recent match, or null if there is no match currently. <br /> |

**See also:**

- [first()](https://developer.android.com/reference/android/icu/text/SearchIterator#first())
- [next()](https://developer.android.com/reference/android/icu/text/SearchIterator#next())
- [previous()](https://developer.android.com/reference/android/icu/text/SearchIterator#previous())
- [last()](https://developer.android.com/reference/android/icu/text/SearchIterator#last())  

### getTarget

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public CharacterIterator getTarget ()
```

Return the string text to be searched.

<br />

|                                                           Returns                                                            ||
|------------------------------------------------------------------------------------------|------------------------------------|
| [CharacterIterator](https://developer.android.com/reference/java/text/CharacterIterator) | text string to be searched. <br /> |

### isOverlapping

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public boolean isOverlapping ()
```

Return true if the overlapping property has been set. See[setOverlapping(boolean)](https://developer.android.com/reference/android/icu/text/SearchIterator#setOverlapping(boolean))for more information.

<br />

|                                     Returns                                      ||
|-----------|-----------------------------------------------------------------------|
| `boolean` | true if the overlapping property has been set, false otherwise <br /> |

**See also:**

- [setOverlapping(boolean)](https://developer.android.com/reference/android/icu/text/SearchIterator#setOverlapping(boolean))  

### last

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
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()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())) is the match position if one was found. If a match is not found,[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)will be returned and the iterator will be adjusted to the index[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE).

<br />

|                                                                          Returns                                                                           ||
|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| `int` | The index of the first match, or[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)if there are no matches. <br /> |

**See also:**

- [getIndex()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())  

### next

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
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()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())) is the match position if one was found. If a match is not found,[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)will be returned and the iterator will be adjusted to a position after the end of the text string.

<br />

|                                                                                          Returns                                                                                          ||
|-------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `int` | The index of the next match after the current position, or[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)if there are no more matches. <br /> |

**See also:**

- [getIndex()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())  

### preceding

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public final int preceding (int position)
```

Returns the first index less thanpositionat which the string text matches the search pattern. The iterator is adjusted so that its current index (as returned by[getIndex()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())) is the match position if one was found. If a match is not found,[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)will be returned and the iterator will be adjusted to the index[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)

When the overlapping option ([isOverlapping()](https://developer.android.com/reference/android/icu/text/SearchIterator#isOverlapping())) is off, the last index of the result match is always less thanposition. When the overlapping option is on, the result match may span acrossposition.

<br />

|                        Parameters                        ||
|------------|----------------------------------------------|
| `position` | `int`: where search is to start from. <br /> |

|                                                                                        Returns                                                                                         ||
|-------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `int` | The character index of the first match precedingposition, or[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)if there are no matches. <br /> |

|                                                                                     Throws                                                                                      ||
|----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| [IndexOutOfBoundsException](https://developer.android.com/reference/java/lang/IndexOutOfBoundsException) | If position is less than or greater than the text range for searching |

**See also:**

- [getIndex()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())  

### previous

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
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()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())) is the match position if one was found. If a match is not found,[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)will be returned and the iterator will be adjusted to the index[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE).

<br />

|                                                                                            Returns                                                                                             ||
|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `int` | The index of the previous match before the current position, or[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)if there are no more matches. <br /> |

**See also:**

- [getIndex()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())  

### reset

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

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

<br />

### setBreakIterator

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public void setBreakIterator (BreakIterator breakiter)
```

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

<br />

|                                                                                                                                                                                                                 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](https://developer.android.com/reference/android/icu/text/BreakIterator), the match will be rejected and another will be searched for. If this parameter isnull, no break detection is attempted. <br /> |

**See also:**

- [BreakIterator](https://developer.android.com/reference/android/icu/text/BreakIterator)  

### setElementComparisonType

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public void setElementComparisonType (SearchIterator.ElementComparisonType type)
```

Sets the collation element comparison type.

The default comparison type is[ElementComparisonType.STANDARD_ELEMENT_COMPARISON](https://developer.android.com/reference/android/icu/text/SearchIterator.ElementComparisonType#STANDARD_ELEMENT_COMPARISON).

<br />

|                      Parameters                       ||
|--------|-----------------------------------------------|
| `type` | `SearchIterator.ElementComparisonType` <br /> |

**See also:**

- [SearchIterator.ElementComparisonType](https://developer.android.com/reference/android/icu/text/SearchIterator.ElementComparisonType)
- [getElementComparisonType()](https://developer.android.com/reference/android/icu/text/SearchIterator#getElementComparisonType())  

### setIndex

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
public void setIndex (int position)
```

<br />

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

<br />

<br />

|                               Parameters                               ||
|------------|------------------------------------------------------------|
| `position` | `int`: position from which to start the next search <br /> |

|                                                                                 Throws                                                                                 ||
|----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| [IndexOutOfBoundsException](https://developer.android.com/reference/java/lang/IndexOutOfBoundsException) | thrown if argument position is out of the target text range. |

**See also:**

- [getIndex()](https://developer.android.com/reference/android/icu/text/SearchIterator#getIndex())  

### setOverlapping

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

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

<br />

|                                     Parameters                                      ||
|----------------|---------------------------------------------------------------------|
| `allowOverlap` | `boolean`: flag indicator if overlapping matches are allowed <br /> |

**See also:**

- [isOverlapping()](https://developer.android.com/reference/android/icu/text/SearchIterator#isOverlapping())  

### setTarget

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

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

<br />

|                                Parameters                                ||
|--------|------------------------------------------------------------------|
| `text` | `CharacterIterator`: new text iterator to look for match, <br /> |

|                                                                      Throws                                                                      ||
|--------------------------------------------------------------------------------------------------------|------------------------------------------|
| [IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException) | thrown when text is null or has 0 length |

**See also:**

- [getTarget()](https://developer.android.com/reference/android/icu/text/SearchIterator#getTarget())

## Protected methods

### handleNext

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
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(int)](https://developer.android.com/reference/android/icu/text/SearchIterator#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](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE).

<br />

|                                      Parameters                                       ||
|---------|------------------------------------------------------------------------------|
| `start` | `int`: The index in the target text at which the search should start. <br /> |

|                                                                                 Returns                                                                                  ||
|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `int` | index at which the match starts, else if match is not found[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)is returned <br /> |

**See also:**

- [setMatchLength(int)](https://developer.android.com/reference/android/icu/text/SearchIterator#setMatchLength(int))  

### handlePrevious

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

```
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(int)](https://developer.android.com/reference/android/icu/text/SearchIterator#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](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE).

<br />

|                                       Parameters                                        ||
|-----------|------------------------------------------------------------------------------|
| `startAt` | `int`: The index in the target text at which the search should start. <br /> |

|                                                                                 Returns                                                                                  ||
|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `int` | index at which the match starts, else if match is not found[DONE](https://developer.android.com/reference/android/icu/text/SearchIterator#DONE)is returned <br /> |

**See also:**

- [setMatchLength(int)](https://developer.android.com/reference/android/icu/text/SearchIterator#setMatchLength(int))  

### setMatchLength

Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)  

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

<br />

|                Parameters                 ||
|----------|---------------------------------|
| `length` | `int`: new length to set <br /> |

**See also:**

- [handleNext(int)](https://developer.android.com/reference/android/icu/text/SearchIterator#handleNext(int))
- [handlePrevious(int)](https://developer.android.com/reference/android/icu/text/SearchIterator#handlePrevious(int))