strex (version 0.1.3)

str_match_arg: Argument Matching.

Description

Match arg against a series of candidate choices where NULL means take the first one. arg matches an element of choices if arg is a prefix of that element.

Usage

str_match_arg(arg, choices, index = FALSE, several_ok = FALSE,
  ignore_case = FALSE)
match_arg(arg, choices, index = FALSE, several_ok = FALSE,
  ignore_case = FALSE)

Arguments

arg

A character vector (of length one unless several_ok = TRUE).

choices

A character vector of candidate values.

index

Return the index of the match rather than the match itself? Default no.

several_ok

Allow arg to have length greater than one to match several arguments at once? Default no.

ignore_case

Ignore case while matching. Default no. If this is TRUE, the returned value is the matched element of choices (with its original casing).

Details

ERRORs are thrown when a match is not made and where the match is ambiguous. However, sometimes ambiguities are inevitable. Consider the case where choices = c("ab", "abc"), then there's no way to choose "ab" because "ab" is a prefix for "ab" and "abc". If this is the case, you need to provide a full match, i.e. using arg = "ab" will get you "ab" without an error, however arg = "a" will throw an ambiguity error.

This function inspired by RSAGA::match.arg.ext(). Its behaviour is almost identical (the difference is that RSAGA::match.arg.ext(..., ignore.case = TRUE) guarantees that the function returns strings in all lower case, but that is not so with filesstrings::match_arg(..., ignore_case = TRUE)) but RSAGA is a heavy package to depend upon so filesstrings::match_arg() might be handy for package developers.

This function is designed to be used inside of other functions. It's fine to use it for other purposes, but the error messages might be a bit weird.

Examples

# NOT RUN {
choices <- c("Apples", "Pears", "Bananas", "Oranges")
match_arg(NULL, choices)
match_arg("A", choices)
match_arg("B", choices, index = TRUE)
match_arg(c("a", "b"), choices, several_ok = TRUE, ignore_case = TRUE)
match_arg(c("b", "a"), choices, ignore_case = TRUE, index = TRUE,
          several_ok = TRUE)

# }