User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:values [2019/11/11 05:00]
cl:functions:values [2019/11/11 22:00] (current)
Line 1: Line 1:
 +====== Accessor VALUES ======
 +
 +====Syntax====
 +  * **values** //''&​rest''​ object// → //​object''​*''//​
 +  * (**setf** (**values** //''&​rest''​ place//) //​new-values//​)
 +
 +====Arguments and Values====
 +  * //object// - an //​[[CL:​Glossary:​object]]//​.
 +  * //place// - a //​[[CL:​Glossary:​place]]//​.
 +  * //​new-value//​ - an //​[[CL:​Glossary:​object]]//​.
 +
 +====Description====
 +**values** returns the //objects// as //​[[CL:​Glossary:​multiple values]]//.
 +
 +**[[CL:​Macros:​setf]]** of **values** is used to store the //​[[CL:​Glossary:​multiple values]]// //​new-values//​ into the //places//. see section {\secref\SETFofVALUES}.
 +
 +====Examples====
 +<​blockquote>​
 +(values) <​r>//<​no values>//</​r>​
 +(values 1) <​r>​1</​r>​
 +(values 1 2) <r>1
 +2</r>
 +(values 1 2 3) <r>1
 +2
 +3</r>
 +(values (values 1 2 3) 4 5) <r>1
 +4
 +5</r>
 +([[CL:​Macros:​defun]] polar (x y) 
 +  (values ([[CL:​Functions:​sqrt]] ([[CL:​Functions:​math-add|+]] ([[CL:​Functions:​math-multiply|*]] x x) ([[CL:​Functions:​math-multiply|*]] y y))) ([[CL:​Functions:​atan]] y x))) <​r>​POLAR </r>
 +([[CL:​Macros:​multiple-value-bind]] (r theta) (polar 3.0 4.0) 
 +  ([[CL:​Functions:​vector]] r theta)) <​r>#​(5.0 0.927295)</​r>​
 +</​blockquote>​
 +
 +Sometimes it is desirable to indicate explicitly that a function returns exactly one value. For example, the function
 +
 +<​blockquote>​
 +([[CL:​Macros:​defun]] foo (x y) 
 +  ([[CL:​Functions:​floor]] ([[CL:​Functions:​math-add|+]] x y) y)) 
 +<​r>​FOO </r>
 +</​blockquote> ​
 +
 +returns two values because **[[CL:​Functions:​floor]]** returns two values. It may be that the second value makes no sense, or that for efficiency 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:
 +
 +<​blockquote>​
 +([[CL:​Macros:​defun]] foo (x y) 
 +  (values ([[CL:​Functions:​floor]] ([[CL:​Functions:​math-add|+]] x y) y)))
 +<​r>​FOO</​r>​
 +</​blockquote>​
 +
 +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.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +  * **[[CL:​Functions:​values-list|Function VALUES-LIST]]**
 +  * **[[CL:​Macros:​multiple-value-bind|Macro MULTIPLE-VALUE-BIND]]**
 +  * **[[CL:​Constant Variables:​multiple-values-limit|Constant Variable MULTIPLE-VALUES-LIMIT]]**
 +  * {\secref\Evaluation}
 +
 +====Notes====
 +Since **values** is a //​[[CL:​Glossary:​function]]//,​ not a //​[[CL:​Glossary:​macro]]//​ or //​[[CL:​Glossary:​special form]]//, it receives as //​[[CL:​Glossary:​arguments]]//​ only the //​[[CL:​Glossary:​primary value|primary values]]// of its //​[[CL:​Glossary:​argument]]//​ //​[[CL:​Glossary:​form|forms]]//​.
 +
 +\issue{SETF-OF-VALUES:​ADD} \issue{SETF-OF-VALUES:​ADD} \issue{SETF-OF-VALUES:​ADD}