TextFinder

Find or replace text within a range, sheet or spreadsheet. Can also specify search options.

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#findAll()` | `https://developers.google.com/apps-script/reference/spreadsheet/range` | Returns all cells matching the search criteria. |
| `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#findNext()` | `https://developers.google.com/apps-script/reference/spreadsheet/range` | Returns the next cell matching the search criteria. |
| `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#findPrevious()` | `https://developers.google.com/apps-script/reference/spreadsheet/range` | Returns the previous cell matching the search criteria. |
| `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#getCurrentMatch()` | `https://developers.google.com/apps-script/reference/spreadsheet/range` | Returns the current cell matching the search criteria. |
| `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#ignoreDiacritics(Boolean)` | `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#` | If `true`, configures the search to ignore diacritics while matching; otherwise the search matches diacritics. |
| `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#matchCase(Boolean)` | `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#` | If `true`, configures the search to match the search text's case exactly, otherwise the search defaults to case-insensitive matching. |
| `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#matchEntireCell(Boolean)` | `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#` | If `true`, configures the search to match the entire contents of a cell; otherwise, the search defaults to partial matching. |
| `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#matchFormulaText(Boolean)` | `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#` | If `true`, configures the search to return matches that appear within formula text; otherwise cells with formulas are considered based on their displayed value. |
| `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#replaceAllWith(String)` | `Integer` | Replaces all matches with the specified text. |
| `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#replaceWith(String)` | `Integer` | Replaces the search text in the currently matched cell with the specified text and returns the number of occurrences replaced. |
| `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#startFrom(Range)` | `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#` | Configures the search to start searching immediately after the specified cell range. |
| `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#useRegularExpression(Boolean)` | `https://developers.google.com/apps-script/reference/spreadsheet/text-finder#` | If `true`, configures the search to interpret the search string as a regular expression; otherwise the search interprets the search string as normal text. |

## Detailed documentation

### `findAll()`

Returns all cells matching the search criteria.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/range` --- All the matching cells.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `findNext()`

Returns the next cell matching the search criteria.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/range` --- The next matching cell, or `null` if there are no previous matches.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `findPrevious()`

Returns the previous cell matching the search criteria.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/range` --- The previous matching cell, or `null` if there are no previous matches.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `getCurrentMatch()`

Returns the current cell matching the search criteria.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/range` --- The current matching cell, or `null` if there are no further matches.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `ignoreDiacritics(ignoreDiacritics)`

If `true`, configures the search to ignore diacritics while matching; otherwise the
search matches diacritics. A diacritic is a sign, such as an accent or cedilla, which when
written above or below a letter indicates a difference in pronunciation from the same letter
when unmarked or differently marked.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `ignoreDiacritics` | `Boolean` | Whether the search considers diacritics. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/text-finder#` --- This text finder, for chaining.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `matchCase(matchCase)`

If `true`, configures the search to match the search text's case exactly, otherwise the
search defaults to case-insensitive matching.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `matchCase` | `Boolean` | Whether the matching is case-sensitive. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/text-finder#` --- This text finder, for chaining.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `matchEntireCell(matchEntireCell)`

If `true`, configures the search to match the entire contents of a cell; otherwise, the
search defaults to partial matching.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `matchEntireCell` | `Boolean` | Whether the entire cell is matched. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/text-finder#` --- This text finder, for chaining.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `matchFormulaText(matchFormulaText)`

If `true`, configures the search to return matches that appear within formula text;
otherwise cells with formulas are considered based on their displayed value.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `matchFormulaText` | `Boolean` | Whether the search examines formula text. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/text-finder#` --- This text finder, for chaining.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `replaceAllWith(replaceText)`

Replaces all matches with the specified text. Returns the number of occurrences replaced, which
may be different from the number of matched cells.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `replaceText` | `String` | The text that replaces the text in the matched cells. |

#### Return


`Integer` --- The number of occurrences replaced.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `replaceWith(replaceText)`

Replaces the search text in the currently matched cell with the specified text and returns the
number of occurrences replaced.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `replaceText` | `String` | The text that replaces the content in the currently matched cell. |

#### Return


`Integer` --- The number of occurrences replaced.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `startFrom(startRange)`

Configures the search to start searching immediately after the specified cell range.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `startRange` | `https://developers.google.com/apps-script/reference/spreadsheet/range` | The cell range after which the search should start. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/text-finder#` --- This text finder, for chaining.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `useRegularExpression(useRegEx)`

If `true`, configures the search to interpret the search string as a regular expression;
otherwise the search interprets the search string as normal text. For more details on how to
use regular expressions, refer to the [Find and replace support page.](https://support.google.com/docs/answer/62754?p=spreadsheets_find_replace&visit_id=1-636603693162634183-3185740572&rd=1)

#### Parameters

| Name | Type | Description |
|---|---|---|
| `useRegEx` | `Boolean` | Whether to interpret the search string as a regular expression. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/text-finder#` --- This text finder, for chaining.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`