Debian Codegraph @

docsrc/xlisp/xlisp-doc/examples/arrays.htm

raw
1 <html><head>
2
3 <title>Arrays</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>Arrays</h1>
52
53 <hr>
54
55 <p>Arrays are also <a href="sequences.htm">Sequences</a>.</p>
56
57 <ul>
58 <li><nobr><a href="#make-array-star">make-array*</a> - create multi-dimensional arrays</nobr></li>
59 <li><nobr><a href="#aref-star">aref*</a> - access multi-dimensional-arrays</nobr></li>
60 <li><nobr><a href="#vector-star">vector*</a> - make a one-dimensional array out of arbitrary Lisp expressions</nobr></li>
61 <li><nobr><a href="#vector-star">array*</a> - make a multi-dimensional array out of arbitrary Lisp expressions</nobr></li>
62 </ul>
63
64 <a name="make-array-star"></a>
65
66 <hr>
67
68 <h2>make-array*</h2>
69
70 <hr>
71
72 <p>XLISP already has the
73 <nobr><a href="../reference/make-array.htm">make-array</a></nobr>
74 function to create <nobr>one-dimensional</nobr> arrays:</p>
75
76 <p><div class="box">
77
78 <dl>
79 <dt><nobr>(<a href="../reference/make-array.htm">make-array</a> <i>size</i>)</nobr></dt>
80 <dd><i>size</i> - the size [integer] of the array to be created<br>
81 returns - the new array</dd>
82 </dl>
83
84 </div></p>
85
86 <p>Here is a function to create <nobr>multi-dimensional</nobr> arrays:</p>
87
88 <p><div class="box">
89
90 <dl>
91 <dt>(<b>make-array*</b> <i>size-1</i> [<i>size-2</i> ...])</dt>
92 <dd><i>sizeN</i> - the size [integer] of the <i>N</i>-th dimension in the array to be created<br>
93 returns - the new array</dd>
94 </dl>
95
96 </div></p>
97
98 <pre class="example">
99 (defun <font color="#0000CC">make-array*</font> (&amp;rest dimensions-list)
100 (cond ((null dimensions-list)
101 (error <font color="#880000">"too few arguments"</font>))
102 ((and (null (rest dimensions-list))
103 (eql 0 (first dimensions-list)))
104 (make-array 0))
105 (t (labels ((multi-vector (dimensions-list)
106 (let ((count (first dimensions-list)))
107 (if (not (and (integerp count) (plusp count)))
108 (error <font color="#880000">"not a positive integer"</font> count)
109 (let ((rest (rest dimensions-list))
110 (elements-list nil))
111 (dotimes (i count)
112 (push (when rest
113 (multi-vector rest))
114 elements-list))
115 (apply #'vector (reverse elements-list)))))))
116 (multi-vector dimensions-list)))))
117 </pre>
118
119 <p>Examples:</p>
120
121 <pre class="example">
122 (make-array* 2 3) =&gt; #(#(NIL NIL NIL) #(NIL NIL NIL)))
123 (make-array* 2 2 1) =&gt; #(#(#(NIL) #(NIL)) #(#(NIL) #(NIL)))
124 </pre>
125
126 <p>Like <nobr><a href="../reference/make-array.htm">make-array</a></nobr> it
127 is possible to create <nobr>one-dimensional</nobr> arrays with zero
128 elements:</p>
129
130 <pre class="example">
131 (make-array* 0) =&gt; #()
132 (make-array 0) =&gt; #()
133 </pre>
134
135 <p>But it is not allowed to create <nobr>multi-dimensional</nobr> arrays
136 with <nobr>zero-size</nobr> dimensions:</p>
137
138 <pre class="example">
139 (make-array* 1 0 1) =&gt; <font color="#AA0000">error: not a positive integer - 0</font>
140 </pre>
141
142 <p><b>Rationale:</b> Multi-dimensional arrays are implemented as nested
143 vectors and a <nobr>zero-element</nobr> vector cannot hold the vector for
144 the subsequent dimension. <nobr>We would</nobr> need some additional
145 administration overhead to keep the subsequent dimensions accessible, but
146 this would break the compatibility to the <nobr>build-in</nobr> XLISP
147 <a href="../reference/aref.htm">aref</a> function.</p>
148
149 <p>More practical examples see 'aref*' below.</p>
150
151 <p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
152
153 <a name="aref-star"></a>
154
155 <hr>
156
157 <h2>aref*</h2>
158
159 <hr>
160
161 <p>XLISP already has the <a href="../reference/aref.htm">aref</a> function
162 to access elements in one-dimensional arrays:</p>
163
164 <p><div class="box">
165
166 <dl>
167 <dt>(<a href="../reference/aref.htm">aref</a> <i>array dimension-1</i>)</dt>
168 <dd><i>array</i> - one-dimensional array<br>
169 <i>dimension-1</i> - element number in the first dimension<br>
170 returns - the value of the array element</dd>
171 </dl>
172
173 </div></p>
174
175 <p>Here is a macro for accessing elements in <nobr>multi-dimensional</nobr>
176 arrays:</p>
177
178 <p><div class="box">
179
180 <dl>
181 <dt>(<b>aref*</b> <i>array dimension-1</i> [<i>dimension-2</i> ...])</dt>
182 <dd><i>array</i> - any-dimensional array<br>
183 <i>dimensionN</i> - element number in the <i>N</i>-th dimension<br>
184 returns - the value of the array element</dd>
185 </dl>
186
187 </div></p>
188
189 <pre class="example">
190 (defmacro <font color="#0000CC">aref*</font> (array &amp;rest index-list)
191 (labels ((multi-aref (array-name index-list)
192 (let ((index (first index-list)))
193 (if (not (integerp index))
194 (error <font color="#880000">"not an integer"</font> index)
195 (let ((rest (rest index-list))
196 (expansion-list (list 'aref)))
197 (push (if rest
198 (multi-aref array-name rest)
199 array-name)
200 expansion-list)
201 (push index expansion-list)
202 (reverse expansion-list))))))
203 (multi-aref `,array (reverse `,index-list))))
204 </pre>
205
206 <p>The symbols inside the <a href="../reference/labels.htm">labels</a> form
207 do not leak into the expansion, so 'aref*' also works with array names like
208 'array', '<nobr>array-name</nobr>' 'index', '<nobr>index-list</nobr>' or
209 '<nobr>expansion-list</nobr>'. Also the values of local or global variables
210 with these names are not changed.</p>
211
212 <pre class="example">
213 (macroexpand-1 '(aref* a 1 2 3)) =&gt; (aref (aref (aref a 1) 2) 3)
214 </pre>
215
216 <p>Examples:</p>
217
218 <pre class="example">
219 &gt; (setq a (make-array* 2 3))
220 #(#(NIL NIL NIL) #(NIL NIL NIL)))
221
222 &gt; (setf (aref* a 0 1) "hello")
223 "hello"
224
225 &gt; a
226 #(#(NIL "hello" NIL) #(NIL NIL NIL))
227
228 &gt; (aref* a 0 1)
229 "hello"
230 </pre>
231
232 <p>'aref*' with only one 'dimension' argument behaves
233 <nobr>like <a href="../reference/aref.htm">aref</a>:</nobr></p>
234
235 <pre class="example">
236 (aref* a 0) =&gt; #(NIL "hello" NIL)
237 (aref a 0) =&gt; #(NIL "hello" NIL)
238
239 (aref* (aref* a 0) 1) =&gt; "hello"
240 (aref (aref a 0) 1) =&gt; "hello"
241
242 (aref* a 0 1) =&gt; "hello"
243 (aref a 0 1) =&gt; <font color="#AA0000">error: too many arguments</font>
244 </pre>
245
246 <p>'aref*' like <a href="../reference/aref.htm">aref</a> also works
247 <nobr>with <a href="../reference/setf.htm">setf</a></nobr> to store
248 values in <nobr>multi-dimensional</nobr> arrays:</p>
249
250 <pre class="example">
251 (setf (aref* (aref* a 0) 1) "1") =&gt; "1" <font color="#008844">; a =&gt; #(#(NIL "1" NIL) #(NIL NIL NIL)))</font>
252 (setf (aref (aref a 0) 1) "2") =&gt; "2" <font color="#008844">; a =&gt; #(#(NIL "2" NIL) #(NIL NIL NIL)))</font>
253
254 (setf (aref* 0 1) "3") =&gt; "3" <font color="#008844">; a =&gt; #(#(NIL "3" NIL) #(NIL NIL NIL)))</font>
255 (setf (aref 0 1) "4") =&gt; <font color="#AA0000">error: too many arguments</font>
256 </pre>
257
258 <p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
259
260 <a name="vector-star"></a>
261
262 <hr>
263
264 <h2>vector*</h2>
265
266 <hr>
267
268 <pre class="example">
269 (defun <font color="#0000CC">vector*</font> (&amp;rest items)
270 (if (null items)
271 (make-array 0)
272 (let* ((end (length items))
273 (result (make-array end)))
274 (if (&gt; end 1)
275 (dotimes (index end) <font color="#008844">; more than one item</font>
276 (setf (aref result index)
277 (if (eq (nth index items) '*unbound*)
278 '*unbound*
279 (nth index items))))
280 (if (eq (first items) '*unbound*) <font color="#008844">; one item only</font>
281 (setf (aref result 0) '*unbound*)
282 (let ((item (first items)))
283 (case (type-of item)
284 (cons (let ((end (length item)))
285 (setq result (make-array end))
286 (dotimes (index end)
287 (setf (aref result index)
288 (if (eq (nth index item) '*unbound*)
289 '*unbound*
290 (nth index item))))))
291 (array (let ((end (length item)))
292 (setq result (make-array end))
293 (dotimes (index end)
294 (setf (aref result index)
295 (if (eq (aref item index) '*unbound*)
296 '*unbound*
297 (aref item index))))))
298 (string (let ((end (length item)))
299 (setq result (make-array end))
300 (dotimes (index end)
301 (setf (aref result index)
302 (char item index)))))
303 (t (setf (aref result 0) item))))))
304 result)))
305 </pre>
306
307 <pre class="example">
308 (defun <font color="#0000CC">list*</font> (&amp;rest items)
309 (if (null items)
310 nil
311 (let* ((end (length items))
312 (result nil))
313 (labels ((push-element (element)
314 (if (member (type-of element) '(array cons string))
315 (setq result (append (reverse (list* element)) result))
316 (push element result))))
317 (dotimes (index end)
318 (if (eq (nth index items) '*unbound*)
319 (push '*unbound* result)
320 (let ((item (nth index items)))
321 (case (type-of item)
322 (nil (push item result))
323 (cons (let ((end (length item)))
324 (when (not (consp (last item))) (incf end))
325 (dotimes (index end)
326 (if (eq (nth index item) '*unbound*)
327 (push '*unbound* result)
328 (push-element (nth index item))))))
329 (array (let ((end (length item)))
330 (dotimes (index end)
331 (if (eq (aref item index) '*unbound*)
332 (push '*unbound* result)
333 (push-element (aref item index))))))
334 (string (let ((end (length item)))
335 (dotimes (index end)
336 (push (char item index) result))))
337 (t (push item result))))))
338 (reverse result)))))
339 </pre>
340
341
342 <pre class="example">
343 (defun <font color="#0000CC">tree*</font> (&amp;rest items)
344 (if (null items)
345 nil
346 (let* ((end (length items))
347 (result nil))
348 (labels ((push-element (element)
349 (if (member (type-of element) '(array cons string))
350 (push (reverse (list* element)) result)
351 (push element result))))
352 (dotimes (index end)
353 (if (eq (nth index items) '*unbound*)
354 (push '*unbound* result)
355 (let ((item (nth index items)))
356 (case (type-of item)
357 (nil (push item result))
358 (cons (let ((end (length item)))
359 (when (not (consp (last item))) (incf end))
360 (dotimes (index end)
361 (if (eq (nth index item) '*unbound*)
362 (push '*unbound* result)
363 (push-element (nth index item))))))
364 (array (let ((end (length item)))
365 (dotimes (index end)
366 (if (eq (aref item index) '*unbound*)
367 (push '*unbound* result)
368 (push-element (aref item index))))))
369 (string (let ((end (length item)))
370 (dotimes (index end)
371 (push (char item index) result))))
372 (t (push item result))))))
373 (reverse result)))))
374 </pre>
375
376
377
378
379 <p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
380
381 <a name="array-star"></a>
382
383 <hr>
384
385 <h2>array*</h2>
386
387 <hr>
388
389 <pre class="example">
390 (defun <font color="#0000CC">array*</font> (&amp;rest items)
391 (if (null items)
392 (make-array 0)
393 (let* ((end (length items))
394 (result (make-array end)))
395 (labels ((vector-element (element index)
396 (setf (aref result index)
397 (if (member (type-of element) '(cons string array))
398 (array* element)
399 element))))
400 (dotimes (index end)
401 (if (eq (nth index items) '*unbound*)
402 (setf (aref result index) '*unbound*)
403 (let ((item (nth index items)))
404 (case (type-of item)
405 (cons (let ((end (length item)))
406 (dotimes (index end)
407 (if (eq (nth index item) '*unbound*)
408 (strcat-element <font color="#880000">"*UNBOUND*"</font>)
409 (strcat-element (nth index item))))))
410 (array (let ((end (length item)))
411 (dotimes (index end)
412 (if (eq (aref item index) '*unbound*)
413 (strcat-element <font color="#880000">"*UNBOUND*"</font>)
414 (strcat-element (aref item index))))))
415 (t (strcat-element item))))))
416 result))))
417 </pre>
418
419
420 <p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
421
422 <hr>
423
424 <a href="../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
425 <a href="../manual/contents.htm">Contents</a> |
426 <a href="../tutorials/tutorials.htm">Tutorials</a> |
427 <a href="examples.htm">Examples</a> |
428 <a href="../reference/reference-index.htm">Reference</a>
429
430 </body></html>