do.call                 package:base                 R Documentation

Execute a Function Call

Description:

     'do.call' constructs and executes a function call from a name or a
     function and a list of arguments to be passed to it.

Usage:

     do.call(what, args, quote = FALSE, envir = parent.frame())

Arguments:

    what: either a function or a non-empty character string naming the
          function to be called.

    args: a _list_ of arguments to the function call.  The 'names'
          attribute of 'args' gives the argument names.

   quote: a logical value indicating whether to quote the arguments.

   envir: an environment within which to evaluate the call.  This will
          be most useful if 'what' is a character string and the
          arguments are symbols or quoted expressions.

Details:

     If 'quote' is 'FALSE', the default, then the arguments are
     evaluated (in the calling environment, not 'envir'.).  If 'quote'
     is 'TRUE' then each argument is quoted (see 'quote') so that the
     effect of argument evaluation is to remove the quotes - leaving
     the original arguments unevaluated when the call is constructed.

     The behavior of some functions, such as 'substitute', will not be
     the same for functions evaluated using 'do.call' as if they were
     evaluated from the interpreter.  The precise semantics are
     currently undefined and subject to change.

Value:

     The result of the (evaluated) function call.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'call' which creates an unevaluated call.

Examples:

     do.call("complex", list(imag = 1:3))

     ## if we already have a list (e.g. a data frame)
     ## we need c() to add further arguments
     tmp <- expand.grid(letters[1:2], 1:3, c("+", "-"))
     do.call("paste", c(tmp, sep=""))

     do.call(paste, list(as.name("A"), as.name("B")), quote=TRUE)

     ## examples of where objects will be found.
     A <- 2
     f <- function(x) print(x^2)
     env <- new.env()
     assign("A", 10, envir = env)
     assign("f", f, envir = env)
     f <- function(x) print(x)
     f(A)                                    # 2
     do.call("f", list(A))                   # 2
     do.call("f", list(A), envir=env)        # 4
     do.call(f, list(A), envir=env)          # 2
     do.call("f", list(quote(A)), envir=env) # 100
     do.call(f, list(quote(A)), envir=env)   # 10
     do.call("f", list(as.name("A")), envir=env) # 100

     eval(call("f", A))                      # 2
     eval(call("f", quote(A)))               # 2
     eval(call("f", A), envir=env)           # 4
     eval(call("f", quote(A)), envir=env)    # 100

