This is equivalent to base::match.arg() with a few differences:

  • Partial matches trigger an error.

  • Error messages are a bit more informative and obey the tidyverse standards.

arg_match() derives the possible values from the caller frame.

arg_match0() is a bare-bones version if performance is at a premium. It requires a string as arg and explicit character values. For convenience, arg may also be a character vector containing every element of values, possibly permuted. In this case, the first element of arg is used.

  values = NULL,
  multiple = FALSE,
  error_arg = caller_arg(arg),
  error_call = caller_env()

arg_match0(arg, values, arg_nm = caller_arg(arg), error_call = caller_env())



A symbol referring to an argument accepting strings.


A character vector of possible values that arg can take.


These dots are for future extensions and must be empty.


Whether arg may contain zero or several values.


An argument name as a string. This argument will be mentioned in error messages as the input that is at the origin of a problem.


The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.


Same as error_arg.


The string supplied to arg.

See also


fn <- function(x = c("foo", "bar")) arg_match(x) fn("bar")
#> [1] "bar"
# Throws an informative error for mismatches: try(fn("b"))
#> Error in fn("b") : #> `x` must be one of "foo" or "bar", not "b". #> Did you mean "bar"?
#> Error in fn("baz") : #> `x` must be one of "foo" or "bar", not "baz". #> Did you mean "bar"?
# Use the bare-bones version with explicit values for speed: arg_match0("bar", c("foo", "bar", "baz"))
#> [1] "bar"
# For convenience: fn1 <- function(x = c("bar", "baz", "foo")) fn3(x) fn2 <- function(x = c("baz", "bar", "foo")) fn3(x) fn3 <- function(x) arg_match0(x, c("foo", "bar", "baz")) fn1()
#> [1] "bar"
#> [1] "bar"
#> Error in fn3("zoo") : #> `x` must be one of "foo", "bar", or "baz", not "zoo". #> Did you mean "foo"?