Skip to main content

values

values Accessor

Syntax:

values &rest object ! {object}*

(setf (values &rest place) new-values**)**

Arguments and Values:

object—an object.

place—a place.

new-value—an object.

Description:

values returns the objects as multiple values2.

setf of values is used to store the multiple values2 new-values into the places. See Section 5.1.2.3 (VALUES Forms as Places).

Examples:

(values) *! ⟨no values⟩* 
(values 1) *!* 1 
(values 1 2) *!* 1, 2 
(values 1 2 3) *!* 1, 2, 3 
(values (values 1 2 3) 4 5) *!* 1, 4, 5 
(defun polar (x y) 
  (values (sqrt (+ (\* x x) (\* y y))) (atan y x))) *!* POLAR 
(multiple-value-bind (r theta) (polar 3.0 4.0) 
  (vector r theta)) 
*!* #(5.0 0.927295) 
Sometimes it is desirable to indicate explicitly that a function returns exactly one value. For example, the function 
(defun foo (x y) 
  (floor (+ x y) y)) *!* FOO 
returns two values because **floor** returns two values. It may be that the second value makes no sense, or that for eciency reasons it is desired not to compute the second value. **values** is the standard idiom for indicating that only one value is to be returned: 

(defun foo (x y) 
  (values (floor (+ x y) y))) *!* FOO 
This works because **values** returns exactly one value for each of *args*; as for any function call, if any of *args* produces more than one value, all but the first are discarded.

See Also:

values-list, multiple-value-bind, multiple-values-limit, Section 3.1 (Evaluation)

Notes:

Since values is a function, not a macro or special form, it receives as arguments only the primary values of its argument forms.

Expanded Reference: values​

Returning multiple values from a function​

values returns its arguments as multiple values. This is the standard way to return more than one value.

(values 1 2 3)
=> 1
=> 2
=> 3

Returning no values​

Called with no arguments, values returns zero values.

(values)
;; => (no values returned)

Defining a function that returns multiple values​

(defun divide (dividend divisor)
  (values (floor dividend divisor)
          (mod dividend divisor)))
=> DIVIDE

(divide 17 5)
=> 3
=> 2

Suppressing extra return values​

Wrapping a form in values truncates its results to a single value. This is useful when a function returns multiple values but you only want the primary value.

(floor 17 5)
=> 3
=> 2

(values (floor 17 5))
=> 3

Using setf with values to assign to multiple places​

setf of values assigns multiple values to multiple places simultaneously.

(let (a b c)
  (setf (values a b c) (values 1 2 3))
  (list a b c))
=> (1 2 3)

Only primary values are passed as function arguments​

Since values is a function, it receives only the primary values of its argument forms.

(values (values 1 2 3) 4 5)
=> 1
=> 4
=> 5