| blob | d7e7f0121ae42a42362df5998d77ccc22b1e4f21 |
1 @c -----------------------------------------------------------------------------
2 @page
3 @node Arrays, Structures, Lists, Data Types and Structures
4 @section Arrays
5 @c -----------------------------------------------------------------------------
7 Maxima supports 3 array-like constructs:
8 @itemize
9 @anchor{hashed array}
10 @anchor{hashed arrays}
11 @anchor{undeclared array}
12 @anchor{undeclared arrays}
13 @item If one tries to write to an indexed variable without creating a list first an
14 undeclared array (also named hashed array) is created that grows dynamically and
15 allows numbers, symbols and strings as indices:
16 @c ===beg===
17 @c a["feww"]:1;
18 @c a[qqwdqwd]:3;
19 @c a[5]:99;
20 @c a[qqwdqwd];
21 @c a[5];
22 @c a["feww"];
23 @c ===end===
24 @example
25 @group
26 (%i1) a["feww"]:1;
27 (%o1) 1
28 @end group
29 @group
30 (%i2) a[qqwdqwd]:3;
31 (%o2) 3
32 @end group
33 @group
34 (%i3) a[5]:99;
35 (%o3) 99
36 @end group
37 @group
38 (%i4) a[qqwdqwd];
39 (%o4) 3
40 @end group
41 @group
42 (%i5) a[5];
43 (%o5) 99
44 @end group
45 @group
46 (%i6) a["feww"];
47 (%o6) 1
48 @end group
49 @end example
50 Since lisp handles hashed arrays and @mref{memoizing functions} similar to arrays
51 many of the functions that can be applied to arrays can be applied to them, as well.
52 @item Lists (see @mref{makelist} allow for fast addition and removal
53 of elements, can be created without knowing their final size.
54 @item Declared arrays that allow fast access to random elements at the cost that their
55 size needs to be known at construction time.
56 (@xref{Performance considerations for Lists}.)
57 @end itemize
59 @menu
60 * Functions and Variables for Arrays::
61 @end menu
63 @c -----------------------------------------------------------------------------
64 @node Functions and Variables for Arrays, , Arrays, Arrays
65 @subsection Functions and Variables for Arrays
66 @c -----------------------------------------------------------------------------
68 @c -----------------------------------------------------------------------------
69 @anchor{array}
70 @deffn {Function} array @
71 @fname{array} (@var{name}, @var{dim_1}, @dots{}, @var{dim_n}) @
72 @fname{array} (@var{name}, @var{type}, @var{dim_1}, @dots{}, @var{dim_n}) @
73 @fname{array} ([@var{name_1}, @dots{}, @var{name_m}], @var{dim_1}, @dots{}, @var{dim_n})
75 Creates an @math{n}-dimensional array. @math{n} may be less than or equal to 5.
76 The subscripts for the @math{i}'th dimension are the integers running from 0 to
77 @var{dim_i}.
79 @code{array (@var{name}, @var{dim_1}, ..., @var{dim_n})} creates a general
80 array.
82 @code{array (@var{name}, @var{type}, @var{dim_1}, ..., @var{dim_n})} creates
83 an array, with elements of a specified type. @var{type} can be @code{fixnum}
84 for integers of limited size or @code{flonum} for floating-point numbers.
86 @code{array ([@var{name_1}, ..., @var{name_m}], @var{dim_1}, ..., @var{dim_n})}
87 creates @math{m} arrays, all of the same dimensions.
88 @c SAME TYPE AS WELL ??
90 See also @mrefcomma{arraymake} @mref{arrayinfo} and @mrefdot{make_array}
92 @opencatbox{Categories:}
93 @category{Arrays}
94 @closecatbox
95 @end deffn
97 @c -----------------------------------------------------------------------------
98 @anchor{arrayapply}
99 @deffn {Function} arrayapply (@var{A}, [@var{i_1}, @dots{}, @var{i_n}])
101 Evaluates @code{@var{A} [@var{i_1}, ..., @var{i_n}]},
102 where @var{A} is an array and @var{i_1}, @dots{}, @var{i_n} are integers.
104 This is reminiscent of @mrefcomma{apply} except the first argument is an array
105 instead of a function.
107 @opencatbox{Categories:}
108 @category{Expressions}
109 @category{Arrays}
110 @closecatbox
111 @end deffn
113 @c -----------------------------------------------------------------------------
114 @anchor{arrayinfo}
115 @deffn {Function} arrayinfo (@var{A})
117 Returns information about the array @var{A}.
118 The argument @var{A} may be a declared array, a @mrefcomma{hashed array}
119 a @mrefcomma{memoizing function} or a subscripted function.
121 For declared arrays, @code{arrayinfo} returns a list comprising the atom
122 @code{declared}, the number of dimensions, and the size of each dimension.
123 The elements of the array, both bound and unbound, are returned by
124 @mrefdot{listarray}
126 For undeclared arrays (hashed arrays), @code{arrayinfo} returns a list
127 comprising the atom @code{hashed}, the number of subscripts,
128 and the subscripts of every element which has a value.
129 The values are returned by @mrefdot{listarray}
131 For @mrefcomma{memoizing functions} @code{arrayinfo} returns a list comprising the atom
132 @code{hashed}, the number of subscripts,
133 and any subscript values for which there are stored function values.
134 The stored function values are returned by @mrefdot{listarray}
136 For subscripted functions, @code{arrayinfo} returns a list comprising the atom
137 @code{hashed}, the number of subscripts,
138 and any subscript values for which there are lambda expressions.
139 The lambda expressions are returned by @mrefdot{listarray}
141 See also @mrefdot{listarray}
143 Examples:
145 @code{arrayinfo} and @mref{listarray} applied to a declared array.
147 @c ===beg===
148 @c array (aa, 2, 3);
149 @c aa [2, 3] : %pi;
150 @c aa [1, 2] : %e;
151 @c arrayinfo (aa);
152 @c listarray (aa);
153 @c ===end===
154 @example
155 @group
156 (%i1) array (aa, 2, 3);
157 (%o1) aa
158 @end group
159 @group
160 (%i2) aa [2, 3] : %pi;
161 (%o2) %pi
162 @end group
163 @group
164 (%i3) aa [1, 2] : %e;
165 (%o3) %e
166 @end group
167 @group
168 (%i4) arrayinfo (aa);
169 (%o4) [declared, 2, [2, 3]]
170 @end group
171 @group
172 (%i5) listarray (aa);
173 (%o5) [#####, #####, #####, #####, #####, #####, %e, #####,
174 #####, #####, #####, %pi]
175 @end group
176 @end example
178 @code{arrayinfo} and @mref{listarray} applied to an undeclared array (@mrefdot{hashed array}).
180 @c ===beg===
181 @c bb [FOO] : (a + b)^2;
182 @c bb [BAR] : (c - d)^3;
183 @c arrayinfo (bb);
184 @c listarray (bb);
185 @c ===end===
186 @example
187 @group
188 (%i1) bb [FOO] : (a + b)^2;
189 2
190 (%o1) (b + a)
191 @end group
192 @group
193 (%i2) bb [BAR] : (c - d)^3;
194 3
195 (%o2) (c - d)
196 @end group
197 @group
198 (%i3) arrayinfo (bb);
199 (%o3) [hashed, 1, [BAR], [FOO]]
200 @end group
201 @group
202 (%i4) listarray (bb);
203 3 2
204 (%o4) [(c - d) , (b + a) ]
205 @end group
206 @end example
208 @code{arrayinfo} and @mref{listarray} applied to a @mrefdot{memoizing function}
210 @c ===beg===
211 @c cc [x, y] := y / x;
212 @c cc [u, v];
213 @c cc [4, z];
214 @c arrayinfo (cc);
215 @c listarray (cc);
216 @c ===end===
217 @example
218 @group
219 (%i1) cc [x, y] := y / x;
220 y
221 (%o1) cc := -
222 x, y x
223 @end group
224 @group
225 (%i2) cc [u, v];
226 v
227 (%o2) -
228 u
229 @end group
230 @group
231 (%i3) cc [4, z];
232 z
233 (%o3) -
234 4
235 @end group
236 @group
237 (%i4) arrayinfo (cc);
238 (%o4) [hashed, 2, [4, z], [u, v]]
239 @end group
240 @group
241 (%i5) listarray (cc);
242 z v
243 (%o5) [-, -]
244 4 u
245 @end group
246 @end example
249 Using @code{arrayinfo} in order to convert an undeclared array to a declared array:
251 @c ===beg===
252 @c for i:0 thru 10 do a[i]:i^2$
253 @c indices:map(first,rest(rest(arrayinfo(a))));
254 @c array(A,fixnum,length(indices)-1)$
255 @c fillarray(A,map(lambda([x],a[x]),indices))$
256 @c listarray(A);
257 @c ===end===
258 @example
259 (%i1) for i:0 thru 10 do a[i]:i^2$
260 @group
261 (%i2) indices:map(first,rest(rest(arrayinfo(a))));
262 (%o2) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
263 @end group
264 (%i3) array(A,fixnum,length(indices)-1)$
265 (%i4) fillarray(A,map(lambda([x],a[x]),indices))$
266 @group
267 (%i5) listarray(A);
268 (%o5) [0, 1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
269 @end group
270 @end example
272 @code{arrayinfo} and @mref{listarray} applied to a subscripted function.
274 @c ===beg===
275 @c dd [x] (y) := y ^ x;
276 @c dd [a + b];
277 @c dd [v - u];
278 @c arrayinfo (dd);
279 @c listarray (dd);
280 @c ===end===
281 @example
282 @group
283 (%i1) dd [x] (y) := y ^ x;
284 x
285 (%o1) dd (y) := y
286 x
287 @end group
288 @group
289 (%i2) dd [a + b];
290 b + a
291 (%o2) lambda([y], y )
292 @end group
293 @group
294 (%i3) dd [v - u];
295 v - u
296 (%o3) lambda([y], y )
297 @end group
298 @group
299 (%i4) arrayinfo (dd);
300 (%o4) [hashed, 1, [b + a], [v - u]]
301 @end group
302 @group
303 (%i5) listarray (dd);
304 b + a v - u
305 (%o5) [lambda([y], y ), lambda([y], y )]
306 @end group
307 @end example
309 @opencatbox{Categories:}
310 @category{Arrays}
311 @closecatbox
312 @end deffn
314 @c -----------------------------------------------------------------------------
315 @anchor{arraymake}
316 @deffn {Function} arraymake (@var{A}, [@var{i_1}, @dots{}, @var{i_n}])
318 Returns the expression @code{@var{A}[@var{i_1}, ..., @var{i_n}]}.
319 The result is an unevaluated array reference.
321 @code{arraymake} is reminiscent of @mrefcomma{funmake} except the return value
322 is an unevaluated array reference instead of an unevaluated function call.
324 Examples:
325 @c ===beg===
326 @c arraymake (A, [1]);
327 @c arraymake (A, [k]);
328 @c arraymake (A, [i, j, 3]);
329 @c array (A, fixnum, 10);
330 @c fillarray (A, makelist (i^2, i, 1, 11));
331 @c arraymake (A, [5]);
332 @c ''%;
333 @c L : [a, b, c, d, e];
334 @c arraymake ('L, [n]);
335 @c ''%, n = 3;
336 @c A2 : make_array (fixnum, 10);
337 @c fillarray (A2, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
338 @c arraymake ('A2, [8]);
339 @c ''%;
340 @c ===end===
341 @example
342 @group
343 (%i1) arraymake (A, [1]);
344 (%o1) A
345 1
346 @end group
347 @group
348 (%i2) arraymake (A, [k]);
349 (%o2) A
350 k
351 @end group
352 @group
353 (%i3) arraymake (A, [i, j, 3]);
354 (%o3) A
355 i, j, 3
356 @end group
357 @group
358 (%i4) array (A, fixnum, 10);
359 (%o4) A
360 @end group
361 @group
362 (%i5) fillarray (A, makelist (i^2, i, 1, 11));
363 (%o5) A
364 @end group
365 @group
366 (%i6) arraymake (A, [5]);
367 (%o6) A
368 5
369 @end group
370 @group
371 (%i7) ''%;
372 (%o7) 36
373 @end group
374 @group
375 (%i8) L : [a, b, c, d, e];
376 (%o8) [a, b, c, d, e]
377 @end group
378 @group
379 (%i9) arraymake ('L, [n]);
380 (%o9) L
381 n
382 @end group
383 @group
384 (%i10) ''%, n = 3;
385 (%o10) c
386 @end group
387 @group
388 (%i11) A2 : make_array (fixnum, 10);
389 (%o11) @{Lisp Array: #(0 0 0 0 0 0 0 0 0 0)@}
390 @end group
391 @group
392 (%i12) fillarray (A2, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
393 (%o12) @{Lisp Array: #(1 2 3 4 5 6 7 8 9 10)@}
394 @end group
395 @group
396 (%i13) arraymake ('A2, [8]);
397 (%o13) A2
398 8
399 @end group
400 @group
401 (%i14) ''%;
402 (%o14) 9
403 @end group
404 @end example
406 @opencatbox{Categories:}
407 @category{Expressions}
408 @category{Arrays}
409 @closecatbox
410 @end deffn
412 @c -----------------------------------------------------------------------------
413 @anchor{arrays}
414 @defvr {System variable} arrays
415 Default value: @code{[]}
417 @code{arrays} is a list of arrays that have been allocated.
418 These comprise arrays declared by @mrefcomma{array} @mref{hashed arrays} that can be
419 constructed by implicit definition (assigning something to an element that isn't yet
420 declared as a list or an array),
421 and @mref{memoizing functions} defined by @code{:=} and @mrefdot{define}
422 Arrays defined by @mref{make_array} are not included.
424 See also
425 @mrefcomma{array} @mrefcomma{arrayapply} @mrefcomma{arrayinfo}@w{}
426 @mrefcomma{arraymake} @mrefcomma{fillarray} @mrefcomma{listarray} and
427 @mrefdot{rearray}
428 @c IS THIS AN EXHAUSTIVE LIST ??
430 Examples:
432 @c ===beg===
433 @c array (aa, 5, 7);
434 @c bb [FOO] : (a + b)^2;
435 @c cc [x] := x/100;
436 @c dd : make_array ('any, 7);
437 @c arrays;
438 @c ===end===
439 @example
440 @group
441 (%i1) array (aa, 5, 7);
442 (%o1) aa
443 @end group
444 @group
445 (%i2) bb [FOO] : (a + b)^2;
446 2
447 (%o2) (b + a)
448 @end group
449 @group
450 (%i3) cc [x] := x/100;
451 x
452 (%o3) cc := ---
453 x 100
454 @end group
455 @group
456 (%i4) dd : make_array ('any, 7);
457 (%o4) @{Lisp Array: #(NIL NIL NIL NIL NIL NIL NIL)@}
458 @end group
459 @group
460 (%i5) arrays;
461 (%o5) [aa, bb, cc]
462 @end group
463 @end example
465 @opencatbox{Categories:}
466 @category{Arrays}
467 @category{Global variables}
468 @closecatbox
469 @end defvr
471 @c -----------------------------------------------------------------------------
472 @anchor{arraysetapply}
473 @deffn {Function} arraysetapply (@var{A}, [@var{i_1}, @dots{}, @var{i_n}], @var{x})
475 Assigns @var{x} to @code{@var{A}[@var{i_1}, ..., @var{i_n}]},
476 where @var{A} is an array and @var{i_1}, @dots{}, @var{i_n} are integers.
478 @code{arraysetapply} evaluates its arguments.
480 @opencatbox{Categories:}
481 @category{Expressions}
482 @category{Arrays}
483 @closecatbox
484 @end deffn
486 @c -----------------------------------------------------------------------------
487 @anchor{fillarray}
488 @deffn {Function} fillarray (@var{A}, @var{B})
490 Fills array @var{A} from @var{B}, which is a list or an array.
492 If a specific type was declared for @var{A} when it was created,
493 it can only be filled with elements of that same type;
494 it is an error if an attempt is made to copy an element of a different type.
496 If the dimensions of the arrays @var{A} and @var{B} are
497 different, @var{A} is filled in row-major order. If there are not enough
498 elements in @var{B} the last element is used to fill out the
499 rest of @var{A}. If there are too many, the remaining ones are ignored.
501 @code{fillarray} returns its first argument.
503 Examples:
505 Create an array of 9 elements and fill it from a list.
507 @c ===beg===
508 @c array (a1, fixnum, 8);
509 @c listarray (a1);
510 @c fillarray (a1, [1, 2, 3, 4, 5, 6, 7, 8, 9]);
511 @c listarray (a1);
512 @c ===end===
513 @example
514 @group
515 (%i1) array (a1, fixnum, 8);
516 (%o1) a1
517 @end group
518 @group
519 (%i2) listarray (a1);
520 (%o2) [0, 0, 0, 0, 0, 0, 0, 0, 0]
521 @end group
522 @group
523 (%i3) fillarray (a1, [1, 2, 3, 4, 5, 6, 7, 8, 9]);
524 (%o3) a1
525 @end group
526 @group
527 (%i4) listarray (a1);
528 (%o4) [1, 2, 3, 4, 5, 6, 7, 8, 9]
529 @end group
530 @end example
532 When there are too few elements to fill the array,
533 the last element is repeated.
534 When there are too many elements,
535 the extra elements are ignored.
537 @c ===beg===
538 @c a2 : make_array (fixnum, 8);
539 @c fillarray (a2, [1, 2, 3, 4, 5]);
540 @c fillarray (a2, [4]);
541 @c fillarray (a2, makelist (i, i, 1, 100));
542 @c ===end===
543 @example
544 @group
545 (%i1) a2 : make_array (fixnum, 8);
546 (%o1) @{Lisp Array: #(0 0 0 0 0 0 0 0)@}
547 @end group
548 @group
549 (%i2) fillarray (a2, [1, 2, 3, 4, 5]);
550 (%o2) @{Lisp Array: #(1 2 3 4 5 5 5 5)@}
551 @end group
552 @group
553 (%i3) fillarray (a2, [4]);
554 (%o3) @{Lisp Array: #(4 4 4 4 4 4 4 4)@}
555 @end group
556 @group
557 (%i4) fillarray (a2, makelist (i, i, 1, 100));
558 (%o4) @{Lisp Array: #(1 2 3 4 5 6 7 8)@}
559 @end group
560 @end example
562 Multiple-dimension arrays are filled in row-major order.
564 @c ===beg===
565 @c a3 : make_array (fixnum, 2, 5);
566 @c fillarray (a3, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
567 @c a4 : make_array (fixnum, 5, 2);
568 @c fillarray (a4, a3);
569 @c ===end===
570 @example
571 @group
572 (%i1) a3 : make_array (fixnum, 2, 5);
573 (%o1) @{Lisp Array: #2A((0 0 0 0 0) (0 0 0 0 0))@}
574 @end group
575 @group
576 (%i2) fillarray (a3, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
577 (%o2) @{Lisp Array: #2A((1 2 3 4 5) (6 7 8 9 10))@}
578 @end group
579 @group
580 (%i3) a4 : make_array (fixnum, 5, 2);
581 (%o3) @{Lisp Array: #2A((0 0) (0 0) (0 0) (0 0) (0 0))@}
582 @end group
583 @group
584 (%i4) fillarray (a4, a3);
585 (%o4) @{Lisp Array: #2A((1 2) (3 4) (5 6) (7 8) (9 10))@}
586 @end group
587 @end example
589 @opencatbox{Categories:}
590 @category{Arrays}
591 @closecatbox
592 @end deffn
594 @c -----------------------------------------------------------------------------
595 @anchor{listarray}
596 @deffn {Function} listarray (@var{A})
598 Returns a list of the elements of the array @var{A}.
599 The argument @var{A} may be an array, an undeclared array (@mref{hashed array}),
600 a @mrefcomma{memoizing function} or a subscripted function.
602 Elements are listed in row-major order.
603 That is, elements are sorted according to the first index, then according to
604 the second index, and so on. The sorting order of index values is the same as
605 the order established by @mrefdot{orderless}
607 For undeclared arrays (@mref{hashed arrays}), @mrefcomma{memoizing functions} and subscripted functions,
608 the elements correspond to the index values returned by @mrefdot{arrayinfo}
610 Unbound elements of general arrays (that is, not @code{fixnum} and not
611 @code{flonum}) are returned as @code{#####}.
612 Unbound elements of @code{fixnum} or @code{flonum} arrays
613 are returned as 0 or 0.0, respectively.
614 Unbound elements of hashed arrays, @mrefcomma{memoizing functions}
615 and subscripted functions are not returned.
617 Examples:
619 @code{listarray} and @mref{arrayinfo} applied to a declared array.
621 @c ===beg===
622 @c array (aa, 2, 3);
623 @c aa [2, 3] : %pi;
624 @c aa [1, 2] : %e;
625 @c listarray (aa);
626 @c arrayinfo (aa);
627 @c ===end===
628 @example
629 @group
630 (%i1) array (aa, 2, 3);
631 (%o1) aa
632 @end group
633 @group
634 (%i2) aa [2, 3] : %pi;
635 (%o2) %pi
636 @end group
637 @group
638 (%i3) aa [1, 2] : %e;
639 (%o3) %e
640 @end group
641 @group
642 (%i4) listarray (aa);
643 (%o4) [#####, #####, #####, #####, #####, #####, %e, #####,
644 #####, #####, #####, %pi]
645 @end group
646 @group
647 (%i5) arrayinfo (aa);
648 (%o5) [declared, 2, [2, 3]]
649 @end group
650 @end example
652 @code{listarray} and @mref{arrayinfo} applied to an undeclared array (@mref{hashed array}).
654 @c ===beg===
655 @c bb [FOO] : (a + b)^2;
656 @c bb [BAR] : (c - d)^3;
657 @c listarray (bb);
658 @c arrayinfo (bb);
659 @c ===end===
660 @example
661 @group
662 (%i1) bb [FOO] : (a + b)^2;
663 2
664 (%o1) (b + a)
665 @end group
666 @group
667 (%i2) bb [BAR] : (c - d)^3;
668 3
669 (%o2) (c - d)
670 @end group
671 @group
672 (%i3) listarray (bb);
673 3 2
674 (%o3) [(c - d) , (b + a) ]
675 @end group
676 @group
677 (%i4) arrayinfo (bb);
678 (%o4) [hashed, 1, [BAR], [FOO]]
679 @end group
680 @end example
682 @code{listarray} and @mref{arrayinfo} applied to a @mrefdot{memoizing function}
684 @c ===beg===
685 @c cc [x, y] := y / x;
686 @c cc [u, v];
687 @c cc [4, z];
688 @c listarray (cc);
689 @c arrayinfo (cc);
690 @c ===end===
691 @example
692 @group
693 (%i1) cc [x, y] := y / x;
694 y
695 (%o1) cc := -
696 x, y x
697 @end group
698 @group
699 (%i2) cc [u, v];
700 v
701 (%o2) -
702 u
703 @end group
704 @group
705 (%i3) cc [4, z];
706 z
707 (%o3) -
708 4
709 @end group
710 @group
711 (%i4) listarray (cc);
712 z v
713 (%o4) [-, -]
714 4 u
715 @end group
716 @group
717 (%i5) arrayinfo (cc);
718 (%o5) [hashed, 2, [4, z], [u, v]]
719 @end group
720 @end example
722 @code{listarray} and @mref{arrayinfo} applied to a subscripted function.
724 @c ===beg===
725 @c dd [x] (y) := y ^ x;
726 @c dd [a + b];
727 @c dd [v - u];
728 @c listarray (dd);
729 @c arrayinfo (dd);
730 @c ===end===
731 @example
732 @group
733 (%i1) dd [x] (y) := y ^ x;
734 x
735 (%o1) dd (y) := y
736 x
737 @end group
738 @group
739 (%i2) dd [a + b];
740 b + a
741 (%o2) lambda([y], y )
742 @end group
743 @group
744 (%i3) dd [v - u];
745 v - u
746 (%o3) lambda([y], y )
747 @end group
748 @group
749 (%i4) listarray (dd);
750 b + a v - u
751 (%o4) [lambda([y], y ), lambda([y], y )]
752 @end group
753 @group
754 (%i5) arrayinfo (dd);
755 (%o5) [hashed, 1, [b + a], [v - u]]
756 @end group
757 @end example
759 @opencatbox{Categories:}
760 @category{Arrays}
761 @closecatbox
762 @end deffn
764 @c NEEDS CLARIFICATION
766 @c -----------------------------------------------------------------------------
767 @anchor{make_array}
768 @deffn {Function} make_array (@var{type}, @var{dim_1}, @dots{}, @var{dim_n})
770 Creates and returns a Lisp array. @var{type} may
771 be @code{any}, @code{flonum}, @code{fixnum}, @code{hashed} or
772 @code{functional}.
773 There are @math{n} indices,
774 and the @math{i}'th index runs from 0 to @math{@var{dim_i} - 1}.
776 The advantage of @code{make_array} over @mref{array} is that the return value
777 doesn't have a name, and once a pointer to it goes away, it will also go away.
778 For example, if @code{y: make_array (...)} then @code{y} points to an object
779 which takes up space, but after @code{y: false}, @code{y} no longer
780 points to that object, so the object can be garbage collected.
782 @c 'FUNCTIONAL ARGUMENT IN MAKE_ARRAY APPEARS TO BE BROKEN
783 @c EVEN AFTER READING THE CODE (SRC/AR.LISP) I CAN'T TELL HOW THIS IS SUPPOSED TO WORK
784 @c COMMENTING OUT THIS STUFF TO PREVENT CONFUSION AND HEARTBREAK
785 @c RESTORE IT WHEN MAKE_ARRAY ('FUNCTIONAL, ...) IS FIXED
786 @c @code{y: make_array ('functional, 'f, 'hashed, 1)} - the second argument to
787 @c @code{make_array} in this case is the function to call to calculate array
788 @c elements, and the rest of the arguments are passed recursively to
789 @c @code{make_array} to generate the "memory" for the array function object.
791 Examples:
793 @c ===beg===
794 @c A1 : make_array (fixnum, 10);
795 @c A1 [8] : 1729;
796 @c A1;
797 @c A2 : make_array (flonum, 10);
798 @c A2 [2] : 2.718281828;
799 @c A2;
800 @c A3 : make_array (any, 10);
801 @c A3 [4] : x - y - z;
802 @c A3;
803 @c A4 : make_array (fixnum, 2, 3, 5);
804 @c fillarray (A4, makelist (i, i, 1, 2*3*5));
805 @c A4 [0, 2, 1];
806 @c ===end===
807 @example
808 @group
809 (%i1) A1 : make_array (fixnum, 10);
810 (%o1) @{Lisp Array: #(0 0 0 0 0 0 0 0 0 0)@}
811 @end group
812 @group
813 (%i2) A1 [8] : 1729;
814 (%o2) 1729
815 @end group
816 @group
817 (%i3) A1;
818 (%o3) @{Lisp Array: #(0 0 0 0 0 0 0 0 1729 0)@}
819 @end group
820 @group
821 (%i4) A2 : make_array (flonum, 10);
822 (%o4) @{Lisp Array: #(0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0)@}
823 @end group
824 @group
825 (%i5) A2 [2] : 2.718281828;
826 (%o5) 2.718281828
827 @end group
828 @group
829 (%i6) A2;
830 (%o6)
831 @{Lisp Array: #(0.0 0.0 2.718281828 0.0 0.0 0.0 0.0 0.0 0.0 0.0)@}
832 @end group
833 @group
834 (%i7) A3 : make_array (any, 10);
835 (%o7) @{Lisp Array: #(NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)@}
836 @end group
837 @group
838 (%i8) A3 [4] : x - y - z;
839 (%o8) (- z) - y + x
840 @end group
841 @group
842 (%i9) A3;
843 (%o9) @{Lisp Array: #(NIL NIL NIL NIL
844 ((MPLUS SIMP) $X ((MTIMES SIMP) -1 $Y) ((MTIMES S\
845 IMP) -1 $Z))
846 NIL NIL NIL NIL NIL)@}
847 @end group
848 @group
849 (%i10) A4 : make_array (fixnum, 2, 3, 5);
850 (%o10) @{Lisp Array: #3A(((0 0 0 0 0) (0 0 0 0 0) (0 0 0 0 0))
851 ((0 0 0 0 0) (0 0 0 0 0) (0 0 0 0 0)))@}
852 @end group
853 @group
854 (%i11) fillarray (A4, makelist (i, i, 1, 2*3*5));
855 (%o11) @{Lisp Array: #3A(((1 2 3 4 5) (6 7 8 9 10) (11 12 13 14 1\
856 5))
857 ((16 17 18 19 20) (21 22 23 24 25) (26 27 28 29\
858 30)))@}
859 @end group
860 @group
861 (%i12) A4 [0, 2, 1];
862 (%o12) 12
863 @end group
864 @end example
866 @opencatbox{Categories:}
867 @category{Arrays}
868 @closecatbox
869 @end deffn
871 @c DOES THIS MODIFY A OR DOES IT CREATE A NEW ARRAY ??
873 @c -----------------------------------------------------------------------------
874 @anchor{rearray}
875 @deffn {Function} rearray (@var{A}, @var{dim_1}, @dots{}, @var{dim_n})
877 Changes the dimensions of an array.
878 The new array will be filled with the elements of the old one in
879 row-major order. If the old array was too small,
880 the remaining elements are filled with
881 @code{false}, @code{0.0} or @code{0},
882 depending on the type of the array. The type of the array cannot be
883 changed.
885 @opencatbox{Categories:}
886 @category{Arrays}
887 @closecatbox
888 @end deffn
890 @c -----------------------------------------------------------------------------
891 @anchor{remarray}
892 @deffn {Function} remarray @
893 @fname{remarray} (@var{A_1}, @dots{}, @var{A_n}) @
894 @fname{remarray} (all)
896 Removes arrays and array associated functions and frees the storage occupied.
897 The arguments may be declared arrays, @mrefcomma{hashed arrays} array
898 functions, and subscripted functions.
900 @code{remarray (all)} removes all items in the global list @mrefdot{arrays}
902 It may be necessary to use this function if it is
903 desired to clear the cache of a @mrefdot{memoizing function}
905 @code{remarray} returns the list of arrays removed.
907 @code{remarray} quotes its arguments.
909 @opencatbox{Categories:}
910 @category{Arrays}
911 @closecatbox
912 @end deffn
914 @c -----------------------------------------------------------------------------
915 @anchor{subvar}
916 @deffn {Function} subvar (@var{x}, @var{i})
918 Evaluates the subscripted expression @code{@var{x}[@var{i}]}.
920 @code{subvar} evaluates its arguments.
922 @code{arraymake (@var{x}, [@var{i}])} constructs the expression
923 @code{@var{x}[@var{i}]}, but does not evaluate it.
925 Examples:
927 @c ===beg===
928 @c x : foo $
929 @c i : 3 $
930 @c subvar (x, i);
931 @c foo : [aa, bb, cc, dd, ee]$
932 @c subvar (x, i);
933 @c arraymake (x, [i]);
934 @c ''%;
935 @c ===end===
936 @example
937 (%i1) x : foo $
938 (%i2) i : 3 $
939 @group
940 (%i3) subvar (x, i);
941 (%o3) foo
942 3
943 @end group
944 (%i4) foo : [aa, bb, cc, dd, ee]$
945 @group
946 (%i5) subvar (x, i);
947 (%o5) cc
948 @end group
949 @group
950 (%i6) arraymake (x, [i]);
951 (%o6) foo
952 3
953 @end group
954 @group
955 (%i7) ''%;
956 (%o7) cc
957 @end group
958 @end example
960 @opencatbox{Categories:}
961 @category{Expressions}
962 @category{Arrays}
963 @closecatbox
964 @end deffn
966 @c NEEDS EXPANSION AND EXAMPLES
968 @c -----------------------------------------------------------------------------
969 @anchor{subvarp}
970 @deffn {Function} subvarp (@var{expr})
972 Returns @code{true} if @var{expr} is a subscripted variable, for example
973 @code{a[i]}.
975 @opencatbox{Categories:}
976 @category{Predicate functions}
977 @closecatbox
978 @end deffn
980 @c -----------------------------------------------------------------------------
981 @anchor{use_fast_arrays}
982 @defvr {Option variable} use_fast_arrays
983 Default value: @code{false}
985 When @code{use_fast_arrays} is @code{true},
986 arrays declared by @code{array} are values instead of properties,
987 and undeclared arrays (@mref{hashed arrays}) are implemented as Lisp hashed arrays.
989 When @code{use_fast_arrays} is @code{false},
990 arrays declared by @code{array} are properties,
991 and undeclared arrays are implemented with Maxima's own hashed array implementation.
993 Note that the code @code{use_fast_arrays} switches to is not necessarily faster
994 than the default one; Arrays created by @mref{make_array} are not affected by
995 @code{use_fast_arrays}.
997 See also @mrefdot{translate_fast_arrays}
999 @opencatbox{Categories:}
1000 @category{Arrays}
1001 @category{Global flags}
1002 @closecatbox
1003 @end defvr
1005 @c -----------------------------------------------------------------------------
1006 @anchor{translate_fast_arrays}
1007 @defvr {Option variable} translate_fast_arrays
1008 Default value: @code{false}
1010 When @code{translate_fast_arrays} is @code{true},
1011 the Maxima-to-Lisp translator generates code that assumes arrays are values instead of properties,
1012 as if @code{use_fast_arrays} were @code{true}.
1014 When @code{translate_fast_arrays} is @code{false},
1015 the Maxima-to-Lisp translator generates code that assumes arrays are properties,
1016 as if @code{use_fast_arrays} were @code{false}.
1018 @opencatbox{Categories:}
1019 @category{Arrays}
1020 @category{Translation flags and variables}
1021 @closecatbox
1022 @end defvr