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-listlist) == (apply #'valueslist)

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 *form*s. All the values
of the *form*s 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-listform) == (multiple-value-call #'listform)

**[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 *form*s
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 2nil)

**[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.

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

AI.Repository@cs.cmu.edu