R: Argument Verification Using Partial Matching

match.arg {base} | R Documentation

## Argument Verification Using Partial Matching

### Description

`match.arg` matches `arg` against a table of candidate values as specified by `choices`, where `NULL` means to take the first one.

### Usage

    match.arg(arg, choices, several.ok = FALSE)

### Arguments

`arg` | a character vector (of length one unless `several.ok` is `TRUE`) or `NULL`.
`choices` | a character vector of candidate values
`several.ok` | logical specifying if `arg` should be allowed to have more than one element.

### Details

In the one-argument form `match.arg(arg)`, the choices are obtained from a default setting for the formal argument `arg` of the function from which `match.arg` was called. (Since default argument matching will set `arg` to `choices`, this is allowed as an exception to the ‘length one unless `several.ok` is `TRUE`’ rule, and returns the first element.)

Matching is done using `pmatch`, so `arg` may be abbreviated.

### Value

The unabbreviated version of the exact or unique partial match if there is one; otherwise, an error is signalled if `several.ok` is false, as per default. When `several.ok` is true and more than one element of `arg` has a match, all unabbreviated versions of matches are returned.

### See Also

`pmatch`, `match.fun`, `match.call`.

### Examples

    require(stats)
    ## Extends the example for 'switch'
    center <- function(x, type = c("mean", "median", "trimmed")) {
      type <- match.arg(type)
      switch(type,
             mean = mean(x),
             median = median(x),
             trimmed = mean(x, trim = .1))
    }
    x <- rcauchy(10)
    center(x, "t")       # Works
    center(x, "med")     # Works
    try(center(x, "m"))  # Error
    stopifnot(identical(center(x),       center(x, "mean")),
              identical(center(x, NULL), center(x, "mean")) )

    ## Allowing more than one match:
    match.arg(c("gauss", "rect", "ep"),
              c("gaussian", "epanechnikov", "rectangular", "triangular"),
              several.ok = TRUE)

[Package base version 2.6.2 Index]