Class TextFinder | Apps Script | Google for Developers (original) (raw)
Class TextFinder
Stay organized with collections Save and categorize content based on your preferences.
TextFinder
Find or replace text within a range, sheet or spreadsheet. Can also specify search options.
Methods
| Method | Return type | Brief description |
|---|---|---|
| findAll() | Range[] | Returns all cells matching the search criteria. |
| findNext() | Range | Returns the next cell matching the search criteria. |
| findPrevious() | Range | Returns the previous cell matching the search criteria. |
| getCurrentMatch() | Range | Returns the current cell matching the search criteria. |
| ignoreDiacritics(ignoreDiacritics) | TextFinder | If true, configures the search to ignore diacritics while matching; otherwise the search matches diacritics. |
| matchCase(matchCase) | TextFinder | If true, configures the search to match the search text's case exactly, otherwise the search defaults to case-insensitive matching. |
| matchEntireCell(matchEntireCell) | TextFinder | If true, configures the search to match the entire contents of a cell; otherwise, the search defaults to partial matching. |
| matchFormulaText(matchFormulaText) | TextFinder | If true, configures the search to return matches that appear within formula text; otherwise cells with formulas are considered based on their displayed value. |
| replaceAllWith(replaceText) | Integer | Replaces all matches with the specified text. |
| replaceWith(replaceText) | Integer | Replaces the search text in the currently matched cell with the specified text and returns the number of occurrences replaced. |
| startFrom(startRange) | TextFinder | Configures the search to start searching immediately after the specified cell range. |
| useRegularExpression(useRegEx) | TextFinder | 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
[Range[]](/apps-script/reference/spreadsheet/range) — All the matching cells.
Scripts that use this method require authorization with one or more of the following scopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
findNext()
Returns the next cell matching the search criteria.
Return
[Range](/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://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
findPrevious()
Returns the previous cell matching the search criteria.
Return
[Range](/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://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
getCurrentMatch()
Returns the current cell matching the search criteria.
Return
[Range](/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://www.googleapis.com/auth/spreadsheets.currentonlyhttps://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
[TextFinder](#) — This text finder, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://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
[TextFinder](#) — This text finder, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://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
[TextFinder](#) — This text finder, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://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
[TextFinder](#) — This text finder, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://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://www.googleapis.com/auth/spreadsheets.currentonlyhttps://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://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
startFrom(startRange)
Configures the search to start searching immediately after the specified cell range.
Parameters
| Name | Type | Description |
|---|---|---|
| startRange | Range | The cell range after which the search should start. |
Return
[TextFinder](#) — This text finder, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://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.
Parameters
| Name | Type | Description |
|---|---|---|
| useRegEx | Boolean | Whether to interpret the search string as a regular expression. |
Return
[TextFinder](#) — This text finder, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-12-02 UTC.