ore_subst: 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)

Value

Versions of text with the substitutions made.

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.

Examples

Run this code

# 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")