Multiple Values

Another feature of Common Lisp that I’ve mentioned in passing—in Chapter 11, when I discussed **GETHASH**--is the ability for a single form to return multiple values. I’ll discuss it in greater detail now. It is, however, slightly misplaced in a chapter on special operators since the ability to return multiple values isn’t provided by just one or two special operators but is deeply integrated into the language. The operators you’ll most often use when dealing with multiple values are macros and functions, not special operators. But it is the case that the basic ability to get at multiple return values is provided by a special operator, **MULTIPLE-VALUE-CALL**, upon which the more commonly used **MULTIPLE-VALUE-BIND** macro is built.

The key thing to understand about multiple values is that returning multiple values is quite different from returning a list—if a form returns multiple values, unless you do something specific to capture the multiple values, all but the primary value will be silently discarded. To see the distinction, consider the function **GETHASH**, which returns two values: the value found in the hash table and a boolean that’s **NIL** when no value was found. If it returned those two values in a list, every time you called **GETHASH** you’d have to take apart the list to get at the actual value, regardless of whether you cared about the second return value. Suppose you have a hash table, *h*, that contains numeric values. If **GETHASH** returned a list, you couldn’t write something like this:

  1. (+ (gethash 'a *h*) (gethash 'b *h*))

because **+** expects its arguments to be numbers, not lists. But because the multiple value mechanism silently discards the secondary return value when it’s not wanted, this form works fine.

There are two aspects to using multiple values—returning multiple values and getting at the nonprimary values returned by forms that return multiple values. The starting points for returning multiple values are the functions **VALUES** and **VALUES-LIST**. These are regular functions, not special operators, so their arguments are passed in the normal way. **VALUES** takes a variable number of arguments and returns them as multiple values; **VALUES-LIST** takes a single list and returns its elements as multiple values. In other words:

  1. (values-list x) === (apply #'values x)

The mechanism by which multiple values are returned is implementation dependent just like the mechanism for passing arguments into functions is. Almost all language constructs that return the value of some subform will “pass through” multiple values, returning all the values returned by the subform. Thus, a function that returns the result of calling **VALUES** or **VALUES-LIST** will itself return multiple values—and so will another function whose result comes from calling the first function. And so on.11

But when a form is evaluated in a value position, only the primary value will be used, which is why the previous addition form works the way you’d expect. The special operator **MULTIPLE-VALUE-CALL** provides the mechanism for getting your hands on the multiple values returned by a form. **MULTIPLE-VALUE-CALL** is similar to **FUNCALL** except that while **FUNCALL** is a regular function and, therefore, can see and pass on only the primary values passed to it, **MULTIPLE-VALUE-CALL** passes, to the function returned by its first subform, all the values returned by the remaining subforms.

  1. (funcall #'+ (values 1 2) (values 3 4))             ==> 4
  2. (multiple-value-call #'+ (values 1 2) (values 3 4)) ==> 10

However, it’s fairly rare that you’ll simply want to pass all the values returned by a function onto another function. More likely, you’ll want to stash the multiple values in different variables and then do something with them. The **MULTIPLE-VALUE-BIND** macro, which you saw in Chapter 11, is the most frequently used operator for accepting multiple return values. Its skeleton looks like this:

  1. (multiple-value-bind (variable*) values-form
  2.   body-form*)

The values-form is evaluated, and the multiple values it returns are bound to the variables. Then the body-forms are evaluated with those bindings in effect. Thus:

  1. (multiple-value-bind (x y) (values 1 2)
  2.   (+ x y)) ==> 3

Another macro, **MULTIPLE-VALUE-LIST**, is even simpler—it takes a single form, evaluates it, and collects the resulting multiple values into a list. In other words, it’s the inverse of **VALUES-LIST**.

  1. CL-USER> (multiple-value-list (values 1 2))
  2. (1 2)
  3. CL-USER> (values-list (multiple-value-list (values 1 2)))
  4. 1
  5. 2

However, if you find yourself using **MULTIPLE-VALUE-LIST** a lot, it may be a sign that some function should be returning a list to start with rather than multiple values.

Finally, if you want to assign multiple values returned by a form to existing variables, you can use **VALUES** as a **SETF**able place. For example:

  1. CL-USER> (defparameter *x* nil)
  2. *X*
  3. CL-USER> (defparameter *y* nil)
  4. *Y*
  5. CL-USER> (setf (values *x* *y*) (floor (/ 57 34)))
  6. 1
  7. 23/34
  8. CL-USER> *x*
  9. 1
  10. CL-USER> *y*
  11. 23/34