GNU Info

(elisp)Calling Functions

---

Next: Mapping Functions Prev: Defining Functions Up: Functions

---

Enter node , (file) or (file)node

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

   Defining functions is only half the battle.  Functions don't do
anything until you "call" them, i.e., tell them to run.  Calling a
function 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' with arguments `"a"' and `"b"'.  Note: Evaluation, for a
description of evaluation.

   When you write a list as an expression in your program, the function
name it calls is written in your program.  This means that you choose
which function to call, and how many arguments to give it, when you
write the program.  Usually that's just what you want.  Occasionally you
need to compute at run time which function to call.  To do that, use the
function `funcall'.  When you also need to determine at run time how
many arguments to pass, use `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 these examples with the examples 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 objects,
     which are passed to FUNCTION as separate arguments, rather than a
     single list.  We say that `apply' "spreads" this list so that each
     individual element becomes an argument.

     `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)

     For an interesting example of using `apply', see the description of
     `mapcar', in Note: Mapping Functions.

   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 a functional, 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'.