Ordinarily the result of calling a Lisp function is a single Lisp object. Sometimes, however, it is convenient for a function to compute several objects and return them. Common Lisp provides a mechanism for handling multiple values directly. This mechanism is cleaner and more efficient than the usual tricks involving returning a list of results or stashing results in global variables.
Normally multiple values are not used. Special operators 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 operators and macros for receiving multiple values are as follows:
These specify a form to evaluate and an indication of where to put the values returned by that form.
All of the arguments are returned, in order, as values. For example:
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
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.
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.
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.
All of the elements of list are returned as multiple values. For example:
In general,
but values-list may be clearer or more efficient.
multiple-value-list evaluates form and returns a list of the multiple values it returned. For example:
multiple-value-list and values-list are therefore inverses of each other.
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:
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.
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:
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 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.
X3J13 voted in January 1989 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
Value number 1 is the second value returned by floor, the first value being value number 0.
One could define nth-value simply as
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.
It is often the case that the value of a special operator or macro call is defined to be the value of one of its subforms. For example, the value of a cond is the value of the last form in the selected clause.
In most such cases, if the subform produces multiple values, then the original form will also produce all of those values. This passing back of multiple values of course has no effect unless eventually one of the special operators for receiving multiple values is reached.
To be explicit, multiple values can result from a special operator under precisely these circumstances:
X3J13 has voted to add many new constructs to the language that contain implicit progn contexts. I won’t attempt to list them all here. Of particular interest, however, is locally, which may be regarded as simply a version of progn that permits declarations before its body. This provides a useful building block for constructing macros that permit declarations (but not documentation strings) before their bodies and pass back any multiple values produced by the last sub-form of a body. (If a body can contain a documentation string, most likely lambda is the correct building block to use.)
Among special operators that never pass back multiple values are prog1, prog2, setq, and multiple-value-setq. The conventional way to force only one value to be returned from a form x is to write (values x).
The most important rule about multiple values is: No matter how many values a form produces, if the form is an argument form in a function call, then exactly one value (the first one) is used.
For example, if you write (cons (floor x)), then cons will always receive exactly one argument (which is of course an error), even though floor returns two values. To pass both values from floor to cons, one must write something like (multiple-value-call #’cons (floor x)). In an ordinary function call, each argument form produces exactly one argument; if such a form returns zero values, nil is used for the argument, and if more than one value, all but the first are discarded. Similarly, conditional constructs such as if that test the value of a form will use exactly one value, the first one, from that form and discard the rest; such constructs will use nil as the test value if zero values are returned.