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

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

AI.Repository@cs.cmu.edu