Skip to main content

multiple-value-bind

multiple-value-bind Macro

Syntax:

multiple-value-bind ({var}*) values-form {declaration}* {form}*

! {result}*

Data and Control

Arguments and Values:

var—a symbol naming a variable; not evaluated.

values-form—a form; evaluated.

declaration—a declare expression; not evaluated.

forms—an implicit progn.

results—the values returned by the forms.

Description:

Creates new variable bindings for the vars and executes a series of forms that use these bindings. The variable bindings created are lexical unless special declarations are specified.

Values-form is evaluated, and each of the vars is bound to the respective value returned by that form. If there are more vars than values returned, extra values of nil are given to the remaining vars. If there are more values than vars, the excess values are discarded. The vars are bound to the values over the execution of the forms, which make up an implicit progn. The consequences are unspecified if a type declaration is specified for a var, but the value to which that var is bound is not consistent with the type declaration.

The scopes of the name binding and declarations do not include the values-form.

Examples:

(multiple-value-bind (f r) 
    (floor 130 11) 
  (list f r)) *!* (11 9)

See Also:

let, multiple-value-call

Notes:

(multiple-value-bind ({var}*) values-form {form}*)

⌘ (multiple-value-call #’(lambda (&optional {var}* &rest #1=#:ignore)

(declare (ignore #1#))

{form}*)

values-form)

Expanded Reference: multiple-value-bind​

Capturing multiple return values from floor​

multiple-value-bind binds variables to the multiple values returned by a form.

(multiple-value-bind (quotient remainder)
    (floor 17 5)
  (list quotient remainder))
=> (3 2)

Decomposing a floating point number​

decode-float returns three values: significand, exponent, and sign.

(multiple-value-bind (significand exponent sign)
    (decode-float -3.5)
  (list significand exponent sign))
=> (0.875 2 -1.0)

Extra variables are bound to NIL​

If the form returns fewer values than there are variables, the excess variables are bound to nil.

(multiple-value-bind (a b c)
    (values 1 2)
  (list a b c))
=> (1 2 NIL)

Excess values are discarded​

If the form returns more values than there are variables, the extra values are simply discarded.

(multiple-value-bind (q)
    (floor 10 3)
  q)
=> 3

Using with truncate for integer division​

A practical use case: getting just the integer part and remainder of a division.

(defun divide-with-remainder (dividend divisor)
  (multiple-value-bind (quotient remainder)
      (truncate dividend divisor)
    (format nil "~A divided by ~A is ~A remainder ~A"
            dividend divisor quotient remainder)))
=> DIVIDE-WITH-REMAINDER

(divide-with-remainder 17 5)
=> "17 divided by 5 is 3 remainder 2"

Capturing hash table lookup results​

gethash returns the value and a boolean indicating whether the key was found.

(let ((ht (make-hash-table)))
  (setf (gethash :a ht) 1)
  (multiple-value-bind (value found-p)
      (gethash :b ht)
    (if found-p
        (format nil "Found: ~A" value)
        "Not found")))
=> "Not found"