match.arg                package: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)

