(lispref.info)Calling Functions


Next: Mapping Functions Prev: Defining Functions Up: Functions

Calling Functions
=================

   Defining functions is only half the battle.  Functions don't do
anything until you "call" them, i.e., tell them to run.  This process
is also known as "invocation".

   The most common way of invoking a function is by evaluating a list.
For example, evaluating the list `(concat "a" "b")' calls the function
`concat'.  Note: Evaluation, for a description of evaluation.

   When you write a list as an expression in your program, the function
name is part of the program.  This means that the choice of which
function to call is made when you write the program.  Usually that's
just what you want.  Occasionally you need to decide at run time which
function to call.  Then you can use the functions `funcall' and `apply'.

 - Function: funcall FUNCTION &rest ARGUMENTS
     `funcall' calls FUNCTION with ARGUMENTS, and returns whatever
     FUNCTION returns.

     Since `funcall' is a function, all of its arguments, including
     FUNCTION, are evaluated before `funcall' is called.  This means
     that you can use any expression to obtain the function to be
     called.  It also means that `funcall' does not see the expressions
     you write for the ARGUMENTS, only their values.  These values are
     *not* evaluated a second time in the act of calling FUNCTION;
     `funcall' enters the normal procedure for calling a function at the
     place where the arguments have already been evaluated.

     The argument FUNCTION must be either a Lisp function or a
     primitive function.  Special forms and macros are not allowed,
     because they make sense only when given the "unevaluated" argument
     expressions.  `funcall' cannot provide these because, as we saw
     above, it never knows them in the first place.

          (setq f 'list)
               => list
          (funcall f 'x 'y 'z)
               => (x y z)
          (funcall f 'x 'y '(z))
               => (x y (z))
          (funcall 'and t nil)
          error--> Invalid function: #<subr and>

     Compare this example with that of `apply'.

 - Function: apply FUNCTION &rest ARGUMENTS
     `apply' calls FUNCTION with ARGUMENTS, just like `funcall' but
     with one difference: the last of ARGUMENTS is a list of arguments
     to give to FUNCTION, rather than a single argument.  We also say
     that this list is "appended" to the other arguments.

     `apply' returns the result of calling FUNCTION.  As with
     `funcall', FUNCTION must either be a Lisp function or a primitive
     function; special forms and macros do not make sense in `apply'.

          (setq f 'list)
               => list
          (apply f 'x 'y 'z)
          error--> Wrong type argument: listp, z
          (apply '+ 1 2 '(3 4))
               => 10
          (apply '+ '(1 2 3 4))
               => 10
          
          (apply 'append '((a b c) nil (x y z) nil))
               => (a b c x y z)

     An interesting example of using `apply' is found in the description
     of `mapcar'; see the following section.

   It is common for Lisp functions to accept functions as arguments or
find them in data structures (especially in hook variables and property
lists) and call them using `funcall' or `apply'.  Functions that accept
function arguments are often called "functionals".

   Sometimes, when you call such a function, it is useful to supply a
no-op function as the argument.  Here are two different kinds of no-op
function:

 - Function: identity ARG
     This function returns ARG and has no side effects.

 - Function: ignore &rest ARGS
     This function ignores any arguments and returns `nil'.


automatically generated by info2www