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

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 used order in the message is determined by the order of the factor levels, which is influenced by the locale at the time of their creation, see the 'Warning' in factor() and the 'Programming Notes' in checkinput::all_names().

replace_vals() does not allow input of type double because matching such input should allow for small numerical errors by using a tolerance, for example using are_equal().

See also

gsub(); replace(); trimws() to remove leading whitespace, trailing whitespace, or both; replace_nonalnum(); append() which, despite its name, can insert values into a vector at any place; checkinput::all_names() and checkinput::is_path() for checks on the validity of strings.

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, replace_nonalnum(), 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'