Skip to main content

multiple-value-prog1

multiple-value-prog1 Special Operator

Syntax:

multiple-value-prog1 first-form {form}* ! first-form-results

Arguments and Values:

first-form—a form; evaluated as described below.

form—a form; evaluated as described below.

first-form-results—the values resulting from the evaluation of first-form.

Description:

multiple-value-prog1 evaluates first-form and saves all the values produced by that form. It then evaluates each form from left to right, discarding their values.

Examples:

(setq temp ’(1 2 3)) *!* (1 2 3) 
(multiple-value-prog1 
    (values-list temp) 
  (setq temp nil) 
  (values-list temp)) *!* 1, 2, 3

See Also:

prog1 multiple-value-setq

Expanded Reference: multiple-value-prog1​

Preserving all values from the first form​

multiple-value-prog1 evaluates all forms but returns all the values from the first form, not just the primary value. This distinguishes it from prog1, which only returns the primary value.

(multiple-value-prog1
    (values 1 2 3)
  (format t "side effect~%"))
.. side effect
..
=> 1
=> 2
=> 3

Comparison with prog1​

prog1 discards secondary values from its first form. multiple-value-prog1 preserves them.

;; prog1 returns only the primary value
(prog1 (values 'a 'b 'c) (format t "done~%"))
.. done
..
=> A

;; multiple-value-prog1 preserves all values
(multiple-value-prog1 (values 'a 'b 'c) (format t "done~%"))
.. done
..
=> A
=> B
=> C

Preserving values while performing cleanup​

A common use is to save the result of an operation before performing side effects.

(let ((temp '(1 2 3)))
  (multiple-value-prog1
      (values-list temp)
    (setq temp nil)
    (values-list temp)))
=> 1
=> 2
=> 3

Practical use with floor​

(let ((x 0))
  (multiple-value-list
    (multiple-value-prog1
        (floor 17 5)
      (setq x 42))))
=> (3 2)