User Tools

====== 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}