Next: Rules Governing the Up: Multiple Values Previous: Multiple Values

## 7.10.1. Constructs for Handling Multiple Values

Normally multiple values are not used. Special forms are required both to produce multiple values and to receive them. If the caller of a function does not request multiple values, but the called function produces multiple values, then the first value is given to the caller and all others are discarded; if the called function produces zero values, then the caller gets `nil` as a value.

The primary primitive for producing multiple values is `values`, which takes any number of arguments and returns that many values. If the last form in the body of a function is a `values` with three arguments, then a call to that function will return three values. Other special forms also produce multiple values, but they can be described in terms of `values`. Some built-in Common Lisp functions, such as `floor`, return multiple values; those that do are so documented.

The special forms and macros for receiving multiple values are as follows:

    multiple-value-list
    multiple-value-call
    multiple-value-prog1
    multiple-value-bind
    multiple-value-setq

These specify a form to evaluate and an indication of where to put the values returned by that form.

[Function]
`values` `&rest` args

All of the arguments are returned, in order, as values. For example:

    (defun polar (x y)
      (values (sqrt (+ (* x x) (* y y))) (atan y x)))

    (multiple-value-bind (r theta) (polar 3.0 4.0)
      (vector r theta))
       => #(5.0 0.9272952)

The expression `(values)` returns zero values. This is the standard idiom for returning no values from a function.

Sometimes it is desirable to indicate explicitly that a function will return exactly one value. For example, the function

    (defun foo (x y)
      (floor (+ x y) y))

will return two values because `floor` returns two values. It may be that the second value makes no sense, or that for efficiency reasons it is desired not to compute the second value. The `values` function is the standard idiom for indicating that only one value is to be returned, as shown in the following example.

    (defun foo (x y)
      (values (floor (+ x y) y)))

This works because `values` returns exactly one value for each of its argument forms; as for any function call, if any argument form to `values` produces more than one value, all but the first are discarded.

There is absolutely no way in Common Lisp for a caller to distinguish between returning a single value in the ordinary manner and returning exactly one ``multiple value.'' For example, the values returned by the expressions `(+ 1 2)` and `(values (+ 1 2))` are identical in every respect: the single value `3`.

[Constant]
`multiple-values-limit`

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

[Function]
`values-list` `list`

All of the elements of list are returned as multiple values. For example:

    (values-list (list a b c)) == (values a b c)

In general,

    (values-list list) == (apply #'values list)

but `values-list` may be clearer or more efficient.

[Macro]
`multiple-value-list` `form`

`multiple-value-list` evaluates form and returns a list of the multiple values it returned. For example:

    (multiple-value-list (floor -3 4)) => (-1 1)

`multiple-value-list` and `values-list` are therefore inverses of each other.

[Special Form]
`multiple-value-call` `function` `{form}*`

`multiple-value-call` first evaluates function to obtain a function and then evaluates all of the forms. All the values of the forms are gathered together (not just one value from each) and are all given as arguments to the function. The result of `multiple-value-call` is whatever is returned by the function. For example:

    (+ (floor 5 3) (floor 19 4))
       == (+ 1 4) => 5
    (multiple-value-call #'+ (floor 5 3) (floor 19 4))
       == (+ 1 2 4 3) => 10
    (multiple-value-list form) == (multiple-value-call #'list form)

[Special Form]
`multiple-value-prog1` `form` `{form}*`

`multiple-value-prog1` evaluates the first form and saves all the values produced by that form. It then evaluates the other forms from left to right, discarding their values. The values produced by the first form are returned by `multiple-value-prog1`. See `prog1`, which always returns a single value.

[Macro]

    multiple-value-bind ({var}*) values-form
                          {declaration}* {form}*

The values-form is evaluated, and each of the variables var is bound to the respective value returned by that form. If there are more variables than values returned, extra values of `nil` are given to the remaining variables. If there are more values than variables, the excess values are simply discarded. The variables are bound to the values over the execution of the forms, which make up an implicit `progn`. For example:

    (multiple-value-bind (x) (floor 5 3) (list x)) => (1)
    (multiple-value-bind (x y) (floor 5 3) (list x y)) => (1 2)
    (multiple-value-bind (x y z) (floor 5 3) (list x y z))
       => (1 2 nil)

[Macro]
`multiple-value-setq variables form`

The variables must be a list of variables. The form is evaluated, and the variables are set (not bound) to the values returned by that form. If there are more variables than values returned, extra values of `nil` are assigned to the remaining variables. If there are more values than variables, the excess values are simply discarded.

Compatibility note: In Lisp Machine Lisp this is called `multiple-value`. The added clarity of the name `multiple-value-setq` in Common Lisp was deemed worth the incompatibility with Lisp Machine Lisp.

`multiple-value-setq` always returns a single value, which is the first value returned by form, or `nil` if form produces zero values.

X3J13 voted in March 1989 (SYMBOL-MACROLET-SEMANTICS) to specify that if any var refers not to an ordinary variable but to a binding made by `symbol-macrolet`, then that var is handled as if `setq` were used to assign the appropriate value to it.

[Macro]
`nth-value` `n` `form`

X3J13 voted in January 1989 (NTH-VALUE) to add a new macro named `nth-value`. The argument forms n and form are both evaluated. The value of n must be a non-negative integer, and the form may produce any number of values. The integer n is used as a zero-based index into the list of values. Value n of the form is returned as the single value of the `nth-value` form; `nil` is returned if the form produces no more than n values.

As an example, `mod` could be defined as

    (defun mod (number divisor)
      (nth-value 1 (floor number divisor)))

Value number 1 is the second value returned by `floor`, the first value being value number 0.

One could define `nth-value` simply as

    (defmacro nth-value (n form)
      `(nth ,n (multiple-value-list ,form)))

but the clever implementor will doubtless find an implementation technique for `nth-value` that avoids constructing an intermediate list of all the values of the form.

Common Lisp the Language, 2nd Edition BR>

Next: Rules Governing the Up: Multiple Values Previous: Multiple Values