Skip to contents

Replace values

Source: R/replace_vals.R
replace_vals.Rd

Replace character values or factor levels.

Usage

replace_vals(
  x,
  old,
  new,
  ignore_case = FALSE,
  allow_multiple = TRUE,
  warn_absent = TRUE,
  signal_case_old = c("warning", "error", "message", "quiet"),
  signal_case_new = c("warning", "error", "message", "quiet"),
  signal_old_ignore_case = TRUE,
  quiet = FALSE
)

Arguments

x

Character vector with values to be replaced, or factor with levels to be replaced.

old

Character vector with values to be replaced. Should be unique and not contain the value new, otherwise an error is thrown.

new

Character string with the new value.

ignore_case

TRUE or FALSE: ignore case when looking for old? See Details.

allow_multiple

TRUE or FALSE: allow multiple values of old to match x? See Details.

warn_absent

TRUE or FALSE: warn if neither old nor new is found in x? It is silently assumed replacement is not necessary anymore if new is found.

signal_case_old, signal_case_new

"error", "warning", "message", or "quiet": character string indicating the type of signal to give if values in x are a case-insensitive match but not a case-sensitive match to old or new, respectively. For signal_case_old, this is also influenced by argument signal_old_ignore_case.

signal_old_ignore_case

TRUE or FALSE: use signal_case_old if ignore_case is TRUE? If FALSE, no signal is emitted if ignore_case is TRUE.

quiet

TRUE or FALSE: suppress the message indicating which values have been replaced?

Value

x with the requested replacements. Factor levels are not reordered after the replacement.

Details

Values in x that only differ from new in their case are not adjusted, but lead to a signal as indicated by argument signal_case_new.

An error is thrown if allow_multiple is FALSE and multiple values of old match x, unless those values of old only differ in their case and ignore_case is TRUE. An example of such an exception is replace_vals(x = c("a", "A"), old = c("a", "A"), new = "b", ignore_case = TRUE, allow_multiple = FALSE), which returns c("b", "b").

If quiet is FALSE, a message indicates which values have been replaced. The order of the factor levels determines the order used in the message, which is influenced by the locale at the time of their creation, see the Warning in factor().

See also

gsub(); replace(); append() which, despite its name, can insert values into a vector at any place; replace_nonalnum()

Other functions to check equality: are_equal(), check_case(), get_file_path(), not_in(), replace_nonalnum(), signif_custom()

Other functions to modify character vectors: as.numeric_safe(), reexports, signal_text(), unpaste_unquote(), vect_to_char(), wrap_text()

Other functions to modify factors: as.numeric_safe(), reexports, reorder_levels(), vect_to_char()

Examples

x <- c("k", "l", "m")

# All values in 'x' that match any value of 'old' are replaced by 'new'.
replace_vals(x = rep(x, 2), old = x[3:2], new = "b", allow_multiple = TRUE)
#> Replaced values 'l', 'm' with 'b'
#> [1] "k" "b" "b" "k" "b" "b"

# Factor input to 'x' is handled by replacing the values and levels. The
# levels are not reordered
replace_vals(x = as.factor(x), old = x[3:2], new = "b", allow_multiple = TRUE)
#> Replaced values 'l', 'm' with 'b'
#> [1] k b b
#> Levels: k b

# Case-insensitive matching is used if 'ignore_case' is TRUE, with a warning
# if 'signal_case_old' is '"warning"'
replace_vals(x = "A", old = "a", new = "b", ignore_case = TRUE,
             signal_case_old = "warning")
#> Warning: Values in 'x' are a case-insensitive match but not a case-sensitive match to
#> 'old' ('a'): 'A'
#> Replaced values 'A' with 'b'
#> [1] "b"

# Case-sensitive matching is used if 'ignore_case' is FALSE. A warning is
# issued if no match is found and 'warn_absent' is 'TRUE'
replace_vals(x = "A", old = "a", new = "b", ignore_case = FALSE,
             warn_absent = TRUE)
#> Warning: Values in 'x' are a case-insensitive match but not a case-sensitive match to
#> 'old' ('a'): 'A'
#> Warning: None of the values of argument 'old' ('a') were found in 'x' ('A')!
#> [1] "A"

# If 'allow_multiple' is FALSE, an error is thrown if multiple values of
# 'old' match 'x'.
try(replace_vals(x = x, old = letters[13:12], new = "b",
                 allow_multiple = FALSE))
#> Error in replace_vals(x = x, old = letters[13:12], new = "b", allow_multiple = FALSE) : 
#>   Multiple values of 'old' ('m', 'l') matched 'x' ('k', 'l', 'm'): 'l', 'm'