Common Lisp the Language, 2nd Edition

Next: Simple Sequencing Up: Control Structure Previous: Generalized Variables

# 7.3. Function Invocation

The most primitive form for function invocation in Lisp of course has no name; any list that has no other interpretation as a macro call or special form is taken to be a function call. Other constructs are provided for less common but nevertheless frequently useful situations.

[Function]
`apply` `function arg` `&rest` `more-args`

This applies function to a list of arguments.

The function may be a compiled-code object, or a lambda-expression, or a symbol; in the latter case the global functional value of that symbol is used (but it is illegal for the symbol to be the name of a macro or special form).

X3J13 voted in June 1988 (FUNCTION-TYPE) to allow the function to be only of type `symbol` or `function`; a lambda-expression is no longer acceptable as a functional argument. One must use the `function` special form or the abbreviation `#'` before a lambda-expression that appears as an explicit argument form.

The arguments for the function consist of the last argument to `apply` appended to the end of a list of all the other arguments to `apply` but the function itself; it is as if all the arguments to `apply` except the function were given to `list*` to create the argument list. For example:

    (setq f '+) (apply f '(1 2)) => 3
    (setq f #'-) (apply f '(1 2)) => -1
    (apply #'max 3 5 '(2 7 3)) => 7
    (apply 'cons '((+ 2 3) 4)) =>
            ((+ 2 3) . 4) not (5 . 4)
    (apply #'+ '()) => 0

Note that if the function takes keyword arguments, the keywords as well as the corresponding values must appear in the argument list:

    (apply #'(lambda (&key a b) (list a b)) '(:b 3)) => (nil 3)

This can be very useful in conjunction with the `&allow-other-keys` feature:

    (defun foo (size &rest keys &key double &allow-other-keys)
      (let ((v (apply #'make-array size :allow-other-keys t keys)))
        (if double (concatenate (type-of v) v v) v)))

    (foo 4 :initial-contents '(a b c d) :double t)
       => #(a b c d a b c d)

[Function]
`funcall` `fn` `&rest` `arguments`

`(funcall fn a1 a2 ... an)` applies the function fn to the arguments a1, a2, ..., an. The fn may not be a special form or a macro; this would not be meaningful.

X3J13 voted in June 1988 (FUNCTION-TYPE) to allow the fn to be only of type `symbol` or `function`; a lambda-expression is no longer acceptable as a functional argument. One must use the `function` special form or the abbreviation `#'` before a lambda-expression that appears as an explicit argument form.

For example:

    (cons 1 2) => (1 . 2)
    (setq cons (symbol-function '+))
    (funcall cons 1 2) => 3

The difference between `funcall` and an ordinary function call is that the function is obtained by ordinary Lisp evaluation rather than by the special interpretation of the function position that normally occurs.

Compatibility note: The Common Lisp function `funcall` corresponds roughly to the Interlisp primitive `apply*`.

[Constant]
`call-arguments-limit`

The value of `call-arguments-limit` is a positive integer that is the upper exclusive bound on the number of arguments that may be passed to a function. This bound depends on the implementation but will not be smaller than 50. (Implementors are encouraged to make this limit as large as practicable without sacrificing performance.) The value of `call-arguments-limit` must be at least as great as that of `lambda-parameters-limit`. See also `multiple-values-limit`.

Next: Simple Sequencing Up: Control Structure Previous: Generalized Variables