Editing Common Lisp (section)

====Multiple return values====

Common Lisp supports the concept of ''multiple values'',<ref>{{cite web|title=Common Lisp Hyperspec: Section 3.1.7|url=http://www.lispworks.com/documentation/HyperSpec/Body/03_ag.htm}}</ref> where any expression always has a single ''primary value'', but it might also have any number of ''secondary values'', which might be received and inspected by interested callers. This concept is distinct from returning a list value, as the secondary values are fully optional, and passed via a dedicated side channel. This means that callers may remain entirely unaware of the secondary values being there if they have no need for them, and it makes it convenient to use the mechanism for communicating information that is sometimes useful, but not always necessary. For example,

* The <code>TRUNCATE</code> function<ref>{{cite web|title=Common Lisp Hyperspec: Function FLOOR|url=http://www.lispworks.com/documentation/HyperSpec/Body/f_floorc.htm}}</ref> rounds the given number to an [[integer]] towards zero. However, it also returns a remainder as a secondary value, making it very easy to determine what value was truncated. It also supports an optional divisor parameter, which can be used to perform [[Euclidean division]] trivially:
<syntaxhighlight lang="cl">
(let ((x 1266778)
      (y 458))
  (multiple-value-bind (quotient remainder)
      (truncate x y)
    (format nil "~A divided by ~A is ~A remainder ~A" x y quotient remainder)))

;;;; => "1266778 divided by 458 is 2765 remainder 408"
</syntaxhighlight>

* <code>GETHASH</code><ref>{{cite web|title=Common Lisp Hyperspec: Accessor GETHASH|url=http://www.lispworks.com/documentation/HyperSpec/Body/f_gethas.htm}}</ref> returns the value of a key in an [[associative map]], or the default value otherwise, and a secondary Boolean indicating whether the value was found. Thus code that does not care about whether the value was found or provided as the default can simply use it as-is, but when such distinction is important, it might inspect the secondary Boolean and react appropriately. Both use cases are supported by the same call and neither is unnecessarily burdened or constrained by the other. Having this feature at the language level removes the need to check for the existence of the key or compare it to [[Null morpheme|null]] as would be done in other languages.
<syntaxhighlight lang="cl">
(defun get-answer (library)
  (gethash 'answer library 42))

(defun the-answer-1 (library)
  (format nil "The answer is ~A" (get-answer library)))
;;;; Returns "The answer is 42" if ANSWER not present in LIBRARY

(defun the-answer-2 (library)
  (multiple-value-bind (answer sure-p)
      (get-answer library)
    (if (not sure-p)
        "I don't know"
     (format nil "The answer is ~A" answer))))
;;;; Returns "I don't know" if ANSWER not present in LIBRARY
</syntaxhighlight>

Multiple values are supported by a handful of standard forms, most common of which are the <code>MULTIPLE-VALUE-BIND</code> special form for accessing secondary values and <code>VALUES</code> for returning multiple values:

<syntaxhighlight lang="cl">
(defun magic-eight-ball ()
  "Return an outlook prediction, with the probability as a secondary value"
  (values "Outlook good" (random 1.0)))

;;;; => "Outlook good"
;;;; => 0.3187
</syntaxhighlight>