match.fun                package:base                R Documentation

Function Verification for ``Function Variables''

Description:

     When called inside functions that take a function as argument,
     extract the desired function object while avoiding undesired
     matching to objects of other types.

Usage:

     match.fun(FUN, descend = TRUE)

Arguments:

     FUN: item to match as function.

 descend: logical; control whether to search past non-function objects.

Details:

     `match.fun' is not intended to be used at the top level since it
     will perform matching in the parent of the caller.

     If `FUN' is a function, it is returned.  If it is a symbol or a
     character vector of length one, it will be looked up using `get'
     in the environment of the parent of the caller.  If it is of any
     other mode, it is attempted first to get the argument to the
     caller as a symbol (using `substitute' twice), and if that fails,
     an error is declared.

     If `descend = TRUE', `match.fun' will look past non-function
     objects with the given name; otherwise if `FUN' points to a
     non-function object then an error is generated.

     This is now used in base functions such as `apply', `lapply',
     `outer', and `sweep'.

Value:

     A function matching `FUN' or an error is generated.

Bugs:

     The `descend' argument is a bit of misnomer and probably not
     actually needed by anything.  It may go away in the future.

     It is impossible to fully foolproof this.  If one `attach'es a
     list or data frame containing a character object with the same
     name of a system function, it will be used.

Author(s):

     Peter Dalgaard and Robert Gentleman, based on an earlier version
     by Jonathan Rougier.

See Also:

     `match.arg', `get'

Examples:

     # Same as get("*"):
     match.fun("*")
     # Overwrite outer with a vector
     outer <- 1:5

     match.fun(outer, descend = FALSE) #-> Error:  not a function

     match.fun(outer) # finds it anyway
     is.function(match.fun("outer")) # as well

