ore_subst {ore}

Replace matched substrings with new text

Description

These functions substitute new text into strings in regions that match a regular expression. The substitutions may be simple text, may include references to matched subgroups, or may be created by an R function.

Usage

ore_subst(regex, replacement, text, ..., all = FALSE, start = 1L)

ore_repl(regex, replacement, text, ..., all = FALSE, start = 1L,
  simplify = TRUE)

Arguments

regex

A single character string or object of class "ore". In the former case, this will first be passed through ore.

replacement

A character vector, or a function to be applied to the matches.

text

A vector of strings to match against.

...

Further arguments to replacement, if it is a function.

all

If TRUE, then all matches within each element of text will be found. Otherwise, the search will stop at the first match.

start

An optional vector of offsets (in characters) at which to start searching. Will be recycled to the length of text.

simplify

For ore_repl, a character vector of modified strings will be returned if this is TRUE and text is of length 1. Otherwise, a list of such objects will always be returned.

Details

These functions differ in how they are vectorised. ore_subst vectorises over matches, and returns a vector of the same length as the text argument. If multiple replacements are given then they are applied to matches in turn. ore_repl vectorises over replacements, replicating the elements of text as needed, and (in general) returns a list the same length as text, whose elements are character vectors each of the same length as replacement (or its return value, if a function). Each string combines the first replacement for each match, the second, and so on.

If replacement is a character vector, its component strings may include back-references to captured substrings. "\\0" corresponds to the whole matching substring, "\\1" is the first captured group, and so on. Named groups may be referenced as "\\k<name>".

If replacement is a function, then it will be passed as its first argument an object of class "orearg". This is a character vector containing as its elements the matched substrings, and with an attribute containing the matches for parenthesised subgroups, if there are any. A groups method is available for this class, so the groups attribute can be easily obtained that way. The substitution function will be called once per element of text by ore_subst, and once per match by ore_repl.

Value

Versions of text with the substitutions made.

See Also

ore_search

Examples

# Simple text substitution (produces "no dogs")
ore_subst("\\d+", "no", "2 dogs")

# Back-referenced substitution (produces "22 dogs")
ore_subst("(\\d+)", "\\1\\1", "2 dogs")

# Function-based substitution (produces "4 dogs")
ore_subst("\\d+", function(i) as.numeric(i)^2, "2 dogs")