Lists
=====

Introduction to Lists
---------------------

Lists are the basic building block for Maxima and Lisp.  All data types other than arrays, hashed arrays and numbers are represented as Lisp lists, These Lisp lists have the form

     ((MPLUS) $A 2)

to indicate an expression a+2.  At Maxima level one would see the infix notation a+2.  Maxima also has lists which are printed as

     [1, 2, 7, x+y]

for a list with 4 elements.  Internally this corresponds to a Lisp list of the form

     ((MLIST) 1 2 7 ((MPLUS) $X $Y))

The flag which denotes the type field of the Maxima expression is a list itself, since after it has been through the simplifier the list would become

     ((MLIST SIMP) 1 2 7 ((MPLUS SIMP) $X $Y))

Functions and Variables for Lists
---------------------------------

 -- Operator: [
 -- Operator: ]

     [ and ] mark the beginning and end, respectively, of a list.

     [ and ] also enclose the subscripts of a list, array, hashed array or memoizing function Note that other than for arrays accessing the nth element of a list may need an amount of time that is roughly proportional to  n, see Performance considerations for Lists.

     Note that if an element of a subscripted variable is written to before a list or an array of this name is declared a hashed array (see Arrays) is created, not a list.

     Examples:

          (%i1) x: [a, b, c];
          (%o1)                       [a, b, c]

          (%i2) x[3];
          (%o2)                           c

          (%i3) array (y, fixnum, 3);
          (%o3)                           y

          (%i4) y[2]: %pi;
          (%o4)                          %pi

          (%i5) y[2];
          (%o5)                          %pi

          (%i6) z['foo]: 'bar;
          (%o6)                          bar

          (%i7) z['foo];
          (%o7)                          bar

          (%i8) g[k] := 1/(k^2+1);
                                            1
          (%o8)                     g  := ------
                                     k     2
                                          k  + 1

          (%i9) g[10];
                                          1
          (%o9)                          ---
                                         101

     Categories: Lists Operators

 -- Function: append (LIST_1, ..., LIST_N)

     Returns a single list of the elements of LIST_1 followed by the elements of LIST_2, ...  append also works on general expressions, e.g. append (f(a,b), f(c,d,e)); yields f(a,b,c,d,e).

     See also addrow addcol and join

     Do example(append); for an example.

     Categories: Lists Expressions

 -- Function: assoc
     assoc (KEY, E, DEFAULT)
     assoc (KEY, E)

     assoc searches for KEY as the first part of an argument of E and returns the second part of the first match, if any.

     KEY may be any expression. E must be a nonatomic expression, and every argument of E must have exactly two parts. assoc returns the second part of the first matching argument of E. Matches are determined by is(KEY = first(A)) where A is an argument of E.

     If there are two or more matches, only the first is returned. If there are no matches, DEFAULT is returned, if specified. Otherwise, false is returned.

     See also sublist and member

     Examples:

     KEY may be any expression. E must be a nonatomic expression, and every argument of E must have exactly two parts. assoc returns the second part of the first matching argument of E.

          (%i1) assoc (f(x), foo(g(x) = y, f(x) = z + 1, h(x) = 2*u));
          (%o1)                         z + 1

     If there are two or more matches, only the first is returned.

          (%i1) assoc (yy, [xx = 111, yy = 222, yy = 333, yy = 444]);
          (%o1)                          222

     If there are no matches, DEFAULT is returned, if specified. Otherwise, false is returned.

          (%i1) assoc (abc, [[x, 111], [y, 222], [z, 333]], none);
          (%o1)                         none
          (%i2) assoc (abc, [[x, 111], [y, 222], [z, 333]]);
          (%o2)                         false

     Categories: Lists Expressions

 -- Function: cons
     cons (EXPR, LIST)
     cons (EXPR_1, EXPR_2)

     cons (EXPR, LIST) returns a new list constructed of the element EXPR as its first element, followed by the elements of LIST. This is analogous to the Lisp language construction operation "cons".

     The Maxima function cons can also be used where the second argument is other than a list and this might be useful. In this case, cons (EXPR_1, EXPR_2) returns an expression with same operator as EXPR_2 but with argument cons(expr_1, args(expr_2)). Examples:

          (%i1) cons(a,[b,c,d]);
          (%o1)                     [a, b, c, d]

          (%i2) cons(a,f(b,c,d));
          (%o2)                     f(a, b, c, d)

     In general, cons applied to a nonlist doesn't make sense. For instance, cons(a,b^c) results in an illegal expression, since '^' cannot take three arguments.

     When inflag is true, cons operates on the internal structure of an expression, otherwise cons operates on the displayed form. Especially when inflag is true, cons applied to a nonlist sometimes gives a surprising result; for example

          (%i1) cons(a,-a), inflag : true;
                                           2
          (%o1)                         - a

          (%i2) cons(a,-a), inflag : false;
          (%o2)                           0

     Categories: Lists Expressions

 -- Function: copylist (LIST)

     Returns a copy of the list LIST.

     Categories: Lists

 -- Function: create_list (FORM, X_1, LIST_1, ..., X_N, LIST_N)

     Create a list by evaluating FORM with X_1 bound to each element of LIST_1, and for each such binding bind X_2 to each element of LIST_2, ... The number of elements in the result will be the product of the number of elements in each list. Each variable X_I must actually be a symbol -- it will not be evaluated. The list arguments will be evaluated once at the beginning of the iteration.

          (%i1) create_list (x^i, i, [1, 3, 7]);
                                          3   7
          (%o1)                      [x, x , x ]

     With a double iteration:

          (%i1) create_list ([i, j], i, [a, b], j, [e, f, h]);
          (%o1)   [[a, e], [a, f], [a, h], [b, e], [b, f], [b, h]]

     Instead of LIST_I two args may be supplied each of which should evaluate to a number.  These will be the inclusive lower and upper bounds for the iteration.

          (%i1) create_list ([i, j], i, [1, 2, 3], j, 1, i);
          (%o1)   [[1, 1], [2, 1], [2, 2], [3, 1], [3, 2], [3, 3]]

     Note that the limits or list for the j variable can depend on the current value of i.

     Categories: Lists

 -- Function: delete
     delete (EXPR_1, EXPR_2)
     delete (EXPR_1, EXPR_2, N)

     delete(EXPR_1, EXPR_2) removes from EXPR_2 any arguments of its top-level operator which are the same (as determined by "=") as EXPR_1. Note that "=" tests for formal equality, not equivalence. Note also that arguments of subexpressions are not affected.

     EXPR_1 may be an atom or a non-atomic expression. EXPR_2 may be any non-atomic expression. delete returns a new expression; it does not modify EXPR_2.

     delete(EXPR_1, EXPR_2, N) removes from EXPR_2 the first N arguments of the top-level operator which are the same as EXPR_1. If there are fewer than N such arguments, then all such arguments are removed.

     Examples:

     Removing elements from a list.

          (%i1) delete (y, [w, x, y, z, z, y, x, w]);
          (%o1)                  [w, x, z, z, x, w]

     Removing terms from a sum.

          (%i1) delete (sin(x), x + sin(x) + y);
          (%o1)                         y + x

     Removing factors from a product.

          (%i1) delete (u - x, (u - w)*(u - x)*(u - y)*(u - z));
          (%o1)                (u - w) (u - y) (u - z)

     Removing arguments from an arbitrary expression.

          (%i1) delete (a, foo (a, b, c, d, a));
          (%o1)                     foo(b, c, d)

     Limit the number of removed arguments.

          (%i1) delete (a, foo (a, b, a, c, d, a), 2);
          (%o1)                    foo(b, c, d, a)

     Whether arguments are the same as EXPR_1 is determined by "=". Arguments which are equal but not "=" are not removed.

          (%i1) [is (equal (0, 0)), is (equal (0, 0.0)), is (equal (0, 0b0))];
          (%o1)                  [true, true, true]

          (%i2) [is (0 = 0), is (0 = 0.0), is (0 = 0b0)];
          (%o2)                 [true, false, false]

          (%i3) delete (0, [0, 0.0, 0b0]);
          (%o3)                     [0.0, 0.0b0]

          (%i4) is (equal ((x + y)*(x - y), x^2 - y^2));
          (%o4)                         true

          (%i5) is ((x + y)*(x - y) = x^2 - y^2);
          (%o5)                         false

          (%i6) delete ((x + y)*(x - y), [(x + y)*(x - y), x^2 - y^2]);
                                        2    2
          (%o6)                       [x  - y ]

     Categories: Lists Expressions

 -- Function: eighth (EXPR)

     Returns the 8th item of expression or list EXPR. See first for more details.

     Categories: Lists Expressions

 -- Function: endcons
     endcons (EXPR, LIST)
     endcons (EXPR_1, EXPR_2)

     endcons (EXPR, LIST) returns a new list constructed of the elements of LIST followed by EXPR. The Maxima function endcons can also be used where the second argument is other than a list and this might be useful. In this case, endcons (EXPR_1, EXPR_2) returns an expression with same operator as EXPR_2 but with argument endcons(expr_1, args(expr_2)). Examples:

          (%i1) endcons(a,[b,c,d]);
          (%o1)                     [b, c, d, a]

          (%i2) endcons(a,f(b,c,d));
          (%o2)                     f(b, c, d, a)

     In general, endcons applied to a nonlist doesn't make sense. For instance, endcons(a,b^c) results in an illegal expression, since '^' cannot take three arguments.

     When inflag is true, endcons operates on the internal structure of an expression, otherwise endcons operates on the displayed form. Especially when inflag is true, endcons applied to a nonlist sometimes gives a surprising result; for example

          (%i1) endcons(a,-a), inflag : true;
                                           2
          (%o1)                         - a

          (%i2) endcons(a,-a), inflag : false;
          (%o2)                           0

     Categories: Lists Expressions

 -- Function: fifth (EXPR)

     Returns the 5th item of expression or list EXPR. See first for more details.

     Categories: Lists Expressions

 -- Function: first (EXPR)

     Returns the first part of EXPR which may result in the first element of a list, the first row of a matrix, the first term of a sum, etc.:

          (%i1) matrix([1,2],[3,4]);
                                             [ 1  2 ]
          (%o1)                              [      ]
                                             [ 3  4 ]
          (%i2) first(%);
          (%o2)                              [1,2]
          (%i3) first(%);
          (%o3)                              1
          (%i4) first(a*b/c+d+e/x);
                                             a b
          (%o4)                              ---
                                              c
          (%i5) first(a=b/c+d+e/x);
          (%o5)                              a

     Note that first and its related functions, rest and last, work on the form of EXPR which is displayed not the form which is typed on input.  If the variable inflag is set to true however, these functions will look at the internal form of EXPR. One reason why this may make a difference is that the simplifier re-orders expressions:

          (%i1) x+y;
          (%o1)                              y+1
          (%i2) first(x+y),inflag : true;
          (%o2)                              x
          (%i3) first(x+y),inflag : false;
          (%o3)                              y

     The functions second ... tenth yield the second through the tenth part of their input argument.

     See also firstn and part

     Categories: Lists Expressions

 -- Function: firstn (EXPR, COUNT)

     Returns the first COUNT arguments of EXPR, if EXPR has at least COUNT arguments. Returns EXPR if EXPR has less than COUNT arguments.

     EXPR may be any nonatomic expression. When EXPR is something other than a list, firstn returns an expression which has the same operator as EXPR. COUNT must be a nonnegative integer.

     firstn honors the global flag inflag, which governs whether the internal form of an expression is processed (when inflag is true) or the displayed form (when inflag is false).

     Note that firstn(EXPR, 1), which returns a nonatomic expression containing the first argument, is not the same as first(EXPR), which returns the first argument by itself.

     See also lastn and rest

     Examples:

     firstn returns the first COUNT elements of EXPR, if EXPR has at least COUNT elements.

          (%i1) mylist : [1, a, 2, b, 3, x, 4 - y, 2*z + sin(u)];
          (%o1)        [1, a, 2, b, 3, x, 4 - y, 2 z + sin(u)]

          (%i2) firstn (mylist, 0);
          (%o2)                          []

          (%i3) firstn (mylist, 1);
          (%o3)                          [1]

          (%i4) firstn (mylist, 2);
          (%o4)                        [1, a]

          (%i5) firstn (mylist, 7);
          (%o5)               [1, a, 2, b, 3, x, 4 - y]

     firstn returns EXPR if EXPR has less than COUNT elements.

          (%i1) mylist : [1, a, 2, b, 3, x, 4 - y, 2*z + sin(u)];
          (%o1)        [1, a, 2, b, 3, x, 4 - y, 2 z + sin(u)]

          (%i2) firstn (mylist, 100);
          (%o2)        [1, a, 2, b, 3, x, 4 - y, 2 z + sin(u)]

     EXPR may be any nonatomic expression.

          (%i1) myfoo : foo(1, a, 2, b, 3, x, 4 - y, 2*z + sin(u));
          (%o1)      foo(1, a, 2, b, 3, x, 4 - y, 2 z + sin(u))

          (%i2) firstn (myfoo, 4);
          (%o2)                    foo(1, a, 2, b)

          (%i3) mybar : bar[m, n](1, a, 2, b, 3, x, 4 - y, 2*z + sin(u));
          (%o3)    bar    (1, a, 2, b, 3, x, 4 - y, 2 z + sin(u))
                      m, n

          (%i4) firstn (mybar, 4);
          (%o4)                  bar    (1, a, 2, b)
                                    m, n

          (%i5) mymatrix : genmatrix (lambda ([i, j], 10*i + j), 10, 4) $

          (%i6) firstn (mymatrix, 3);
                                 [ 11  12  13  14 ]
                                 [                ]
          (%o6)                  [ 21  22  23  24 ]
                                 [                ]
                                 [ 31  32  33  34 ]

     firstn honors the global flag inflag.

          (%i1) myexpr : a + b + c + d + e;
          (%o1)                   e + d + c + b + a

          (%i2) firstn (myexpr, 3), inflag=true;
          (%o2)                       c + b + a

          (%i3) firstn (myexpr, 3), inflag=false;
          (%o3)                       e + d + c

     Note that firstn(EXPR, 1) is not the same as first(EXPR).

          (%i1) firstn ([w, x, y, z], 1);
          (%o1)                          [w]

          (%i2) first ([w, x, y, z]);
          (%o2)                           w

     Categories: Lists Expressions

 -- Function: fourth (EXPR)

     Returns the 4th item of expression or list EXPR. See first for more details.

     Categories: Lists Expressions

 -- Function: join (L, M)

     Creates a new list containing the elements of lists L and M, interspersed.  The result has elements [L[1], M[1], L[2], M[2], ...].  The lists L and M may contain any type of elements.

     If the lists are different lengths, join ignores elements of the longer list.

     Maxima complains if L or M is not a list.

     See also append

     Examples:

          (%i1) L1: [a, sin(b), c!, d - 1];
          (%o1)                [a, sin(b), c!, d - 1]

          (%i2) join (L1, [1, 2, 3, 4]);
          (%o2)          [a, 1, sin(b), 2, c!, 3, d - 1, 4]

          (%i3) join (L1, [aa, bb, cc, dd, ee, ff]);
          (%o3)        [a, aa, sin(b), bb, c!, cc, d - 1, dd]

     Categories: Lists

 -- Function: last (EXPR)

     Returns the last part (term, row, element, etc.) of the EXPR.

     See also lastn

     Categories: Lists Expressions

 -- Function: lastn (EXPR, COUNT)

     Returns the last COUNT arguments of EXPR, if EXPR has at least COUNT arguments. Returns EXPR if EXPR has less than COUNT arguments.

     EXPR may be any nonatomic expression. When EXPR is something other than a list, lastn returns an expression which has the same operator as EXPR. COUNT must be a nonnegative integer.

     lastn honors the global flag inflag, which governs whether the internal form of an expression is processed (when inflag is true) or the displayed form (when inflag is false).

     Note that lastn(EXPR, 1), which returns a nonatomic expression containing the last argument, is not the same as last(EXPR), which returns the last argument by itself.

     See also firstn and rest

     Examples:

     lastn returns the last COUNT elements of EXPR, if EXPR has at least COUNT elements.

          (%i1) mylist : [1, a, 2, b, 3, x, 4 - y, 2*z + sin(u)];
          (%o1)        [1, a, 2, b, 3, x, 4 - y, 2 z + sin(u)]

          (%i2) lastn (mylist, 0);
          (%o2)                          []

          (%i3) lastn (mylist, 1);
          (%o3)                    [2 z + sin(u)]

          (%i4) lastn (mylist, 2);
          (%o4)                 [4 - y, 2 z + sin(u)]

          (%i5) lastn (mylist, 7);
          (%o5)         [a, 2, b, 3, x, 4 - y, 2 z + sin(u)]

     lastn returns EXPR if EXPR has less than COUNT elements.

          (%i1) mylist : [1, a, 2, b, 3, x, 4 - y, 2*z + sin(u)];
          (%o1)        [1, a, 2, b, 3, x, 4 - y, 2 z + sin(u)]

          (%i2) lastn (mylist, 100);
          (%o2)        [1, a, 2, b, 3, x, 4 - y, 2 z + sin(u)]

     EXPR may be any nonatomic expression.

          (%i1) myfoo : foo(1, a, 2, b, 3, x, 4 - y, 2*z + sin(u));
          (%o1)      foo(1, a, 2, b, 3, x, 4 - y, 2 z + sin(u))

          (%i2) lastn (myfoo, 4);
          (%o2)            foo(3, x, 4 - y, 2 z + sin(u))

          (%i3) mybar : bar[m, n](1, a, 2, b, 3, x, 4 - y, 2*z + sin(u));
          (%o3)    bar    (1, a, 2, b, 3, x, 4 - y, 2 z + sin(u))
                      m, n

          (%i4) lastn (mybar, 4);
          (%o4)          bar    (3, x, 4 - y, 2 z + sin(u))
                            m, n

          (%i5) mymatrix : genmatrix (lambda ([i, j], 10*i + j), 10, 4) $

          (%i6) lastn (mymatrix, 3);
                               [ 81   82   83   84  ]
                               [                    ]
          (%o6)                [ 91   92   93   94  ]
                               [                    ]
                               [ 101  102  103  104 ]

     lastn honors the global flag inflag.

          (%i1) myexpr : a + b + c + d + e;
          (%o1)                   e + d + c + b + a

          (%i2) lastn (myexpr, 3), inflag=true;
          (%o2)                       e + d + c

          (%i3) lastn (myexpr, 3), inflag=false;
          (%o3)                       c + b + a

     Note that lastn(EXPR, 1) is not the same as last(EXPR).

          (%i1) lastn ([w, x, y, z], 1);
          (%o1)                          [z]

          (%i2) last ([w, x, y, z]);
          (%o2)                           z

     Categories: Lists Expressions

 -- Function: length (EXPR)

     Returns (by default) the number of parts in the external (displayed) form of EXPR.  For lists this is the number of elements, for matrices it is the number of rows, and for sums it is the number of terms (see dispform).

     The length command is affected by the inflag switch.  So, e.g. length(a/(b*c)); gives 2 if inflag is false (Assuming exptdispflag is true), but 3 if inflag is true (the internal representation is essentially a*b^-1*c^-1).

     Determining a list's length typically needs an amount of time proportional to the number of elements in the list. If the length of a list is used inside a loop it therefore might drastically increase the performance if the length is calculated outside the loop instead.

     Categories: Lists Expressions

 -- Option variable: listarith
     Default value: true

     If false causes any arithmetic operations with lists to be suppressed; when true, list-matrix operations are contagious causing lists to be converted to matrices yielding a result which is always a matrix.  However, list-list operations should return lists.

     Categories: Lists Global flags

 -- Function: listp (EXPR)

     Returns true if EXPR is a list else false.

     Categories: Lists Predicate functions

 -- Function: lreduce
     lreduce (F, S)
     lreduce (F, S, S_0)

     Extends the binary function F to an n-ary function by composition, where S is a list.

     lreduce(F, S) returns F(... F(F(s_1, s_2), s_3), ... s_n). When the optional argument S_0 is present, the result is equivalent to lreduce(F, cons(S_0, S)).

     The function F is first applied to the leftmost list elements, thus the name "lreduce".

     See also rreduce, xreduce, and tree_reduce.

     Examples:

     lreduce without the optional argument.

          (%i1) lreduce (f, [1, 2, 3]);
          (%o1)                     f(f(1, 2), 3)

          (%i2) lreduce (f, [1, 2, 3, 4]);
          (%o2)                  f(f(f(1, 2), 3), 4)

     lreduce with the optional argument.

          (%i1) lreduce (f, [1, 2, 3], 4);
          (%o1)                  f(f(f(4, 1), 2), 3)

     lreduce applied to built-in binary operators. / is the division operator.

          (%i1) lreduce ("^", args ({a, b, c, d}));
                                         b c d
          (%o1)                       ((a ) )

          (%i2) lreduce ("/", args ({a, b, c, d}));
                                          a
          (%o2)                         -----
                                        b c d

     Categories: Lists

 -- Function: makelist
     makelist ()
     makelist (EXPR, N)
     makelist (EXPR, I, I_MAX)
     makelist (EXPR, I, I_0, I_MAX)
     makelist (EXPR, I, I_0, I_MAX, STEP)
     makelist (EXPR, X, LIST)

     The first form, makelist (), creates an empty list. The second form, makelist (EXPR), creates a list with EXPR as its single element. makelist (EXPR, N) creates a list of N elements generated from EXPR.

     The most general form, makelist (EXPR, I, I_0, I_MAX, STEP), returns the list of elements obtained when ev (EXPR, I=J) is applied to the elements J of the sequence: I_0, I_0 + STEP, I_0 + 2*STEP, ..., with |J| less than or equal to |I_MAX|.

     The increment STEP can be a number (positive or negative) or an expression. If it is omitted, the default value 1 will be used. If both I_0 and STEP are omitted, they will both have a default value of 1.

     makelist (EXPR, X, LIST) returns a list, the jth element of which is equal to ev (EXPR, X=LIST[j]) for j equal to 1 through length (LIST).

     Examples:

          (%i1) makelist (concat (x,i), i, 6);
          (%o1)               [x1, x2, x3, x4, x5, x6]

          (%i2) makelist (x=y, y, [a, b, c]);
          (%o2)                 [x = a, x = b, x = c]

          (%i3) makelist (x^2, x, 3, 2*%pi, 2);
          (%o3)                        [9, 25]

          (%i4) makelist (random(6), 4);
          (%o4)                     [2, 0, 2, 5]

          (%i5) flatten (makelist (makelist (i^2, 3), i, 4));
          (%o5)        [1, 1, 1, 4, 4, 4, 9, 9, 9, 16, 16, 16]

          (%i6) flatten (makelist (makelist (i^2, i, 3), 4));
          (%o6)         [1, 4, 9, 1, 4, 9, 1, 4, 9, 1, 4, 9]

     Categories: Lists

 -- Function: member (EXPR_1, EXPR_2)

     Returns true if is(EXPR_1 = A) for some element A in args(EXPR_2), otherwise returns false.

     expr_2 is typically a list, in which case args(EXPR_2) = EXPR_2 and is(EXPR_1 = A) for some element A in expr_2 is the test.

     member does not inspect parts of the arguments of expr_2, so it may return false even if expr_1 is a part of some argument of expr_2.

     See also elementp

     Examples:

          (%i1) member (8, [8, 8.0, 8b0]);
          (%o1)                         true

          (%i2) member (8, [8.0, 8b0]);
          (%o2)                         false

          (%i3) member (b, [a, b, c]);
          (%o3)                         true

          (%i4) member (b, [[a, b], [b, c]]);
          (%o4)                         false

          (%i5) member ([b, c], [[a, b], [b, c]]);
          (%o5)                         true

          (%i6) F (1, 1/2, 1/4, 1/8);
                                         1  1  1
          (%o6)                     F(1, -, -, -)
                                         2  4  8

          (%i7) member (1/8, %);
          (%o7)                         true

          (%i8) member ("ab", ["aa", "ab", sin(1), a + b]);
          (%o8)                         true

     Categories: Lists Expressions Predicate functions

 -- Function: ninth (EXPR)

     Returns the 9th item of expression or list EXPR. See first for more details.

     Categories: Lists Expressions

 -- Function: pop (LIST)

     pop removes and returns the first element from the list LIST. The argument LIST must be a mapatom that is bound to a nonempty list. If the argument LIST is not bound to a nonempty list, Maxima signals an error. For examples, see push

     Categories: Lists Expressions

 -- Function: push (ITEM, LIST)

     push prepends the item ITEM to the list LIST and returns a copy of the new list. The second argument LIST must be a mapatom that is bound to a list. The first argument ITEM can be any Maxima symbol or expression. If the argument LIST is not bound to a list, Maxima signals an error.

     To remove the first item from a list, see pop

     Examples:

          (%i1) ll: [];
          (%o1)                          []

          (%i2) push (x, ll);
          (%o2)                          [x]

          (%i3) push (x^2+y, ll);
                                           2
          (%o3)                      [y + x , x]

          (%i4) a: push ("string", ll);
                                               2
          (%o4)                  [string, y + x , x]

          (%i5) pop (ll);
          (%o5)                        string

          (%i6) pop (ll);
                                            2
          (%o6)                        y + x

          (%i7) pop (ll);
          (%o7)                           x

          (%i8) ll;
          (%o8)                          []

          (%i9) a;
                                               2
          (%o9)                  [string, y + x , x]

     Categories: Lists Expressions

 -- Function: rest
     rest (EXPR, N)
     rest (EXPR)

     Returns EXPR with its first N elements removed if N is positive and its last - N elements removed if N is negative. If N is 1 it may be omitted. The first argument EXPR may be a list, matrix, or other expression. When EXPR is an atom, rest signals an error; when EXPR is an empty list and partswitch is false, rest signals an error. When EXPR is an empty list and partswitch is true, rest returns end.

     Applying rest to expression such as f(a,b,c) returns f(b,c). In general, applying rest to a nonlist doesn't make sense. For example, because '^' requires two arguments, rest(a^b) results in an error message. The functions args and op may be useful as well, since args(a^b) returns [a,b] and op(a^b) returns ^.

     See also firstn and lastn

          (%i1) rest(a+b+c);
          (%o1) b+a
          (%i2) rest(a+b+c,2);
          (%o2) a
          (%i3) rest(a+b+c,-2);
          (%o3) c

     Categories: Lists Expressions

 -- Function: reverse (LIST)

     Reverses the order of the members of the LIST (not the members themselves).  reverse also works on general expressions, e.g.  reverse(a=b); gives b=a.

     See also sreverse

     Categories: Lists Expressions

 -- Function: rreduce
     rreduce (F, S)
     rreduce (F, S, S_{N + 1})

     Extends the binary function F to an n-ary function by composition, where S is a list.

     rreduce(F, S) returns F(s_1, ... F(s_{n - 2}, F(s_{n - 1}, s_n))). When the optional argument S_{N + 1} is present, the result is equivalent to rreduce(F, endcons(S_{N + 1}, S)).

     The function F is first applied to the rightmost list elements, thus the name "rreduce".

     See also lreduce, tree_reduce, and xreduce.

     Examples:

     rreduce without the optional argument.

          (%i1) rreduce (f, [1, 2, 3]);
          (%o1)                     f(1, f(2, 3))

          (%i2) rreduce (f, [1, 2, 3, 4]);
          (%o2)                  f(1, f(2, f(3, 4)))

     rreduce with the optional argument.

          (%i1) rreduce (f, [1, 2, 3], 4);
          (%o1)                  f(1, f(2, f(3, 4)))

     rreduce applied to built-in binary operators. / is the division operator.

          (%i1) rreduce ("^", args ({a, b, c, d}));
                                           d
                                          c
                                         b
          (%o1)                         a

          (%i2) rreduce ("/", args ({a, b, c, d}));
                                         a c
          (%o2)                          ---
                                         b d

     Categories: Lists

 -- Function: second (EXPR)

     Returns the 2nd item of expression or list EXPR. See first for more details.

     Categories: Lists Expressions

 -- Function: seventh (EXPR)

     Returns the 7th item of expression or list EXPR. See first for more details.

     Categories: Lists Expressions

 -- Function: sixth (EXPR)

     Returns the 6th item of expression or list EXPR. See first for more details.

     Categories: Lists Expressions

 -- Function: sort
     sort (L, P)
     sort (L)

     sort(L, P) sorts a list L according to a predicate P of two arguments which defines a strict weak order on the elements of L. If P(a, b) is true, then a appears before b in the result. If neither P(a, b) nor P(b, a) are true, then a and b are equivalent, and appear in the result in the same order as in the input. That is, sort is a stable sort.

     If P(a, b) and P(b, a) are both true for some elements of L, then P is not a valid sort predicate, and the result is undefined. If P(a, b) is something other than true or false, sort signals an error.

     The predicate may be specified as the name of a function or binary infix operator, or as a lambda expression.  If specified as the name of an operator, the name must be enclosed in double quotes.

     The sorted list is returned as a new object; the argument L is not modified.

     sort(L) is equivalent to sort(L, orderlessp).

     The default sorting order is ascending, as determined by orderlessp The predicate ordergreatp sorts a list in descending order.

     All Maxima atoms and expressions are comparable under orderlessp and ordergreatp.

     Operators < and > order numbers, constants, and constant expressions by magnitude. Note that orderlessp and ordergreatp do not order numbers, constants, and constant expressions by magnitude.

     ordermagnitudep orders numbers, constants, and constant expressions the same as <, and all other elements the same as orderlessp.

     Examples:

     sort sorts a list according to a predicate of two arguments which defines a strict weak order on the elements of the list.

          (%i1) sort ([1, a, b, 2, 3, c], 'orderlessp);
          (%o1)                  [1, 2, 3, a, b, c]

          (%i2) sort ([1, a, b, 2, 3, c], 'ordergreatp);
          (%o2)                  [c, b, a, 3, 2, 1]

     The predicate may be specified as the name of a function or binary infix operator, or as a lambda expression.  If specified as the name of an operator, the name must be enclosed in double quotes.

          (%i1) L : [[1, x], [3, y], [4, w], [2, z]];
          (%o1)           [[1, x], [3, y], [4, w], [2, z]]

          (%i2) foo (a, b) := a[1] > b[1];
          (%o2)                 foo(a, b) := a  > b
                                              1    1

          (%i3) sort (L, 'foo);
          (%o3)           [[4, w], [3, y], [2, z], [1, x]]

          (%i4) infix (">>");
          (%o4)                          >>

          (%i5) a >> b := a[1] > b[1];
          (%o5)                  (a >> b) := a  > b
                                              1    1

          (%i6) sort (L, ">>");
          (%o6)           [[4, w], [3, y], [2, z], [1, x]]

          (%i7) sort (L, lambda ([a, b], a[1] > b[1]));
          (%o7)           [[4, w], [3, y], [2, z], [1, x]]

     sort(L) is equivalent to sort(L, orderlessp).

          (%i1) L : [a, 2*b, -5, 7, 1 + %e, %pi];
          (%o1)             [a, 2 b, - 5, 7, %e + 1, %pi]

          (%i2) sort (L);
          (%o2)             [- 5, 7, %e + 1, %pi, a, 2 b]

          (%i3) sort (L, 'orderlessp);
          (%o3)             [- 5, 7, %e + 1, %pi, a, 2 b]

     The default sorting order is ascending, as determined by orderlessp The predicate ordergreatp sorts a list in descending order.

          (%i1) L : [a, 2*b, -5, 7, 1 + %e, %pi];
          (%o1)             [a, 2 b, - 5, 7, %e + 1, %pi]

          (%i2) sort (L);
          (%o2)             [- 5, 7, %e + 1, %pi, a, 2 b]

          (%i3) sort (L, 'ordergreatp);
          (%o3)             [2 b, a, %pi, %e + 1, 7, - 5]

     All Maxima atoms and expressions are comparable under orderlessp and ordergreatp.

          (%i1) L : [11, -17, 29b0, 9*c, 7.55, foo(x, y), -5/2, b + a];
                                                           5
          (%o1)  [11, - 17, 2.9b1, 9 c, 7.55, foo(x, y), - -, b + a]
                                                           2

          (%i2) sort (L, orderlessp);
                          5
          (%o2)  [- 17, - -, 7.55, 11, 2.9b1, b + a, 9 c, foo(x, y)]
                          2

          (%i3) sort (L, ordergreatp);
                                                            5
          (%o3)  [foo(x, y), 9 c, b + a, 2.9b1, 11, 7.55, - -, - 17]
                                                            2

     Operators < and > order numbers, constants, and constant expressions by magnitude. Note that orderlessp and ordergreatp do not order numbers, constants, and constant expressions by magnitude.

          (%i1) L : [%pi, 3, 4, %e, %gamma];
          (%o1)                [%pi, 3, 4, %e, %gamma]

          (%i2) sort (L, ">");
          (%o2)                [4, %pi, 3, %e, %gamma]

          (%i3) sort (L, ordergreatp);
          (%o3)                [%pi, %gamma, %e, 4, 3]

     ordermagnitudep orders numbers, constants, and constant expressions the same as <, and all other elements the same as orderlessp.

          (%i1) L: [%i, 1+%i, 2*x, minf, inf, %e, sin(1), 0,1,2,3, 1.0, 1.0b0];
          (%o1) [%i, %i + 1, 2 x, minf, inf, %e, sin(1), 0, 1, 2, 3, 1.0,
                                                                     1.0b0]

          (%i2) sort (L, ordermagnitudep);
          (%o2) [minf, 0, sin(1), 1, 1.0, 1.0b0, 2, %e, 3, inf, %i,
                                                               %i + 1, 2 x]

          (%i3) sort (L, orderlessp);
          (%o3) [0, 1, 1.0, 2, 3, sin(1), 1.0b0, %e, %i, %i + 1, inf,
                                                                 minf, 2 x]

     Categories: Lists

 -- Function: sublist (LIST, P)

     Returns the list of elements of LIST for which the predicate p returns true.

     Example:

          (%i1) L: [1, 2, 3, 4, 5, 6];
          (%o1)                  [1, 2, 3, 4, 5, 6]

          (%i2) sublist (L, evenp);
          (%o2)                       [2, 4, 6]

     Categories: Lists

 -- Function: sublist_indices (L, P)

     Returns the indices of the elements x of the list L for which the predicate maybe(P(x)) returns true; this excludes unknown as well as false. P may be the name of a function or a lambda expression. L must be a literal list.

     Examples:

          (%i1) sublist_indices ('[a, b, b, c, 1, 2, b, 3, b],
                                 lambda ([x], x='b));
          (%o1)                     [2, 3, 7, 9]

          (%i2) sublist_indices ('[a, b, b, c, 1, 2, b, 3, b], symbolp);
          (%o2)                  [1, 2, 3, 4, 7, 9]

          (%i3) sublist_indices ([1 > 0, 1 < 0, 2 < 1, 2 > 1, 2 > 0],
                                 identity);
          (%o3)                       [1, 4, 5]

          (%i4) assume (x < -1);
          (%o4)                       [x < - 1]

          (%i5) map (maybe, [x > 0, x < 0, x < -2]);
          (%o5)                [false, true, unknown]

          (%i6) sublist_indices ([x > 0, x < 0, x < -2], identity);
          (%o6)                          [2]

     Categories: Lists

 -- Function: tenth (EXPR)

     Returns the 10th item of expression or list EXPR. See first for more details.

     Categories: Lists Expressions

 -- Function: third (EXPR)

     Returns the 3rd item of expression or list EXPR. See first for more details.

     Categories: Lists Expressions

 -- Function: tree_reduce
     tree_reduce (F, S)
     tree_reduce (F, S, S_0)

     Extends the binary function F to an n-ary function by composition, where S is a set or list.

     tree_reduce is equivalent to the following: Apply F to successive pairs of elements to form a new list [F(S_1, S_2), F(S_3, S_4), ...], carrying the final element unchanged if there are an odd number of elements. Then repeat until the list is reduced to a single element, which is the return value.

     When the optional argument S_0 is present, the result is equivalent tree_reduce(F, cons(S_0, S)).

     For addition of floating point numbers, tree_reduce may return a sum that has a smaller rounding error than either rreduce or lreduce.

     The elements of S and the partial results may be arranged in a minimum-depth binary tree, thus the name "tree_reduce".

     Examples:

     tree_reduce applied to a list with an even number of elements.

          (%i1) tree_reduce (f, [a, b, c, d]);
          (%o1)                  f(f(a, b), f(c, d))

     tree_reduce applied to a list with an odd number of elements.

          (%i1) tree_reduce (f, [a, b, c, d, e]);
          (%o1)               f(f(f(a, b), f(c, d)), e)

     Categories: Sets Lists

 -- Function: unique (L)

     Returns the unique elements of the list L.

     When all the elements of L are unique, unique returns a shallow copy of L, not L itself.

     If L is not a list, unique returns L.

     Example:

          (%i1) unique ([1, %pi, a + b, 2, 1, %e, %pi, a + b, [1]]);
          (%o1)              [1, 2, %e, %pi, [1], b + a]

 -- Function: xreduce
     xreduce (F, S)
     xreduce (F, S, S_0)

     Extends the function F to an n-ary function by composition, or, if F is already n-ary, applies F to S. When F is not n-ary, xreduce is the same as lreduce. The argument S is a list.

     Functions known to be n-ary include addition +, multiplication *, and, or, max, min, and append. Functions may also be declared n-ary by declare(F, nary). For these functions, xreduce is expected to be faster than either rreduce or lreduce.

     When the optional argument S_0 is present, the result is equivalent to xreduce(S, cons(S_0, S)).

     Floating point addition is not exactly associative; be that as it may, xreduce applies Maxima's n-ary addition when S contains floating point numbers.

     Examples:

     xreduce applied to a function known to be n-ary. F is called once, with all arguments.

          (%i1) declare (F, nary);
          (%o1)                         done

          (%i2) F ([L]) := L;
          (%o2)                      F([L]) := L

          (%i3) xreduce (F, [a, b, c, d, e]);
          (%o3)                    [a, b, c, d, e]

     xreduce applied to a function not known to be n-ary. G is called several times, with two arguments each time.

          (%i1) G ([L]) := L;
          (%o1)                      G([L]) := L

          (%i2) xreduce (G, [a, b, c, d, e]);
          (%o2)                 [[[[a, b], c], d], e]

          (%i3) lreduce (G, [a, b, c, d, e]);
          (%o3)                 [[[[a, b], c], d], e]

     Categories: Sets Lists

Performance considerations for Lists
------------------------------------

Lists provide efficient ways of appending and removing elements. They can be created without knowing their final dimensions. Lisp provides efficient means of copying and handling lists. Also nested lists do not need to be strictly rectangular. These advantages over declared arrays come with the drawback that the amount of time needed for accessing a random element within a list may be roughly proportional to the element's distance from its beginning. Efficient traversal of lists is still possible, though, by using the list as a stack or a fifo:

     (%i1) l:[Test,1,2,3,4];
     (%o1)                  [Test, 1, 2, 3, 4]

     (%i2) while l # [] do
        disp(pop(l));
                                   Test

                                     1

                                     2

                                     3

                                     4

     (%o2)                         done

Another even faster example would be:

     (%i1) l:[Test,1,2,3,4];
     (%o1)                  [Test, 1, 2, 3, 4]

     (%i2) for i in l do
        disp(pop(l));
                                   Test

                                     1

                                     2

                                     3

                                     4

     (%o2)                         done

Beginning traversal with the last element of a list is possible after reversing the list using reverse (). If the elements of a long list need to be processed in a different order performance might be increased by converting the list into a declared array first.

Note also that the ending condition of for loops is tested for every iteration which means that the result of a length should be cached if it is used in the ending condition:

     (%i1) l:makelist(i,i,1,100000)$

     (%i2) lngth:length(l);
     (%o2)                        100000

     (%i3) x:1;
     (%o3)                           1

     (%i4) for i:1 thru lngth do
         x:x+1$

     (%i5) x;
     (%o5)                        100001