Debian Codegraph @

docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-setq.htm

raw
1 <html><head>
2
3 <title>cl:multiple-value-setq</title>
4
5 <style type="text/css">
6 .example {
7 color: #000000;
8 background-color: #F5F5F5;
9 padding: 8px;
10 border: #808080;
11 border-style: solid;
12 border-width: 1px;
13 width:auto;
14 }
15 .button {
16 color: #000000;
17 background-color: #F5F5F5;
18 padding-top: 1px;
19 padding-bottom: 1px;
20 padding-left: 4px;
21 padding-right: 8px;
22 border: #808080;
23 border-style: solid;
24 border-width: 1px;
25 white-space: pre;
26 }
27 .box {
28 color: #000000;
29 padding-top: 4px;
30 padding-bottom: 4px;
31 padding-left: 16px;
32 padding-right: 16px;
33 border: #808080;
34 border-style: solid;
35 border-width: 1px;
36 }
37 </style>
38
39 </head>
40
41 <body>
42
43 <a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
44 <a href="../../manual/contents.htm">Contents</a> |
45 <a href="../../tutorials/tutorials.htm">Tutorials</a> |
46 <a href="../examples.htm">Examples</a> |
47 <a href="../../reference/reference-index.htm">Reference</a>
48
49 <hr>
50
51 <h1>cl:multiple-value-setq</h1>
52
53 <hr>
54
55 <p>The <nobr>cl:<b>multiple-value-setq</b></nobr> macro assigns multiple
56 values to multiple variables:</p>
57
58 <p><div class="box">
59
60 <dl>
61 <dt>(cl:<b>multiple-value-setq</b> <i>symbols expr</i>)</dt>
62 <dd><i>symbols</i> - a list of symbols<br>
63 <i>expr</i> - a Lisp expression returning one or more values<br>
64 returns - the primary value returned by evaluating the expression</dd>
65 </dl>
66
67 </div></p>
68
69 <pre class="example">
70 (defmacro <font color="#0000CC">cl:multiple-value-setq</font> (symbols expr)
71 (and (or (not (consp symbols))
72 (eq 'quote (first symbols))
73 (dolist (symbol symbols)
74 (or (symbolp symbol) (return t))))
75 (error <font color="#880000">"not a list of symbols"</font> symbols))
76 (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
77 (let* ((result (eval expr))
78 (values (if <font color="#AA5500">cl:*multiple-values*</font>
79 <font color="#AA5500">*rslt*</font>
80 (list result)))
81 (number-of-symbols (length symbols))
82 (number-of-values (length values))
83 (assignments (list 'setq)))
84 (dotimes (index number-of-symbols)
85 (push (nth index symbols) assignments)
86 (push (when (&lt; index number-of-values)
87 (list 'quote (nth index values)))
88 assignments))
89 (setq assignments (reverse assignments))
90 `(progn ,assignments ',result)))
91 </pre>
92
93 <p>The expression is evaluated, and each symbol is assigned to the
94 corresponding value returned by the evaluation. <nobr>If there</nobr> are
95 more symbols than values returned,
96 <a href="../../reference/nil.htm">NIL</a> is assigned to the extra symbols.
97 <nobr>If there</nobr> are more values than symbols, the extra values are
98 discarded.</p>
99
100 <p><nobr>The
101 <a href="#cl-global-multiple-values">cl:*multiple-values*</a></nobr>
102 variable <nobr>is <a href="../../reference/t.htm">&nbsp;T&nbsp;</a></nobr>
103 if evaluating the expression returns multiple values and
104 <a href="../../reference/nil.htm">NIL</a> with a normal return value.</p>
105
106 <p>The <nobr>cl:<b>multiple-value-setq</b></nobr> macro assigns multiple
107 values to multiple variables
108 <nobr>using <a href="../../reference/setq.htm">setq</a>:</nobr></p>
109
110 <pre class="example">
111 &gt; (macroexpand-1 '(cl:multiple-value-setq (a b c)
112 (cl:values 1 2 3)))
113 (PROGN (SETQ A (QUOTE 1)
114 B (QUOTE 2)
115 C (QUOTE 3))
116 (QUOTE 1))
117 </pre>
118
119 <p>The <a href="../../reference/quote.htm">quote</a>s are necessary to
120 prevent 'unbound variable' and 'unbound function' errors with symbols and
121 lists.</p>
122
123 <p>Examples:</p>
124
125 <p><b>1.</b> The <nobr>cl:<b>multiple-value-setq</b></nobr> macro assigns
126 values returned by the <a href="values.htm">cl:values</a> function:</p>
127
128 <pre class="example">
129 (defun <font color="#0000CC">multiple-value-function</font> ()
130 (cl:values 1 2 3)) <font color="#008844">; multiple return values</font>
131
132 &gt; (let ((a 'A) (b 'B) (c 'C))
133 (cl:multiple-value-setq (a b c)
134 (multiple-value-function))
135 (list a b c))
136 (1 2 3)
137 </pre>
138
139 <p><b>2.</b> If there are no values returned in the Nyquist
140 <a href="../../reference/global-rslt.htm">*rslt*</a> variable, the normal
141 function return value is assigned to the first symbol and all remaining
142 symbols are assigned
143 <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
144
145 <pre class="example">
146 (defun <font color="#0000CC">normal-lisp-function</font> ()
147 (+ 1 1)) <font color="#008844">; normal return value</font>
148
149 &gt; (let ((a 'A) (b 'B) (c 'C))
150 (cl:multiple-value-setq (a b c)
151 (normal-lisp-function))
152 (list a b c))
153 (2 NIL NIL)
154 </pre>
155
156 <p><b>3.</b> If there are less values than symbols, the extra symbols are
157 assigned <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
158
159 <pre class="example">
160 (defun <font color="#0000CC">not-enough-values-function</font> ()
161 (cl:values 1 2)) <font color="#008844">; multiple return values</font>
162
163 &gt; (let ((a 'A) (b 'B) (c 'C))
164 (cl:multiple-value-setq (a b c)
165 (not-enough-values-function))
166 (list a b c))
167 (1 2 NIL)
168 </pre>
169
170 <p><b>4.</b> If there are more values than symbols, the extra values are
171 ignored:</p>
172
173 <pre class="example">
174 (defun <font color="#0000CC">too-many-values-function</font> ()
175 (cl:values 1 2 3 4 5)) <font color="#008844">; multiple return values</font>
176
177 &gt; (let ((a 'A) (b 'B) (c 'C))
178 (cl:multiple-value-setq (a b c)
179 (too-many-values-function))
180 (list a b c))
181 (1 2 3)
182 </pre>
183
184 <p><b>5.</b> Symbols not contained in the
185 <nobr>cl:<b>multiple-value-setq</b></nobr> <nobr>symbol-list</nobr> are not
186 changed:</p>
187
188 <pre class="example">
189 (defun <font color="#0000CC">multiple-value-function</font> ()
190 (cl:values 1 2 3)) <font color="#008844">; multiple return values</font>
191
192 &gt; (let ((a 'A) (b 'B) (c 'C) (d 'D) (e 'E))
193 (cl:multiple-value-setq (a b c)
194 (multiple-value-function))
195 (list a b c d e))
196 (1 2 3 D E)
197 </pre>
198
199 <p><b>5.</b> If no bindings exist, new variables will be created:</p>
200
201 <pre class="example">
202 (defun <font color="#0000CC">multiple-value-function</font> ()
203 (cl:values 1 2 3)) <font color="#008844">; multiple return values</font>
204
205 &gt; (let ((c 'C) (d 'D) (e 'E))
206 (cl:multiple-value-setq (a b c)
207 (multiple-value-function))
208 (list a b c d e))
209 (1 2 3 D E)
210 </pre>
211
212 <p><b>Caution:</b> In the last example, two global variables 'a' and 'b'
213 were created, while the lexical <a href="../../reference/let.htm">let</a>
214 variable 'c' was assigned to the <nobr>value 3</nobr>:</p>
215
216 <pre class="example">
217 &gt; (list a b)
218 (1 2)
219
220 &gt; (list a b c)
221 <font color="#AA0000">error: unbound variable - C</font>
222 </pre>
223
224 <p>The lexical <a href="../../reference/let.htm">let</a> binding of 'c' does
225 not exist in the global <nobr>top-level</nobr>.
226 <nobr>See <a href="../environment.htm">Environment</a></nobr> for more
227 details about variables.</p>
228
229 <p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
230
231 <hr>
232
233 <a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
234 <a href="../../manual/contents.htm">Contents</a> |
235 <a href="../../tutorials/tutorials.htm">Tutorials</a> |
236 <a href="../examples.htm">Examples</a> |
237 <a href="../../reference/reference-index.htm">Reference</a>
238
239 </body></html>