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
     ## Not run: 
     match.fun(outer, descend = FALSE) #-> Error:  not a function
     ## End(Not run)
     match.fun(outer) # finds it anyway
     is.function(match.fun("outer")) # as well

