| blob | 7b7888247120104eae286ad169474da506a68ebc |
1 @c -----------------------------------------------------------------------------
2 @page
3 @node Lists, Arrays, Constants, Data Types and Structures
4 @section Lists
5 @c -----------------------------------------------------------------------------
7 @menu
8 * Introduction to Lists::
9 * Functions and Variables for Lists::
10 * Performance considerations for Lists::
11 @end menu
13 @c -----------------------------------------------------------------------------
14 @node Introduction to Lists, Functions and Variables for Lists, Lists, Lists
15 @subsection Introduction to Lists
16 @c -----------------------------------------------------------------------------
18 Lists are the basic building block for Maxima and Lisp. All data types
19 other than arrays, @mref{hashed arrays} and numbers are represented as Lisp lists,
20 These Lisp lists have the form
22 @example
23 ((MPLUS) $A 2)
24 @end example
26 @noindent
27 to indicate an expression @code{a+2}. At Maxima level one would see
28 the infix notation @code{a+2}. Maxima also has lists which are printed
29 as
31 @example
32 [1, 2, 7, x+y]
33 @end example
35 @noindent
36 for a list with 4 elements. Internally this corresponds to a Lisp list
37 of the form
39 @example
40 ((MLIST) 1 2 7 ((MPLUS) $X $Y))
41 @end example
43 @noindent
44 The flag which denotes the type field of the Maxima expression is a list
45 itself, since after it has been through the simplifier the list would become
47 @example
48 ((MLIST SIMP) 1 2 7 ((MPLUS SIMP) $X $Y))
49 @end example
51 @c -----------------------------------------------------------------------------
52 @node Functions and Variables for Lists, Performance considerations for Lists ,Introduction to Lists, Lists
53 @subsection Functions and Variables for Lists
54 @c -----------------------------------------------------------------------------
56 @c -----------------------------------------------------------------------------
57 @anchor{[}
58 @anchor{]}
59 @fnindex List delimiters
60 @fnindex Subscript operator
62 @defvr {Operator} [
63 @defvrx {Operator} ]
65 @code{[} and @code{]} mark the beginning and end, respectively, of a list.
67 @code{[} and @code{]} also enclose the subscripts of
68 a list, array, @mrefcomma{hashed array} or @mrefdot{memoizing function} Note that
69 other than for arrays accessing the @code{n}th element of a list
70 may need an amount of time that is roughly proportional to @code{n},
71 @xref{Performance considerations for Lists}.
73 Note that if an element of a subscripted variable is written to before
74 a list or an array of this name is declared a @mref{hashed array}
75 (@pxref{Arrays}) is created, not a list.
77 Examples:
79 @c ===beg===
80 @c x: [a, b, c];
81 @c x[3];
82 @c array (y, fixnum, 3);
83 @c y[2]: %pi;
84 @c y[2];
85 @c z['foo]: 'bar;
86 @c z['foo];
87 @c g[k] := 1/(k^2+1);
88 @c g[10];
89 @c ===end===
90 @example
91 @group
92 (%i1) x: [a, b, c];
93 (%o1) [a, b, c]
94 @end group
95 @group
96 (%i2) x[3];
97 (%o2) c
98 @end group
99 @group
100 (%i3) array (y, fixnum, 3);
101 (%o3) y
102 @end group
103 @group
104 (%i4) y[2]: %pi;
105 (%o4) %pi
106 @end group
107 @group
108 (%i5) y[2];
109 (%o5) %pi
110 @end group
111 @group
112 (%i6) z['foo]: 'bar;
113 (%o6) bar
114 @end group
115 @group
116 (%i7) z['foo];
117 (%o7) bar
118 @end group
119 @group
120 (%i8) g[k] := 1/(k^2+1);
121 1
122 (%o8) g := ------
123 k 2
124 k + 1
125 @end group
126 @group
127 (%i9) g[10];
128 1
129 (%o9) ---
130 101
131 @end group
132 @end example
134 @opencatbox{Categories:}
135 @category{Lists}
136 @category{Operators}
137 @closecatbox
138 @end defvr
140 @c NEED ANOTHER deffn FOR GENERAL EXPRESSIONS ARGUMENTS
141 @c NEEDS CLARIFICATION AND EXAMPLES
143 @c -----------------------------------------------------------------------------
144 @anchor{append}
145 @deffn {Function} append (@var{list_1}, @dots{}, @var{list_n})
147 Returns a single list of the elements of @var{list_1} followed
148 by the elements of @var{list_2}, @dots{} @code{append} also works on
149 general expressions, e.g. @code{append (f(a,b), f(c,d,e));} yields
150 @code{f(a,b,c,d,e)}.
152 See also @mrefcomma{addrow} @mref{addcol} and @mrefdot{join}
154 Do @code{example(append);} for an example.
156 @opencatbox{Categories:}
157 @category{Lists}
158 @category{Expressions}
159 @closecatbox
160 @end deffn
162 @c NEEDS CLARIFICATION AND EXAMPLES
164 @c -----------------------------------------------------------------------------
165 @anchor{assoc}
166 @deffn {Function} assoc @
167 @fname{assoc} (@var{key}, @var{e}, @var{default}) @
168 @fname{assoc} (@var{key}, @var{e})
170 @code{assoc} searches for @var{key} as the first part of an argument of @var{e}
171 and returns the second part of the first match, if any.
173 @var{key} may be any expression.
174 @var{e} must be a nonatomic expression,
175 and every argument of @var{e} must have exactly two parts.
176 @code{assoc} returns the second part of the first matching argument of @var{e}.
177 Matches are determined by @code{is(@var{key} = first(@var{a}))}
178 where @var{a} is an argument of @var{e}.
180 If there are two or more matches, only the first is returned.
181 If there are no matches, @var{default} is returned, if specified.
182 Otherwise, @code{false} is returned.
184 See also @mref{sublist} and @mrefdot{member}
186 Examples:
188 @var{key} may be any expression.
189 @var{e} must be a nonatomic expression,
190 and every argument of @var{e} must have exactly two parts.
191 @code{assoc} returns the second part of the first matching argument of @var{e}.
193 @c ===beg===
194 @c assoc (f(x), foo(g(x) = y, f(x) = z + 1, h(x) = 2*u));
195 @c ===end===
196 @example
197 @group
198 (%i1) assoc (f(x), foo(g(x) = y, f(x) = z + 1, h(x) = 2*u));
199 (%o1) z + 1
200 @end group
201 @end example
203 If there are two or more matches, only the first is returned.
205 @c ===beg===
206 @c assoc (yy, [xx = 111, yy = 222, yy = 333, yy = 444]);
207 @c ===end===
208 @example
209 @group
210 (%i1) assoc (yy, [xx = 111, yy = 222, yy = 333, yy = 444]);
211 (%o1) 222
212 @end group
213 @end example
215 If there are no matches, @var{default} is returned, if specified.
216 Otherwise, @code{false} is returned.
218 @c ===beg===
219 @c assoc (abc, [[x, 111], [y, 222], [z, 333]], none);
220 @c assoc (abc, [[x, 111], [y, 222], [z, 333]]);
221 @c ===end===
222 @example
223 @group
224 (%i1) assoc (abc, [[x, 111], [y, 222], [z, 333]], none);
225 (%o1) none
226 (%i2) assoc (abc, [[x, 111], [y, 222], [z, 333]]);
227 (%o2) false
228 @end group
229 @end example
231 @opencatbox{Categories:}
232 @category{Lists}
233 @category{Expressions}
234 @closecatbox
235 @end deffn
238 @c -----------------------------------------------------------------------------
239 @anchor{cons}
240 @deffn {Function} cons @
241 @fname{cons} (@var{expr}, @var{list}) @
242 @fname{cons} (@var{expr_1}, @var{expr_2})
244 @code{cons (@var{expr}, @var{list})} returns a new list constructed of the element
245 @var{expr} as its first element, followed by the elements of @var{list}. This is
246 analogous to the Lisp language construction operation "cons".
248 The Maxima function @code{cons} can also be used where the second argument is other
249 than a list and this might be useful. In this case, @code{cons (@var{expr_1}, @var{expr_2})}
250 returns an expression with same operator as @var{expr_2} but with argument @code{cons(expr_1, args(expr_2))}.
251 Examples:
253 @c ===beg===
254 @c cons(a,[b,c,d]);
255 @c cons(a,f(b,c,d));
256 @c ===end===
257 @example
258 @group
259 (%i1) cons(a,[b,c,d]);
260 (%o1) [a, b, c, d]
261 @end group
262 @group
263 (%i2) cons(a,f(b,c,d));
264 (%o2) f(a, b, c, d)
265 @end group
266 @end example
268 In general, @code{cons} applied to a nonlist doesn't make sense. For instance, @code{cons(a,b^c)}
269 results in an illegal expression, since '^' cannot take three arguments.
271 When @code{inflag} is true, @code{cons} operates on the internal structure of an expression, otherwise
272 @code{cons} operates on the displayed form. Especially when @code{inflag} is true, @code{cons} applied
273 to a nonlist sometimes gives a surprising result; for example
275 @c ===beg===
276 @c cons(a,-a), inflag : true;
277 @c cons(a,-a), inflag : false;
278 @c ===end===
279 @example
280 @group
281 (%i1) cons(a,-a), inflag : true;
282 2
283 (%o1) - a
284 @end group
285 @group
286 (%i2) cons(a,-a), inflag : false;
287 (%o2) 0
288 @end group
289 @end example
291 @opencatbox{Categories:}
292 @category{Lists}
293 @category{Expressions}
294 @closecatbox
295 @end deffn
297 @c -----------------------------------------------------------------------------
298 @anchor{copylist}
299 @deffn {Function} copylist (@var{list})
301 Returns a copy of the list @var{list}.
303 @opencatbox{Categories:}
304 @category{Lists}
305 @closecatbox
306 @end deffn
308 @c -----------------------------------------------------------------------------
309 @anchor{create_list}
310 @deffn {Function} create_list (@var{form}, @var{x_1}, @var{list_1}, @dots{}, @var{x_n}, @var{list_n})
312 Create a list by evaluating @var{form} with @var{x_1} bound to
313 each element of @var{list_1}, and for each such binding bind @var{x_2}
314 to each element of @var{list_2}, @dots{}
315 The number of elements in the result will be
316 the product of the number of elements in each list.
317 Each variable @var{x_i} must actually be a symbol -- it will not be evaluated.
318 The list arguments will be evaluated once at the beginning of the
319 iteration.
321 @c ===beg===
322 @c create_list (x^i, i, [1, 3, 7]);
323 @c ===end===
324 @example
325 @group
326 (%i1) create_list (x^i, i, [1, 3, 7]);
327 3 7
328 (%o1) [x, x , x ]
329 @end group
330 @end example
332 @noindent
333 With a double iteration:
335 @c ===beg===
336 @c create_list ([i, j], i, [a, b], j, [e, f, h]);
337 @c ===end===
338 @example
339 @group
340 (%i1) create_list ([i, j], i, [a, b], j, [e, f, h]);
341 (%o1) [[a, e], [a, f], [a, h], [b, e], [b, f], [b, h]]
342 @end group
343 @end example
345 Instead of @var{list_i} two args may be supplied each of which should
346 evaluate to a number. These will be the inclusive lower and
347 upper bounds for the iteration.
349 @c ===beg===
350 @c create_list ([i, j], i, [1, 2, 3], j, 1, i);
351 @c ===end===
352 @example
353 @group
354 (%i1) create_list ([i, j], i, [1, 2, 3], j, 1, i);
355 (%o1) [[1, 1], [2, 1], [2, 2], [3, 1], [3, 2], [3, 3]]
356 @end group
357 @end example
359 Note that the limits or list for the @code{j} variable can
360 depend on the current value of @code{i}.
362 @opencatbox{Categories:}
363 @category{Lists}
364 @closecatbox
365 @end deffn
367 @c -----------------------------------------------------------------------------
368 @anchor{delete}
369 @deffn {Function} delete @
370 @fname{delete} (@var{expr_1}, @var{expr_2}) @
371 @fname{delete} (@var{expr_1}, @var{expr_2}, @var{n})
373 @code{delete(@var{expr_1}, @var{expr_2})}
374 removes from @var{expr_2} any arguments of its top-level operator
375 which are the same (as determined by "=") as @var{expr_1}.
376 Note that "=" tests for formal equality, not equivalence.
377 Note also that arguments of subexpressions are not affected.
379 @var{expr_1} may be an atom or a non-atomic expression.
380 @var{expr_2} may be any non-atomic expression.
381 @code{delete} returns a new expression;
382 it does not modify @var{expr_2}.
384 @code{delete(@var{expr_1}, @var{expr_2}, @var{n})}
385 removes from @var{expr_2} the first @var{n} arguments of the top-level operator
386 which are the same as @var{expr_1}.
387 If there are fewer than @var{n} such arguments,
388 then all such arguments are removed.
390 Examples:
392 Removing elements from a list.
394 @c ===beg===
395 @c delete (y, [w, x, y, z, z, y, x, w]);
396 @c ===end===
397 @example
398 @group
399 (%i1) delete (y, [w, x, y, z, z, y, x, w]);
400 (%o1) [w, x, z, z, x, w]
401 @end group
402 @end example
404 Removing terms from a sum.
406 @c ===beg===
407 @c delete (sin(x), x + sin(x) + y);
408 @c ===end===
409 @example
410 @group
411 (%i1) delete (sin(x), x + sin(x) + y);
412 (%o1) y + x
413 @end group
414 @end example
416 Removing factors from a product.
418 @c ===beg===
419 @c delete (u - x, (u - w)*(u - x)*(u - y)*(u - z));
420 @c ===end===
421 @example
422 @group
423 (%i1) delete (u - x, (u - w)*(u - x)*(u - y)*(u - z));
424 (%o1) (u - w) (u - y) (u - z)
425 @end group
426 @end example
428 Removing arguments from an arbitrary expression.
430 @c ===beg===
431 @c delete (a, foo (a, b, c, d, a));
432 @c ===end===
433 @example
434 @group
435 (%i1) delete (a, foo (a, b, c, d, a));
436 (%o1) foo(b, c, d)
437 @end group
438 @end example
440 Limit the number of removed arguments.
442 @c ===beg===
443 @c delete (a, foo (a, b, a, c, d, a), 2);
444 @c ===end===
445 @example
446 @group
447 (%i1) delete (a, foo (a, b, a, c, d, a), 2);
448 (%o1) foo(b, c, d, a)
449 @end group
450 @end example
452 Whether arguments are the same as @var{expr_1} is determined by "=".
453 Arguments which are @code{equal} but not "=" are not removed.
455 @c ===beg===
456 @c [is (equal (0, 0)), is (equal (0, 0.0)), is (equal (0, 0b0))];
457 @c [is (0 = 0), is (0 = 0.0), is (0 = 0b0)];
458 @c delete (0, [0, 0.0, 0b0]);
459 @c is (equal ((x + y)*(x - y), x^2 - y^2));
460 @c is ((x + y)*(x - y) = x^2 - y^2);
461 @c delete ((x + y)*(x - y), [(x + y)*(x - y), x^2 - y^2]);
462 @c ===end===
463 @example
464 @group
465 (%i1) [is (equal (0, 0)), is (equal (0, 0.0)), is (equal (0, 0b0))];
466 (%o1) [true, true, true]
467 @end group
468 @group
469 (%i2) [is (0 = 0), is (0 = 0.0), is (0 = 0b0)];
470 (%o2) [true, false, false]
471 @end group
472 @group
473 (%i3) delete (0, [0, 0.0, 0b0]);
474 (%o3) [0.0, 0.0b0]
475 @end group
476 @group
477 (%i4) is (equal ((x + y)*(x - y), x^2 - y^2));
478 (%o4) true
479 @end group
480 @group
481 (%i5) is ((x + y)*(x - y) = x^2 - y^2);
482 (%o5) false
483 @end group
484 @group
485 (%i6) delete ((x + y)*(x - y), [(x + y)*(x - y), x^2 - y^2]);
486 2 2
487 (%o6) [x - y ]
488 @end group
489 @end example
491 @opencatbox{Categories:}
492 @category{Lists}
493 @category{Expressions}
494 @closecatbox
495 @end deffn
497 @c -----------------------------------------------------------------------------
498 @anchor{eighth}
499 @deffn {Function} eighth (@var{expr})
501 Returns the 8th item of expression or list @var{expr}.
502 See @mref{first} for more details.
504 @opencatbox{Categories:}
505 @category{Lists}
506 @category{Expressions}
507 @closecatbox
508 @end deffn
511 @c -----------------------------------------------------------------------------
512 @anchor{endcons}
513 @deffn {Function} endcons @
514 @fname{endcons} (@var{expr}, @var{list}) @
515 @fname{endcons} (@var{expr_1}, @var{expr_2})
517 @code{endcons (@var{expr}, @var{list})} returns a new list constructed of the elements of
518 @var{list} followed by @var{expr}. The Maxima function @code{endcons} can also be used where
519 the second argument is other than a list and this might be useful. In this case,
520 @code{endcons (@var{expr_1}, @var{expr_2})} returns an expression with same operator as
521 @var{expr_2} but with argument @code{endcons(expr_1, args(expr_2))}. Examples:
523 @c ===beg===
524 @c endcons(a,[b,c,d]);
525 @c endcons(a,f(b,c,d));
526 @c ===end===
527 @example
528 @group
529 (%i1) endcons(a,[b,c,d]);
530 (%o1) [b, c, d, a]
531 @end group
532 @group
533 (%i2) endcons(a,f(b,c,d));
534 (%o2) f(b, c, d, a)
535 @end group
536 @end example
538 In general, @code{endcons} applied to a nonlist doesn't make sense. For instance, @code{endcons(a,b^c)}
539 results in an illegal expression, since '^' cannot take three arguments.
541 When @code{inflag} is true, @code{endcons} operates on the internal structure of an expression, otherwise
542 @code{endcons} operates on the displayed form. Especially when @code{inflag} is true, @code{endcons} applied
543 to a nonlist sometimes gives a surprising result; for example
545 @c ===beg===
546 @c endcons(a,-a), inflag : true;
547 @c endcons(a,-a), inflag : false;
548 @c ===end===
549 @example
550 @group
551 (%i1) endcons(a,-a), inflag : true;
552 2
553 (%o1) - a
554 @end group
555 @group
556 (%i2) endcons(a,-a), inflag : false;
557 (%o2) 0
558 @end group
559 @end example
561 @opencatbox{Categories:}
562 @category{Lists}
563 @category{Expressions}
564 @closecatbox
565 @end deffn
568 @c -----------------------------------------------------------------------------
569 @anchor{fifth}
570 @deffn {Function} fifth (@var{expr})
572 Returns the 5th item of expression or list @var{expr}.
573 See @mref{first} for more details.
575 @opencatbox{Categories:}
576 @category{Lists}
577 @category{Expressions}
578 @closecatbox
579 @end deffn
581 @c -----------------------------------------------------------------------------
582 @anchor{first}
583 @deffn {Function} first (@var{expr})
585 Returns the first part of @var{expr} which may result in the first element of a
586 list, the first row of a matrix, the first term of a sum, etc.:
588 @example
589 @group
590 (%i1) matrix([1,2],[3,4]);
591 [ 1 2 ]
592 (%o1) [ ]
593 [ 3 4 ]
594 (%i2) first(%);
595 (%o2) [1,2]
596 (%i3) first(%);
597 (%o3) 1
598 (%i4) first(a*b/c+d+e/x);
599 a b
600 (%o4) ---
601 c
602 (%i5) first(a=b/c+d+e/x);
603 (%o5) a
604 @end group
605 @end example
607 Note that
608 @code{first} and its related functions, @code{rest} and @code{last}, work
609 on the form of @var{expr} which is displayed not the form which is typed on
610 input. If the variable @mref{inflag} is set to @code{true} however, these
611 functions will look at the internal form of @var{expr}. One reason why this may
612 make a difference is that the simplifier re-orders expressions:
614 @example
615 @group
616 (%i1) x+y;
617 (%o1) y+1
618 (%i2) first(x+y),inflag : true;
619 (%o2) x
620 (%i3) first(x+y),inflag : false;
621 (%o3) y
622 @end group
623 @end example
625 The functions @code{second} @dots{}
626 @code{tenth} yield the second through the tenth part of their input argument.
628 See also @mref{firstn} and @mrefdot{part}
630 @opencatbox{Categories:}
631 @category{Lists}
632 @category{Expressions}
633 @closecatbox
634 @end deffn
636 @c -----------------------------------------------------------------------------
637 @anchor{firstn}
638 @deffn {Function} firstn (@var{expr}, @var{count})
640 Returns the first @var{count} arguments of @var{expr}, if @var{expr} has at least @var{count} arguments.
641 Returns @var{expr} if @var{expr} has less than @var{count} arguments.
643 @var{expr} may be any nonatomic expression.
644 When @var{expr} is something other than a list,
645 @code{firstn} returns an expression which has the same operator as @var{expr}.
646 @var{count} must be a nonnegative integer.
648 @code{firstn} honors the global flag @code{inflag},
649 which governs whether the internal form of an expression is processed (when @code{inflag} is true)
650 or the displayed form (when @code{inflag} is false).
652 Note that @code{firstn(@var{expr}, 1)},
653 which returns a nonatomic expression containing the first argument,
654 is not the same as @code{first(@var{expr})},
655 which returns the first argument by itself.
657 See also @mref{lastn} and @mrefdot{rest}
659 Examples:
661 @code{firstn} returns the first @var{count} elements of @var{expr}, if @var{expr} has at least @var{count} elements.
663 @c ===beg===
664 @c mylist : [1, a, 2, b, 3, x, 4 - y, 2*z + sin(u)];
665 @c firstn (mylist, 0);
666 @c firstn (mylist, 1);
667 @c firstn (mylist, 2);
668 @c firstn (mylist, 7);
669 @c ===end===
670 @example
671 @group
672 (%i1) mylist : [1, a, 2, b, 3, x, 4 - y, 2*z + sin(u)];
673 (%o1) [1, a, 2, b, 3, x, 4 - y, 2 z + sin(u)]
674 @end group
675 @group
676 (%i2) firstn (mylist, 0);
677 (%o2) []
678 @end group
679 @group
680 (%i3) firstn (mylist, 1);
681 (%o3) [1]
682 @end group
683 @group
684 (%i4) firstn (mylist, 2);
685 (%o4) [1, a]
686 @end group
687 @group
688 (%i5) firstn (mylist, 7);
689 (%o5) [1, a, 2, b, 3, x, 4 - y]
690 @end group
691 @end example
693 @code{firstn} returns @var{expr} if @var{expr} has less than @var{count} elements.
695 @c ===beg===
696 @c mylist : [1, a, 2, b, 3, x, 4 - y, 2*z + sin(u)];
697 @c firstn (mylist, 100);
698 @c ===end===
699 @example
700 @group
701 (%i1) mylist : [1, a, 2, b, 3, x, 4 - y, 2*z + sin(u)];
702 (%o1) [1, a, 2, b, 3, x, 4 - y, 2 z + sin(u)]
703 @end group
704 @group
705 (%i2) firstn (mylist, 100);
706 (%o2) [1, a, 2, b, 3, x, 4 - y, 2 z + sin(u)]
707 @end group
708 @end example
710 @var{expr} may be any nonatomic expression.
712 @c ===beg===
713 @c myfoo : foo(1, a, 2, b, 3, x, 4 - y, 2*z + sin(u));
714 @c firstn (myfoo, 4);
715 @c mybar : bar[m, n](1, a, 2, b, 3, x, 4 - y, 2*z + sin(u));
716 @c firstn (mybar, 4);
717 @c mymatrix : genmatrix (lambda ([i, j], 10*i + j), 10, 4) $
718 @c firstn (mymatrix, 3);
719 @c ===end===
720 @example
721 @group
722 (%i1) myfoo : foo(1, a, 2, b, 3, x, 4 - y, 2*z + sin(u));
723 (%o1) foo(1, a, 2, b, 3, x, 4 - y, 2 z + sin(u))
724 @end group
725 @group
726 (%i2) firstn (myfoo, 4);
727 (%o2) foo(1, a, 2, b)
728 @end group
729 @group
730 (%i3) mybar : bar[m, n](1, a, 2, b, 3, x, 4 - y, 2*z + sin(u));
731 (%o3) bar (1, a, 2, b, 3, x, 4 - y, 2 z + sin(u))
732 m, n
733 @end group
734 @group
735 (%i4) firstn (mybar, 4);
736 (%o4) bar (1, a, 2, b)
737 m, n
738 @end group
739 (%i5) mymatrix : genmatrix (lambda ([i, j], 10*i + j), 10, 4) $
740 @group
741 (%i6) firstn (mymatrix, 3);
742 [ 11 12 13 14 ]
743 [ ]
744 (%o6) [ 21 22 23 24 ]
745 [ ]
746 [ 31 32 33 34 ]
747 @end group
748 @end example
750 @code{firstn} honors the global flag @code{inflag}.
752 @c ===beg===
753 @c myexpr : a + b + c + d + e;
754 @c firstn (myexpr, 3), inflag=true;
755 @c firstn (myexpr, 3), inflag=false;
756 @c ===end===
757 @example
758 @group
759 (%i1) myexpr : a + b + c + d + e;
760 (%o1) e + d + c + b + a
761 @end group
762 @group
763 (%i2) firstn (myexpr, 3), inflag=true;
764 (%o2) c + b + a
765 @end group
766 @group
767 (%i3) firstn (myexpr, 3), inflag=false;
768 (%o3) e + d + c
769 @end group
770 @end example
772 Note that @code{firstn(@var{expr}, 1)} is not the same as @code{first(@var{expr})}.
774 @c ===beg===
775 @c firstn ([w, x, y, z], 1);
776 @c first ([w, x, y, z]);
777 @c ===end===
778 @example
779 @group
780 (%i1) firstn ([w, x, y, z], 1);
781 (%o1) [w]
782 @end group
783 @group
784 (%i2) first ([w, x, y, z]);
785 (%o2) w
786 @end group
787 @end example
789 @opencatbox{Categories:}
790 @category{Lists}
791 @category{Expressions}
792 @closecatbox
793 @end deffn
795 @c -----------------------------------------------------------------------------
796 @anchor{fourth}
797 @deffn {Function} fourth (@var{expr})
799 Returns the 4th item of expression or list @var{expr}.
800 See @mref{first} for more details.
802 @opencatbox{Categories:}
803 @category{Lists}
804 @category{Expressions}
805 @closecatbox
806 @end deffn
808 @c -----------------------------------------------------------------------------
809 @anchor{join}
810 @deffn {Function} join (@var{l}, @var{m})
812 Creates a new list containing the elements of lists @var{l} and @var{m},
813 interspersed. The result has elements @code{[@var{l}[1], @var{m}[1],
814 @var{l}[2], @var{m}[2], ...]}. The lists @var{l} and @var{m} may contain any
815 type of elements.
817 If the lists are different lengths, @code{join} ignores elements of the longer
818 list.
820 Maxima complains if @var{l} or @var{m} is not a list.
822 See also @mrefdot{append}
824 Examples:
826 @c ===beg===
827 @c L1: [a, sin(b), c!, d - 1];
828 @c join (L1, [1, 2, 3, 4]);
829 @c join (L1, [aa, bb, cc, dd, ee, ff]);
830 @c ===end===
831 @example
832 @group
833 (%i1) L1: [a, sin(b), c!, d - 1];
834 (%o1) [a, sin(b), c!, d - 1]
835 @end group
836 @group
837 (%i2) join (L1, [1, 2, 3, 4]);
838 (%o2) [a, 1, sin(b), 2, c!, 3, d - 1, 4]
839 @end group
840 @group
841 (%i3) join (L1, [aa, bb, cc, dd, ee, ff]);
842 (%o3) [a, aa, sin(b), bb, c!, cc, d - 1, dd]
843 @end group
844 @end example
846 @opencatbox{Categories:}
847 @category{Lists}
848 @closecatbox
849 @end deffn
851 @c NEEDS EXAMPLES
852 @c HOW IS "LAST" PART DETERMINED ??
854 @c -----------------------------------------------------------------------------
855 @anchor{last}
856 @deffn {Function} last (@var{expr})
858 Returns the last part (term, row, element, etc.) of the @var{expr}.
860 See also @mrefdot{lastn}
862 @opencatbox{Categories:}
863 @category{Lists}
864 @category{Expressions}
865 @closecatbox
866 @end deffn
868 @c NEEDS CLARIFICATION AND EXAMPLES
870 @c -----------------------------------------------------------------------------
871 @anchor{lastn}
872 @deffn {Function} lastn (@var{expr}, @var{count})
874 Returns the last @var{count} arguments of @var{expr}, if @var{expr} has at least @var{count} arguments.
875 Returns @var{expr} if @var{expr} has less than @var{count} arguments.
877 @var{expr} may be any nonatomic expression.
878 When @var{expr} is something other than a list,
879 @code{lastn} returns an expression which has the same operator as @var{expr}.
880 @var{count} must be a nonnegative integer.
882 @code{lastn} honors the global flag @code{inflag},
883 which governs whether the internal form of an expression is processed (when @code{inflag} is true)
884 or the displayed form (when @code{inflag} is false).
886 Note that @code{lastn(@var{expr}, 1)},
887 which returns a nonatomic expression containing the last argument,
888 is not the same as @code{last(@var{expr})},
889 which returns the last argument by itself.
891 See also @mref{firstn} and @mrefdot{rest}
893 Examples:
895 @code{lastn} returns the last @var{count} elements of @var{expr}, if @var{expr} has at least @var{count} elements.
897 @c ===beg===
898 @c mylist : [1, a, 2, b, 3, x, 4 - y, 2*z + sin(u)];
899 @c lastn (mylist, 0);
900 @c lastn (mylist, 1);
901 @c lastn (mylist, 2);
902 @c lastn (mylist, 7);
903 @c ===end===
904 @example
905 @group
906 (%i1) mylist : [1, a, 2, b, 3, x, 4 - y, 2*z + sin(u)];
907 (%o1) [1, a, 2, b, 3, x, 4 - y, 2 z + sin(u)]
908 @end group
909 @group
910 (%i2) lastn (mylist, 0);
911 (%o2) []
912 @end group
913 @group
914 (%i3) lastn (mylist, 1);
915 (%o3) [2 z + sin(u)]
916 @end group
917 @group
918 (%i4) lastn (mylist, 2);
919 (%o4) [4 - y, 2 z + sin(u)]
920 @end group
921 @group
922 (%i5) lastn (mylist, 7);
923 (%o5) [a, 2, b, 3, x, 4 - y, 2 z + sin(u)]
924 @end group
925 @end example
927 @code{lastn} returns @var{expr} if @var{expr} has less than @var{count} elements.
929 @c ===beg===
930 @c mylist : [1, a, 2, b, 3, x, 4 - y, 2*z + sin(u)];
931 @c lastn (mylist, 100);
932 @c ===end===
933 @example
934 @group
935 (%i1) mylist : [1, a, 2, b, 3, x, 4 - y, 2*z + sin(u)];
936 (%o1) [1, a, 2, b, 3, x, 4 - y, 2 z + sin(u)]
937 @end group
938 @group
939 (%i2) lastn (mylist, 100);
940 (%o2) [1, a, 2, b, 3, x, 4 - y, 2 z + sin(u)]
941 @end group
942 @end example
944 @var{expr} may be any nonatomic expression.
946 @c ===beg===
947 @c myfoo : foo(1, a, 2, b, 3, x, 4 - y, 2*z + sin(u));
948 @c lastn (myfoo, 4);
949 @c mybar : bar[m, n](1, a, 2, b, 3, x, 4 - y, 2*z + sin(u));
950 @c lastn (mybar, 4);
951 @c mymatrix : genmatrix (lambda ([i, j], 10*i + j), 10, 4) $
952 @c lastn (mymatrix, 3);
953 @c ===end===
954 @example
955 @group
956 (%i1) myfoo : foo(1, a, 2, b, 3, x, 4 - y, 2*z + sin(u));
957 (%o1) foo(1, a, 2, b, 3, x, 4 - y, 2 z + sin(u))
958 @end group
959 @group
960 (%i2) lastn (myfoo, 4);
961 (%o2) foo(3, x, 4 - y, 2 z + sin(u))
962 @end group
963 @group
964 (%i3) mybar : bar[m, n](1, a, 2, b, 3, x, 4 - y, 2*z + sin(u));
965 (%o3) bar (1, a, 2, b, 3, x, 4 - y, 2 z + sin(u))
966 m, n
967 @end group
968 @group
969 (%i4) lastn (mybar, 4);
970 (%o4) bar (3, x, 4 - y, 2 z + sin(u))
971 m, n
972 @end group
973 (%i5) mymatrix : genmatrix (lambda ([i, j], 10*i + j), 10, 4) $
974 @group
975 (%i6) lastn (mymatrix, 3);
976 [ 81 82 83 84 ]
977 [ ]
978 (%o6) [ 91 92 93 94 ]
979 [ ]
980 [ 101 102 103 104 ]
981 @end group
982 @end example
984 @code{lastn} honors the global flag @code{inflag}.
986 @c ===beg===
987 @c myexpr : a + b + c + d + e;
988 @c lastn (myexpr, 3), inflag=true;
989 @c lastn (myexpr, 3), inflag=false;
990 @c ===end===
991 @example
992 @group
993 (%i1) myexpr : a + b + c + d + e;
994 (%o1) e + d + c + b + a
995 @end group
996 @group
997 (%i2) lastn (myexpr, 3), inflag=true;
998 (%o2) e + d + c
999 @end group
1000 @group
1001 (%i3) lastn (myexpr, 3), inflag=false;
1002 (%o3) c + b + a
1003 @end group
1004 @end example
1006 Note that @code{lastn(@var{expr}, 1)} is not the same as @code{last(@var{expr})}.
1008 @c ===beg===
1009 @c lastn ([w, x, y, z], 1);
1010 @c last ([w, x, y, z]);
1011 @c ===end===
1012 @example
1013 @group
1014 (%i1) lastn ([w, x, y, z], 1);
1015 (%o1) [z]
1016 @end group
1017 @group
1018 (%i2) last ([w, x, y, z]);
1019 (%o2) z
1020 @end group
1021 @end example
1023 @opencatbox{Categories:}
1024 @category{Lists}
1025 @category{Expressions}
1026 @closecatbox
1027 @end deffn
1029 @c -----------------------------------------------------------------------------
1030 @anchor{length}
1031 @deffn {Function} length (@var{expr})
1033 Returns (by default) the number of parts in the external
1034 (displayed) form of @var{expr}. For lists this is the number of elements,
1035 for matrices it is the number of rows, and for sums it is the number
1036 of terms (see @mref{dispform}).
1038 The @code{length} command is affected by the @mref{inflag} switch. So, e.g.
1039 @code{length(a/(b*c));} gives 2 if @code{inflag} is @code{false} (Assuming
1040 @mref{exptdispflag} is @code{true}), but 3 if @code{inflag} is @code{true} (the
1041 internal representation is essentially @code{a*b^-1*c^-1}).
1043 Determining a list's length typically needs an amount of time proportional
1044 to the number of elements in the list. If the length of a list is used inside
1045 a loop it therefore might drastically increase the performance if the length
1046 is calculated outside the loop instead.
1048 @opencatbox{Categories:}
1049 @category{Lists}
1050 @category{Expressions}
1051 @closecatbox
1052 @end deffn
1054 @c -----------------------------------------------------------------------------
1055 @anchor{listarith}
1056 @defvr {Option variable} listarith
1057 Default value: @code{true}
1059 If @code{false} causes any arithmetic operations with lists to be suppressed;
1060 when @code{true}, list-matrix operations are contagious causing lists to be
1061 converted to matrices yielding a result which is always a matrix. However,
1062 list-list operations should return lists.
1064 @opencatbox{Categories:}
1065 @category{Lists}
1066 @category{Global flags}
1067 @closecatbox
1068 @end defvr
1070 @c -----------------------------------------------------------------------------
1071 @deffn {Function} listp (@var{expr})
1073 Returns @code{true} if @var{expr} is a list else @code{false}.
1075 @opencatbox{Categories:}
1076 @category{Lists}
1077 @category{Predicate functions}
1078 @closecatbox
1079 @end deffn
1081 @c -----------------------------------------------------------------------------
1082 @anchor{lreduce}
1083 @deffn {Function} lreduce @
1084 @fname{lreduce} (@var{F}, @var{s}) @
1085 @fname{lreduce} (@var{F}, @var{s}, @var{s_0})
1087 Extends the binary function @var{F} to an n-ary function by composition,
1088 where @var{s} is a list.
1090 @code{lreduce(@var{F}, @var{s})} returns @code{F(... F(F(s_1, s_2), s_3), ... s_n)}.
1091 When the optional argument @var{s_0} is present,
1092 the result is equivalent to @code{lreduce(@var{F}, cons(@var{s_0}, @var{s}))}.
1094 The function @var{F} is first applied to the
1095 @i{leftmost} list elements, thus the name "lreduce".
1097 See also @mref{rreduce}, @mref{xreduce}, and @mref{tree_reduce}.
1099 Examples:
1101 @code{lreduce} without the optional argument.
1103 @c ===beg===
1104 @c lreduce (f, [1, 2, 3]);
1105 @c lreduce (f, [1, 2, 3, 4]);
1106 @c ===end===
1107 @example
1108 @group
1109 (%i1) lreduce (f, [1, 2, 3]);
1110 (%o1) f(f(1, 2), 3)
1111 @end group
1112 @group
1113 (%i2) lreduce (f, [1, 2, 3, 4]);
1114 (%o2) f(f(f(1, 2), 3), 4)
1115 @end group
1116 @end example
1118 @code{lreduce} with the optional argument.
1120 @c ===beg===
1121 @c lreduce (f, [1, 2, 3], 4);
1122 @c ===end===
1123 @example
1124 @group
1125 (%i1) lreduce (f, [1, 2, 3], 4);
1126 (%o1) f(f(f(4, 1), 2), 3)
1127 @end group
1128 @end example
1130 @code{lreduce} applied to built-in binary operators.
1131 @code{/} is the division operator.
1133 @c ===beg===
1134 @c lreduce ("^", args ({a, b, c, d}));
1135 @c lreduce ("/", args ({a, b, c, d}));
1136 @c ===end===
1137 @example
1138 @group
1139 (%i1) lreduce ("^", args (@{a, b, c, d@}));
1140 b c d
1141 (%o1) ((a ) )
1142 @end group
1143 @group
1144 (%i2) lreduce ("/", args (@{a, b, c, d@}));
1145 a
1146 (%o2) -----
1147 b c d
1148 @end group
1149 @end example
1151 @opencatbox{Categories:}
1152 @category{Lists}
1153 @closecatbox
1155 @end deffn
1157 @c -----------------------------------------------------------------------------
1158 @anchor{makelist}
1159 @deffn {Function} makelist @
1160 @fname{makelist} () @
1161 @fname{makelist} (@var{expr}, @var{n}) @
1162 @fname{makelist} (@var{expr}, @var{i}, @var{i_max}) @
1163 @fname{makelist} (@var{expr}, @var{i}, @var{i_0}, @var{i_max}) @
1164 @fname{makelist} (@var{expr}, @var{i}, @var{i_0}, @var{i_max}, @var{step}) @
1165 @fname{makelist} (@var{expr}, @var{x}, @var{list})
1167 The first form, @code{makelist ()}, creates an empty list. The second form,
1168 @code{makelist (@var{expr})}, creates a list with @var{expr} as its single
1169 element. @code{makelist (@var{expr}, @var{n})} creates a list of @var{n}
1170 elements generated from @var{expr}.
1172 The most general form, @code{makelist (@var{expr}, @var{i}, @var{i_0},
1173 @var{i_max}, @var{step})}, returns the list of elements obtained when
1174 @code{ev (@var{expr}, @var{i}=@var{j})} is applied to the elements
1175 @var{j} of the sequence: @var{i_0}, @var{i_0} + @var{step}, @var{i_0} +
1176 2*@var{step}, ..., with @var{|j|} less than or equal to @var{|i_max|}.
1178 The increment @var{step} can be a number (positive or negative) or an
1179 expression. If it is omitted, the default value 1 will be used. If both
1180 @var{i_0} and @var{step} are omitted, they will both have a default
1181 value of 1.
1183 @code{makelist (@var{expr}, @var{x}, @var{list})} returns a list, the
1184 @code{j}th element of which is equal to
1185 @code{ev (@var{expr}, @var{x}=@var{list}[j])} for @code{j} equal to 1 through
1186 @code{length (@var{list})}.
1188 Examples:
1190 @c ===beg===
1191 @c makelist (concat (x,i), i, 6);
1192 @c makelist (x=y, y, [a, b, c]);
1193 @c makelist (x^2, x, 3, 2*%pi, 2);
1194 @c makelist (random(6), 4);
1195 @c flatten (makelist (makelist (i^2, 3), i, 4));
1196 @c flatten (makelist (makelist (i^2, i, 3), 4));
1197 @c ===end===
1198 @example
1199 @group
1200 (%i1) makelist (concat (x,i), i, 6);
1201 (%o1) [x1, x2, x3, x4, x5, x6]
1202 @end group
1203 @group
1204 (%i2) makelist (x=y, y, [a, b, c]);
1205 (%o2) [x = a, x = b, x = c]
1206 @end group
1207 @group
1208 (%i3) makelist (x^2, x, 3, 2*%pi, 2);
1209 (%o3) [9, 25]
1210 @end group
1211 @group
1212 (%i4) makelist (random(6), 4);
1213 (%o4) [2, 0, 2, 5]
1214 @end group
1215 @group
1216 (%i5) flatten (makelist (makelist (i^2, 3), i, 4));
1217 (%o5) [1, 1, 1, 4, 4, 4, 9, 9, 9, 16, 16, 16]
1218 @end group
1219 @group
1220 (%i6) flatten (makelist (makelist (i^2, i, 3), 4));
1221 (%o6) [1, 4, 9, 1, 4, 9, 1, 4, 9, 1, 4, 9]
1222 @end group
1223 @end example
1225 @opencatbox{Categories:}
1226 @category{Lists}
1227 @closecatbox
1228 @end deffn
1230 @c -----------------------------------------------------------------------------
1231 @anchor{member}
1232 @deffn {Function} member (@var{expr_1}, @var{expr_2})
1234 Returns @code{true} if @code{is(@var{expr_1} = @var{a})}
1235 for some element @var{a} in @code{args(@var{expr_2})},
1236 otherwise returns @code{false}.
1238 @code{expr_2} is typically a list, in which case
1239 @code{args(@var{expr_2}) = @var{expr_2}} and @code{is(@var{expr_1} = @var{a})}
1240 for some element @var{a} in @code{expr_2} is the test.
1242 @code{member} does not inspect parts of the arguments of @code{expr_2}, so it
1243 may return @code{false} even if @code{expr_1} is a part of some argument of
1244 @code{expr_2}.
1246 See also @mrefdot{elementp}
1248 Examples:
1250 @c ===beg===
1251 @c member (8, [8, 8.0, 8b0]);
1252 @c member (8, [8.0, 8b0]);
1253 @c member (b, [a, b, c]);
1254 @c member (b, [[a, b], [b, c]]);
1255 @c member ([b, c], [[a, b], [b, c]]);
1256 @c F (1, 1/2, 1/4, 1/8);
1257 @c member (1/8, %);
1258 @c member ("ab", ["aa", "ab", sin(1), a + b]);
1259 @c ===end===
1260 @example
1261 @group
1262 (%i1) member (8, [8, 8.0, 8b0]);
1263 (%o1) true
1264 @end group
1265 @group
1266 (%i2) member (8, [8.0, 8b0]);
1267 (%o2) false
1268 @end group
1269 @group
1270 (%i3) member (b, [a, b, c]);
1271 (%o3) true
1272 @end group
1273 @group
1274 (%i4) member (b, [[a, b], [b, c]]);
1275 (%o4) false
1276 @end group
1277 @group
1278 (%i5) member ([b, c], [[a, b], [b, c]]);
1279 (%o5) true
1280 @end group
1281 @group
1282 (%i6) F (1, 1/2, 1/4, 1/8);
1283 1 1 1
1284 (%o6) F(1, -, -, -)
1285 2 4 8
1286 @end group
1287 @group
1288 (%i7) member (1/8, %);
1289 (%o7) true
1290 @end group
1291 @group
1292 (%i8) member ("ab", ["aa", "ab", sin(1), a + b]);
1293 (%o8) true
1294 @end group
1295 @end example
1297 @opencatbox{Categories:}
1298 @category{Lists}
1299 @category{Expressions}
1300 @category{Predicate functions}
1301 @closecatbox
1302 @end deffn
1304 @c -----------------------------------------------------------------------------
1305 @anchor{ninth}
1306 @deffn {Function} ninth (@var{expr})
1308 Returns the 9th item of expression or list @var{expr}.
1309 See @mref{first} for more details.
1311 @opencatbox{Categories:}
1312 @category{Lists}
1313 @category{Expressions}
1314 @closecatbox
1315 @end deffn
1317 @c -----------------------------------------------------------------------------
1318 @anchor{pop}
1319 @deffn {Function} pop (@var{list})
1321 @code{pop} removes and returns the first element from the list @var{list}. The argument
1322 @var{list} must be a mapatom that is bound to a nonempty list. If the argument @var{list} is
1323 not bound to a nonempty list, Maxima signals an error. For examples, see @mrefdot{push}
1325 @opencatbox{Categories:}
1326 @category{Lists}
1327 @category{Expressions}
1328 @closecatbox
1329 @end deffn
1331 @c -----------------------------------------------------------------------------
1332 @anchor{push}
1333 @deffn {Function} push (@var{item}, @var{list})
1335 @code{push} prepends the item @var{item} to the list @var{list} and returns a copy of the new list.
1336 The second argument @var{list} must be a mapatom that is bound to a list. The first argument @var{item}
1337 can be any Maxima symbol or expression. If the argument @var{list} is not bound to a list, Maxima
1338 signals an error.
1341 To remove the first item from a list, see @mrefdot{pop}
1344 Examples:
1346 @c ===beg===
1347 @c ll: [];
1348 @c push (x, ll);
1349 @c push (x^2+y, ll);
1350 @c a: push ("string", ll);
1351 @c pop (ll);
1352 @c pop (ll);
1353 @c pop (ll);
1354 @c ll;
1355 @c a;
1356 @c ===end===
1357 @example
1358 @group
1359 (%i1) ll: [];
1360 (%o1) []
1361 @end group
1362 @group
1363 (%i2) push (x, ll);
1364 (%o2) [x]
1365 @end group
1366 @group
1367 (%i3) push (x^2+y, ll);
1368 2
1369 (%o3) [y + x , x]
1370 @end group
1371 @group
1372 (%i4) a: push ("string", ll);
1373 2
1374 (%o4) [string, y + x , x]
1375 @end group
1376 @group
1377 (%i5) pop (ll);
1378 (%o5) string
1379 @end group
1380 @group
1381 (%i6) pop (ll);
1382 2
1383 (%o6) y + x
1384 @end group
1385 @group
1386 (%i7) pop (ll);
1387 (%o7) x
1388 @end group
1389 @group
1390 (%i8) ll;
1391 (%o8) []
1392 @end group
1393 @group
1394 (%i9) a;
1395 2
1396 (%o9) [string, y + x , x]
1397 @end group
1398 @end example
1400 @opencatbox{Categories:}
1401 @category{Lists}
1402 @category{Expressions}
1403 @closecatbox
1404 @end deffn
1406 @c -----------------------------------------------------------------------------
1407 @anchor{rest}
1408 @deffn {Function} rest @
1409 @fname{rest} (@var{expr}, @var{n}) @
1410 @fname{rest} (@var{expr})
1412 Returns @var{expr} with its first @var{n} elements removed if @var{n}
1413 is positive and its last @code{- @var{n}} elements removed if @var{n}
1414 is negative. If @var{n} is 1 it may be omitted. The first argument
1415 @var{expr} may be a list, matrix, or other expression. When @var{expr}
1416 is an atom, @code{rest} signals an error; when @var{expr} is an empty
1417 list and @code{partswitch} is false, @code{rest} signals an error. When
1418 @var{expr} is an empty list and @code{partswitch} is true, @code{rest}
1419 returns @code{end}.
1421 Applying @code{rest} to expression such as @code{f(a,b,c)} returns
1422 @code{f(b,c)}. In general, applying @code{rest} to a nonlist doesn't
1423 make sense. For example, because '^' requires two arguments,
1424 @code{rest(a^b)} results in an error message. The functions
1425 @code{args} and @code{op} may be useful as well, since @code{args(a^b)}
1426 returns @code{[a,b]} and @code{op(a^b)} returns ^.
1428 See also @mref{firstn} and @mrefdot{lastn}
1430 @example
1431 @group
1432 (%i1) rest(a+b+c);
1433 (%o1) b+a
1434 (%i2) rest(a+b+c,2);
1435 (%o2) a
1436 (%i3) rest(a+b+c,-2);
1437 (%o3) c
1438 @end group
1439 @end example
1441 @opencatbox{Categories:}
1442 @category{Lists}
1443 @category{Expressions}
1444 @closecatbox
1445 @end deffn
1447 @c NEED ANOTHER deffn FOR GENERAL EXPRESSIONS ARGUMENTS
1448 @c SPLIT OFF EXAMPLES INTO EXAMPLE SECTION
1450 @c -----------------------------------------------------------------------------
1451 @anchor{reverse}
1452 @deffn {Function} reverse (@var{list})
1454 Reverses the order of the members of the @var{list} (not
1455 the members themselves). @code{reverse} also works on general expressions,
1456 e.g. @code{reverse(a=b);} gives @code{b=a}.
1458 See also @mrefdot{sreverse}
1460 @opencatbox{Categories:}
1461 @category{Lists}
1462 @category{Expressions}
1463 @closecatbox
1464 @end deffn
1466 @c -----------------------------------------------------------------------------
1467 @anchor{rreduce}
1468 @deffn {Function} rreduce @
1469 @fname{rreduce} (@var{F}, @var{s}) @
1470 @fname{rreduce} (@var{F}, @var{s}, @var{s_@{n + 1@}})
1472 Extends the binary function @var{F} to an n-ary function by composition,
1473 where @var{s} is a list.
1475 @code{rreduce(@var{F}, @var{s})} returns @code{F(s_1, ... F(s_@{n - 2@}, F(s_@{n - 1@}, s_n)))}.
1476 When the optional argument @var{s_@{n + 1@}} is present,
1477 the result is equivalent to @code{rreduce(@var{F}, endcons(@var{s_@{n + 1@}}, @var{s}))}.
1479 The function @var{F} is first applied to the
1480 @i{rightmost} list elements, thus the name "rreduce".
1482 See also @mref{lreduce}, @mref{tree_reduce}, and @mref{xreduce}.
1484 Examples:
1486 @code{rreduce} without the optional argument.
1488 @c ===beg===
1489 @c rreduce (f, [1, 2, 3]);
1490 @c rreduce (f, [1, 2, 3, 4]);
1491 @c ===end===
1492 @example
1493 @group
1494 (%i1) rreduce (f, [1, 2, 3]);
1495 (%o1) f(1, f(2, 3))
1496 @end group
1497 @group
1498 (%i2) rreduce (f, [1, 2, 3, 4]);
1499 (%o2) f(1, f(2, f(3, 4)))
1500 @end group
1501 @end example
1503 @code{rreduce} with the optional argument.
1505 @c ===beg===
1506 @c rreduce (f, [1, 2, 3], 4);
1507 @c ===end===
1508 @example
1509 @group
1510 (%i1) rreduce (f, [1, 2, 3], 4);
1511 (%o1) f(1, f(2, f(3, 4)))
1512 @end group
1513 @end example
1515 @code{rreduce} applied to built-in binary operators.
1516 @code{/} is the division operator.
1518 @c ===beg===
1519 @c rreduce ("^", args ({a, b, c, d}));
1520 @c rreduce ("/", args ({a, b, c, d}));
1521 @c ===end===
1522 @example
1523 @group
1524 (%i1) rreduce ("^", args (@{a, b, c, d@}));
1525 d
1526 c
1527 b
1528 (%o1) a
1529 @end group
1530 @group
1531 (%i2) rreduce ("/", args (@{a, b, c, d@}));
1532 a c
1533 (%o2) ---
1534 b d
1535 @end group
1536 @end example
1538 @opencatbox{Categories:}
1539 @category{Lists}
1540 @closecatbox
1542 @end deffn
1544 @c -----------------------------------------------------------------------------
1545 @anchor{second}
1546 @deffn {Function} second (@var{expr})
1548 Returns the 2nd item of expression or list @var{expr}.
1549 See @mref{first} for more details.
1551 @opencatbox{Categories:}
1552 @category{Lists}
1553 @category{Expressions}
1554 @closecatbox
1555 @end deffn
1557 @c -----------------------------------------------------------------------------
1558 @anchor{seventh}
1559 @deffn {Function} seventh (@var{expr})
1561 Returns the 7th item of expression or list @var{expr}.
1562 See @mref{first} for more details.
1564 @opencatbox{Categories:}
1565 @category{Lists}
1566 @category{Expressions}
1567 @closecatbox
1568 @end deffn
1570 @c -----------------------------------------------------------------------------
1571 @anchor{sixth}
1572 @deffn {Function} sixth (@var{expr})
1574 Returns the 6th item of expression or list @var{expr}.
1575 See @mref{first} for more details.
1577 @opencatbox{Categories:}
1578 @category{Lists}
1579 @category{Expressions}
1580 @closecatbox
1581 @end deffn
1583 @c -----------------------------------------------------------------------------
1584 @anchor{sort}
1585 @deffn {Function} sort @
1586 @fname{sort} (@var{L}, @var{P}) @
1587 @fname{sort} (@var{L})
1589 @code{sort(@var{L}, @var{P})} sorts a list @var{L} according to a predicate @code{P} of two arguments
1590 which defines a strict weak order on the elements of @var{L}.
1591 If @code{@var{P}(a, b)} is @code{true}, then @code{a} appears before @code{b} in the result.
1592 If neither @code{@var{P}(a, b)} nor @code{@var{P}(b, a)} are @code{true},
1593 then @code{a} and @code{b} are equivalent, and appear in the result in the same order as in the input.
1594 That is, @code{sort} is a stable sort.
1596 If @code{@var{P}(a, b)} and @code{@var{P}(b, a)} are both @code{true} for some elements of @var{L},
1597 then @var{P} is not a valid sort predicate, and the result is undefined.
1598 If @code{@var{P}(a, b)} is something other than @code{true} or @code{false}, @code{sort} signals an error.
1600 The predicate may be specified as the name of a function
1601 or binary infix operator, or as a @code{lambda} expression. If specified as
1602 the name of an operator, the name must be enclosed in double quotes.
1604 The sorted list is returned as a new object; the argument @var{L} is not modified.
1606 @code{sort(@var{L})} is equivalent to @code{sort(@var{L}, orderlessp)}.
1608 The default sorting order is ascending, as determined by @mrefdot{orderlessp} The predicate @code{ordergreatp} sorts a list in descending order.
1610 All Maxima atoms and expressions are comparable under @code{orderlessp} and @code{ordergreatp}.
1612 Operators @code{<} and @code{>} order numbers, constants, and constant expressions by magnitude.
1613 Note that @code{orderlessp} and @code{ordergreatp} do not order numbers, constants, and constant expressions by magnitude.
1615 @code{ordermagnitudep} orders numbers, constants, and constant expressions the same as @code{<},
1616 and all other elements the same as @code{orderlessp}.
1618 Examples:
1620 @code{sort} sorts a list according to a predicate of two arguments
1621 which defines a strict weak order on the elements of the list.
1623 @c ===beg===
1624 @c sort ([1, a, b, 2, 3, c], 'orderlessp);
1625 @c sort ([1, a, b, 2, 3, c], 'ordergreatp);
1626 @c ===end===
1627 @example
1628 @group
1629 (%i1) sort ([1, a, b, 2, 3, c], 'orderlessp);
1630 (%o1) [1, 2, 3, a, b, c]
1631 @end group
1632 @group
1633 (%i2) sort ([1, a, b, 2, 3, c], 'ordergreatp);
1634 (%o2) [c, b, a, 3, 2, 1]
1635 @end group
1636 @end example
1638 The predicate may be specified as the name of a function
1639 or binary infix operator, or as a @code{lambda} expression. If specified as
1640 the name of an operator, the name must be enclosed in double quotes.
1642 @c ===beg===
1643 @c L : [[1, x], [3, y], [4, w], [2, z]];
1644 @c foo (a, b) := a[1] > b[1];
1645 @c sort (L, 'foo);
1646 @c infix (">>");
1647 @c a >> b := a[1] > b[1];
1648 @c sort (L, ">>");
1649 @c sort (L, lambda ([a, b], a[1] > b[1]));
1650 @c ===end===
1651 @example
1652 @group
1653 (%i1) L : [[1, x], [3, y], [4, w], [2, z]];
1654 (%o1) [[1, x], [3, y], [4, w], [2, z]]
1655 @end group
1656 @group
1657 (%i2) foo (a, b) := a[1] > b[1];
1658 (%o2) foo(a, b) := a > b
1659 1 1
1660 @end group
1661 @group
1662 (%i3) sort (L, 'foo);
1663 (%o3) [[4, w], [3, y], [2, z], [1, x]]
1664 @end group
1665 @group
1666 (%i4) infix (">>");
1667 (%o4) >>
1668 @end group
1669 @group
1670 (%i5) a >> b := a[1] > b[1];
1671 (%o5) (a >> b) := a > b
1672 1 1
1673 @end group
1674 @group
1675 (%i6) sort (L, ">>");
1676 (%o6) [[4, w], [3, y], [2, z], [1, x]]
1677 @end group
1678 @group
1679 (%i7) sort (L, lambda ([a, b], a[1] > b[1]));
1680 (%o7) [[4, w], [3, y], [2, z], [1, x]]
1681 @end group
1682 @end example
1684 @code{sort(@var{L})} is equivalent to @code{sort(@var{L}, orderlessp)}.
1686 @c ===beg===
1687 @c L : [a, 2*b, -5, 7, 1 + %e, %pi];
1688 @c sort (L);
1689 @c sort (L, 'orderlessp);
1690 @c ===end===
1691 @example
1692 @group
1693 (%i1) L : [a, 2*b, -5, 7, 1 + %e, %pi];
1694 (%o1) [a, 2 b, - 5, 7, %e + 1, %pi]
1695 @end group
1696 @group
1697 (%i2) sort (L);
1698 (%o2) [- 5, 7, %e + 1, %pi, a, 2 b]
1699 @end group
1700 @group
1701 (%i3) sort (L, 'orderlessp);
1702 (%o3) [- 5, 7, %e + 1, %pi, a, 2 b]
1703 @end group
1704 @end example
1706 The default sorting order is ascending, as determined by @mrefdot{orderlessp} The predicate @code{ordergreatp} sorts a list in descending order.
1708 @c ===beg===
1709 @c L : [a, 2*b, -5, 7, 1 + %e, %pi];
1710 @c sort (L);
1711 @c sort (L, 'ordergreatp);
1712 @c ===end===
1713 @example
1714 @group
1715 (%i1) L : [a, 2*b, -5, 7, 1 + %e, %pi];
1716 (%o1) [a, 2 b, - 5, 7, %e + 1, %pi]
1717 @end group
1718 @group
1719 (%i2) sort (L);
1720 (%o2) [- 5, 7, %e + 1, %pi, a, 2 b]
1721 @end group
1722 @group
1723 (%i3) sort (L, 'ordergreatp);
1724 (%o3) [2 b, a, %pi, %e + 1, 7, - 5]
1725 @end group
1726 @end example
1728 All Maxima atoms and expressions are comparable under @code{orderlessp} and @code{ordergreatp}.
1730 @c ===beg===
1731 @c L : [11, -17, 29b0, 9*c, 7.55, foo(x, y), -5/2, b + a];
1732 @c sort (L, orderlessp);
1733 @c sort (L, ordergreatp);
1734 @c ===end===
1735 @example
1736 @group
1737 (%i1) L : [11, -17, 29b0, 9*c, 7.55, foo(x, y), -5/2, b + a];
1738 5
1739 (%o1) [11, - 17, 2.9b1, 9 c, 7.55, foo(x, y), - -, b + a]
1740 2
1741 @end group
1742 @group
1743 (%i2) sort (L, orderlessp);
1744 5
1745 (%o2) [- 17, - -, 7.55, 11, 2.9b1, b + a, 9 c, foo(x, y)]
1746 2
1747 @end group
1748 @group
1749 (%i3) sort (L, ordergreatp);
1750 5
1751 (%o3) [foo(x, y), 9 c, b + a, 2.9b1, 11, 7.55, - -, - 17]
1752 2
1753 @end group
1754 @end example
1756 Operators @code{<} and @code{>} order numbers, constants, and constant expressions by magnitude.
1757 Note that @code{orderlessp} and @code{ordergreatp} do not order numbers, constants, and constant expressions by magnitude.
1759 @c ===beg===
1760 @c L : [%pi, 3, 4, %e, %gamma];
1761 @c sort (L, ">");
1762 @c sort (L, ordergreatp);
1763 @c ===end===
1764 @example
1765 @group
1766 (%i1) L : [%pi, 3, 4, %e, %gamma];
1767 (%o1) [%pi, 3, 4, %e, %gamma]
1768 @end group
1769 @group
1770 (%i2) sort (L, ">");
1771 (%o2) [4, %pi, 3, %e, %gamma]
1772 @end group
1773 @group
1774 (%i3) sort (L, ordergreatp);
1775 (%o3) [%pi, %gamma, %e, 4, 3]
1776 @end group
1777 @end example
1779 @code{ordermagnitudep} orders numbers, constants, and constant expressions the same as @code{<},
1780 and all other elements the same as @code{orderlessp}.
1782 @c ===beg===
1783 @c L: [%i, 1+%i, 2*x, minf, inf, %e, sin(1), 0, 1,2,3, 1.0, 1.0b0];
1784 @c sort (L, ordermagnitudep);
1785 @c sort (L, orderlessp);
1786 @c ===end===
1787 @example
1788 @group
1789 (%i1) L: [%i, 1+%i, 2*x, minf, inf, %e, sin(1), 0,1,2,3, 1.0, 1.0b0];
1790 (%o1) [%i, %i + 1, 2 x, minf, inf, %e, sin(1), 0, 1, 2, 3, 1.0,
1791 1.0b0]
1792 @end group
1793 @group
1794 (%i2) sort (L, ordermagnitudep);
1795 (%o2) [minf, 0, sin(1), 1, 1.0, 1.0b0, 2, %e, 3, inf, %i,
1796 %i + 1, 2 x]
1797 @end group
1798 @group
1799 (%i3) sort (L, orderlessp);
1800 (%o3) [0, 1, 1.0, 2, 3, sin(1), 1.0b0, %e, %i, %i + 1, inf,
1801 minf, 2 x]
1802 @end group
1803 @end example
1805 @opencatbox{Categories:}
1806 @category{Lists}
1807 @closecatbox
1808 @end deffn
1810 @c -----------------------------------------------------------------------------
1811 @anchor{sublist}
1812 @deffn {Function} sublist (@var{list}, @var{p})
1814 Returns the list of elements of @var{list} for which the predicate @code{p}
1815 returns @code{true}.
1817 Example:
1819 @c ===beg===
1820 @c L: [1, 2, 3, 4, 5, 6];
1821 @c sublist (L, evenp);
1822 @c ===end===
1823 @example
1824 @group
1825 (%i1) L: [1, 2, 3, 4, 5, 6];
1826 (%o1) [1, 2, 3, 4, 5, 6]
1827 @end group
1828 @group
1829 (%i2) sublist (L, evenp);
1830 (%o2) [2, 4, 6]
1831 @end group
1832 @end example
1834 @opencatbox{Categories:}
1835 @category{Lists}
1836 @closecatbox
1837 @end deffn
1839 @c -----------------------------------------------------------------------------
1840 @anchor{sublist_indices}
1841 @deffn {Function} sublist_indices (@var{L}, @var{P})
1843 Returns the indices of the elements @code{x} of the list @var{L} for which
1844 the predicate @code{maybe(@var{P}(x))} returns @code{true};
1845 this excludes @code{unknown} as well as @code{false}.
1846 @var{P} may be the name of a function or a lambda expression.
1847 @var{L} must be a literal list.
1849 Examples:
1851 @c ===beg===
1852 @c sublist_indices ('[a, b, b, c, 1, 2, b, 3, b],
1853 @c lambda ([x], x='b));
1854 @c sublist_indices ('[a, b, b, c, 1, 2, b, 3, b], symbolp);
1855 @c sublist_indices ([1 > 0, 1 < 0, 2 < 1, 2 > 1, 2 > 0],
1856 @c identity);
1857 @c assume (x < -1);
1858 @c map (maybe, [x > 0, x < 0, x < -2]);
1859 @c sublist_indices ([x > 0, x < 0, x < -2], identity);
1860 @c ===end===
1861 @example
1862 @group
1863 (%i1) sublist_indices ('[a, b, b, c, 1, 2, b, 3, b],
1864 lambda ([x], x='b));
1865 (%o1) [2, 3, 7, 9]
1866 @end group
1867 @group
1868 (%i2) sublist_indices ('[a, b, b, c, 1, 2, b, 3, b], symbolp);
1869 (%o2) [1, 2, 3, 4, 7, 9]
1870 @end group
1871 @group
1872 (%i3) sublist_indices ([1 > 0, 1 < 0, 2 < 1, 2 > 1, 2 > 0],
1873 identity);
1874 (%o3) [1, 4, 5]
1875 @end group
1876 @group
1877 (%i4) assume (x < -1);
1878 (%o4) [x < - 1]
1879 @end group
1880 @group
1881 (%i5) map (maybe, [x > 0, x < 0, x < -2]);
1882 (%o5) [false, true, unknown]
1883 @end group
1884 @group
1885 (%i6) sublist_indices ([x > 0, x < 0, x < -2], identity);
1886 (%o6) [2]
1887 @end group
1888 @end example
1890 @opencatbox{Categories:}
1891 @category{Lists}
1892 @closecatbox
1893 @end deffn
1895 @c -----------------------------------------------------------------------------
1896 @anchor{tenth}
1897 @deffn {Function} tenth (@var{expr})
1899 Returns the 10th item of expression or list @var{expr}.
1900 See @mref{first} for more details.
1902 @opencatbox{Categories:}
1903 @category{Lists}
1904 @category{Expressions}
1905 @closecatbox
1906 @end deffn
1908 @c -----------------------------------------------------------------------------
1909 @anchor{third}
1910 @deffn {Function} third (@var{expr})
1912 Returns the 3rd item of expression or list @var{expr}.
1913 See @mref{first} for more details.
1915 @opencatbox{Categories:}
1916 @category{Lists}
1917 @category{Expressions}
1918 @closecatbox
1919 @end deffn
1921 @c -----------------------------------------------------------------------------
1922 @c TREE_REDUCE ACCEPTS A SET OR LIST AS AN ARGUMENT, BUT RREDUCE AND LREDUCE WANT ONLY LISTS; STRANGE
1923 @anchor{tree_reduce}
1924 @deffn {Function} tree_reduce @
1925 @fname{tree_reduce} (@var{F}, @var{s}) @
1926 @fname{tree_reduce} (@var{F}, @var{s}, @var{s_0})
1928 Extends the binary function @var{F} to an n-ary function by composition,
1929 where @var{s} is a set or list.
1931 @code{tree_reduce} is equivalent to the following:
1932 Apply @var{F} to successive pairs of elements
1933 to form a new list @code{[@var{F}(@var{s_1}, @var{s_2}), @var{F}(@var{s_3}, @var{s_4}), ...]},
1934 carrying the final element unchanged if there are an odd number of elements.
1935 Then repeat until the list is reduced to a single element, which is the return value.
1937 When the optional argument @var{s_0} is present,
1938 the result is equivalent @code{tree_reduce(@var{F}, cons(@var{s_0}, @var{s}))}.
1940 For addition of floating point numbers,
1941 @code{tree_reduce} may return a sum that has a smaller rounding error
1942 than either @code{rreduce} or @code{lreduce}.
1944 The elements of @var{s} and the partial results may be arranged in a minimum-depth binary tree,
1945 thus the name "tree_reduce".
1947 Examples:
1949 @code{tree_reduce} applied to a list with an even number of elements.
1951 @c ===beg===
1952 @c tree_reduce (f, [a, b, c, d]);
1953 @c ===end===
1954 @example
1955 @group
1956 (%i1) tree_reduce (f, [a, b, c, d]);
1957 (%o1) f(f(a, b), f(c, d))
1958 @end group
1959 @end example
1961 @code{tree_reduce} applied to a list with an odd number of elements.
1963 @c ===beg===
1964 @c tree_reduce (f, [a, b, c, d, e]);
1965 @c ===end===
1966 @example
1967 @group
1968 (%i1) tree_reduce (f, [a, b, c, d, e]);
1969 (%o1) f(f(f(a, b), f(c, d)), e)
1970 @end group
1971 @end example
1973 @opencatbox{Categories:}
1974 @category{Sets}
1975 @category{Lists}
1976 @closecatbox
1978 @end deffn
1980 @c -----------------------------------------------------------------------------
1981 @anchor{unique}
1982 @deffn {Function} unique (@var{L})
1984 Returns the unique elements of the list @var{L}.
1986 When all the elements of @var{L} are unique,
1987 @code{unique} returns a shallow copy of @var{L},
1988 not @var{L} itself.
1990 If @var{L} is not a list, @code{unique} returns @var{L}.
1992 Example:
1994 @c ===beg===
1995 @c unique ([1, %pi, a + b, 2, 1, %e, %pi, a + b, [1]]);
1996 @c ===end===
1997 @example
1998 @group
1999 (%i1) unique ([1, %pi, a + b, 2, 1, %e, %pi, a + b, [1]]);
2000 (%o1) [1, 2, %e, %pi, [1], b + a]
2001 @end group
2002 @end example
2003 @end deffn
2005 @c -----------------------------------------------------------------------------
2006 @c XREDUCE ACCEPTS A SET OR LIST AS AN ARGUMENT, BUT RREDUCE AND LREDUCE WANT ONLY LISTS; STRANGE
2007 @anchor{xreduce}
2008 @deffn {Function} xreduce @
2009 @fname{xreduce} (@var{F}, @var{s}) @
2010 @fname{xreduce} (@var{F}, @var{s}, @var{s_0})
2012 Extends the function @var{F} to an n-ary function by composition,
2013 or, if @var{F} is already n-ary, applies @var{F} to @var{s}.
2014 When @var{F} is not n-ary, @code{xreduce} is the same as @code{lreduce}.
2015 The argument @var{s} is a list.
2017 Functions known to be n-ary include
2018 addition @code{+}, multiplication @code{*}, @code{and}, @code{or}, @code{max},
2019 @code{min}, and @code{append}.
2020 Functions may also be declared n-ary by @code{declare(@var{F}, nary)}.
2021 For these functions,
2022 @code{xreduce} is expected to be faster than either @code{rreduce} or @code{lreduce}.
2024 When the optional argument @var{s_0} is present,
2025 the result is equivalent to @code{xreduce(@var{s}, cons(@var{s_0}, @var{s}))}.
2027 @c NOT SURE WHAT IS THE RELEVANCE OF THE FOLLOWING COMMENT
2028 @c MAXIMA IS NEVER SO CAREFUL ABOUT FLOATING POINT ASSOCIATIVITY SO FAR AS I KNOW
2029 Floating point addition is not exactly associative; be that as it may,
2030 @code{xreduce} applies Maxima's n-ary addition when @var{s} contains floating point numbers.
2032 Examples:
2034 @code{xreduce} applied to a function known to be n-ary.
2035 @code{F} is called once, with all arguments.
2037 @c ===beg===
2038 @c declare (F, nary);
2039 @c F ([L]) := L;
2040 @c xreduce (F, [a, b, c, d, e]);
2041 @c ===end===
2042 @example
2043 @group
2044 (%i1) declare (F, nary);
2045 (%o1) done
2046 @end group
2047 @group
2048 (%i2) F ([L]) := L;
2049 (%o2) F([L]) := L
2050 @end group
2051 @group
2052 (%i3) xreduce (F, [a, b, c, d, e]);
2053 (%o3) [a, b, c, d, e]
2054 @end group
2055 @end example
2057 @code{xreduce} applied to a function not known to be n-ary.
2058 @code{G} is called several times, with two arguments each time.
2060 @c ===beg===
2061 @c G ([L]) := L;
2062 @c xreduce (G, [a, b, c, d, e]);
2063 @c lreduce (G, [a, b, c, d, e]);
2064 @c ===end===
2065 @example
2066 @group
2067 (%i1) G ([L]) := L;
2068 (%o1) G([L]) := L
2069 @end group
2070 @group
2071 (%i2) xreduce (G, [a, b, c, d, e]);
2072 (%o2) [[[[a, b], c], d], e]
2073 @end group
2074 @group
2075 (%i3) lreduce (G, [a, b, c, d, e]);
2076 (%o3) [[[[a, b], c], d], e]
2077 @end group
2078 @end example
2080 @opencatbox{Categories:}
2081 @category{Sets}
2082 @category{Lists}
2083 @closecatbox
2085 @end deffn
2087 @c h-----------------------------------------------------------------------------
2088 @node Performance considerations for Lists, ,Functions and Variables for Lists, Lists
2089 @subsection Performance considerations for Lists
2090 @c -----------------------------------------------------------------------------
2092 Lists provide efficient ways of appending and removing elements.
2093 They can be created without knowing their final dimensions.
2094 Lisp provides efficient means of copying and handling lists.
2095 Also nested lists do not need to be strictly rectangular.
2096 These advantages over declared arrays come with the drawback that the amount of time
2097 needed for accessing a random element within a list may be roughly
2098 proportional to the element's distance from its beginning.
2099 Efficient traversal of lists is still possible, though, by using the list as a
2100 stack or a fifo:
2102 @c ===beg===
2103 @c l:[Test,1,2,3,4];
2104 @c while l # [] do
2105 @c disp(pop(l));
2106 @c ===end===
2107 @example
2108 @group
2109 (%i1) l:[Test,1,2,3,4];
2110 (%o1) [Test, 1, 2, 3, 4]
2111 @end group
2112 (%i2) while l # [] do
2113 disp(pop(l));
2114 Test
2116 1
2118 2
2120 3
2122 4
2124 (%o2) done
2125 @end example
2126 Another even faster example would be:
2127 @c ===beg===
2128 @c l:[Test,1,2,3,4];
2129 @c for i in l do
2130 @c disp(pop(l));
2131 @c ===end===
2132 @example
2133 @group
2134 (%i1) l:[Test,1,2,3,4];
2135 (%o1) [Test, 1, 2, 3, 4]
2136 @end group
2137 (%i2) for i in l do
2138 disp(pop(l));
2139 Test
2141 1
2143 2
2145 3
2147 4
2149 (%o2) done
2150 @end example
2152 Beginning traversal with the last element of a list is possible after
2153 reversing the list using @code{reverse ()}.
2154 If the elements of a long list need to be processed in a different
2155 order performance might be increased by converting the list into a
2156 declared array first.
2158 Note also that the ending condition of @code{for} loops
2159 is tested for every iteration which means that the result of a
2160 @code{length} should be cached if it is used in the ending
2161 condition:
2163 @c ===beg===
2164 @c l:makelist(i,i,1,100000)$
2165 @c lngth:length(l);
2166 @c x:1;
2167 @c for i:1 thru lngth do
2168 @c x:x+1$
2169 @c x;
2170 @c ===end===
2171 @example
2172 (%i1) l:makelist(i,i,1,100000)$
2173 @group
2174 (%i2) lngth:length(l);
2175 (%o2) 100000
2176 @end group
2177 @group
2178 (%i3) x:1;
2179 (%o3) 1
2180 @end group
2181 @group
2182 (%i4) for i:1 thru lngth do
2183 x:x+1$
2184 @end group
2185 @group
2186 (%i5) x;
2187 (%o5) 100001
2188 @end group
2189 @end example