Class 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[] — All the matching cells.

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

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

`findNext()`

Returns the next cell matching the search criteria.

Return

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.currentonly
https://www.googleapis.com/auth/spreadsheets

`findPrevious()`

Returns the previous cell matching the search criteria.

Return

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.currentonly
https://www.googleapis.com/auth/spreadsheets

`getCurrentMatch()`

Returns the current cell matching the search criteria.

Return

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

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

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

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

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

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.currentonly
https://www.googleapis.com/auth/spreadsheets