Class TextFinder

TextFinder

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

Methods

MethodReturn typeBrief description
findAll()Range[]Returns all cells matching the search criteria.
findNext()RangeReturns the next cell matching the search criteria.
findPrevious()RangeReturns the previous cell matching the search criteria.
getCurrentMatch()RangeReturns the current cell matching the search criteria.
ignoreDiacritics(ignoreDiacritics)TextFinderIf true, configures the search to ignore diacritics while matching; otherwise the search matches diacritics.
matchCase(matchCase)TextFinderIf true, configures the search to match the search text's case exactly, otherwise the search defaults to case-insensitive matching.
matchEntireCell(matchEntireCell)TextFinderIf true, configures the search to match the entire contents of a cell; otherwise, the search defaults to partial matching.
matchFormulaText(matchFormulaText)TextFinderIf 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)IntegerReplaces all matches with the specified text.
replaceWith(replaceText)IntegerReplaces the search text in the currently matched cell with the specified text and returns the number of occurrences replaced.
startFrom(startRange)TextFinderConfigures the search to start searching immediately after the specified cell range.
useRegularExpression(useRegEx)TextFinderIf 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

NameTypeDescription
ignoreDiacriticsBooleanWhether 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

NameTypeDescription
matchCaseBooleanWhether 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

NameTypeDescription
matchEntireCellBooleanWhether 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

NameTypeDescription
matchFormulaTextBooleanWhether 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

NameTypeDescription
replaceTextStringThe 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

NameTypeDescription
replaceTextStringThe 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

NameTypeDescription
startRangeRangeThe 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

NameTypeDescription
useRegExBooleanWhether 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