Introduction to Lists
=====================

Lists are the basic building block for Maxima and Lisp.   All data types other than arrays, hash tables, 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
=================================

 -- 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).

     Do example(append); for an example.

 -- Function: assoc (KEY, LIST, DEFAULT)
 -- Function: assoc (KEY, LIST)
     This function searches for the KEY in the left hand side of the input LIST of the form [x,y,z,...] where each of the LIST elements is an expression of a binary operand and 2 elements.  For example x=1, 2^3, [a,b] etc. The KEY is checked againts the first operand.  assoc returns the second operand if the key is found.  If the key is not found it either returns the DEFAULT value.  DEFAULT is optional and defaults to false.

 -- Function: atom (EXPR)
     Returns true if EXPR is atomic (i.e. a number, name or string) else false.  Thus atom(5) is true while atom(a[1]) and atom(sin(x)) are false (asuming a[1] and x are unbound).

 -- Function: cons (EXPR, LIST)
     Returns a new list constructed of the element EXPR as its first element, followed by the elements of LIST.  cons also works on other expressions, e.g. cons(x, f(a,b,c));  ->  f(x,a,b,c).

 -- Function: copylist (LIST)
     Returns a copy of the list LIST.

 -- 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.

 -- Function: delete (EXPR_1, EXPR_2)
 -- Function: delete (EXPR_1, EXPR_2, N)
     Removes all occurrences of EXPR_1 from EXPR_2.  EXPR_1 may be a term of EXPR_2 (if it is a sum) or a factor of EXPR_2 (if it is a product).

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

     delete(EXPR_1, EXPR_2, N) removes the first N occurrences of EXPR_1 from EXPR_2.  If there are fewer than N occurrences of EXPR_1 in EXPR_2 then all occurrences will be deleted.

          (%i1) delete(a, f(a,b,c,d,a));
          (%o1)                      f(b, c, d)
          (%i2) delete(a, f(a,b,a,c,d,a), 2);
          (%o2)                     f(b, c, d, a)

 -- Function: eighth (EXPR)
     Returns the 8'th item of expression or list EXPR. See first for more details.

 -- Function: endcons (EXPR, LIST)
     Returns a new list consisting of the elements of list followed by EXPR.  endcons also works on general expressions, e.g. endcons(x, f(a,b,c));  ->  f(a,b,c,x).

 -- Function: fifth (EXPR)
     Returns the 5'th item of expression or list EXPR. See first for more details.

 -- 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.  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.  Note that the simplifier re-orders expressions.  Thus first(x+y) will be x if inflag is true and y if inflag is false (first(y+x) gives the same results).  The functions second .. tenth yield the second through the tenth part of their input argument.

 -- Function: fourth (EXPR)
     Returns the 4'th item of expression or list EXPR. See first for more details.

 -- Function: get (A, I)
     Retrieves the user property indicated by I associated with atom A or returns false if a doesn't have property I.

     get evaluates its arguments.

          (%i1) put (%e, 'transcendental, 'type);
          (%o1)                    transcendental
          (%i2) put (%pi, 'transcendental, 'type)$
          (%i3) put (%i, 'algebraic, 'type)$
          (%i4) typeof (expr) := block ([q],
                  if numberp (expr)
                  then return ('algebraic),
                  if not atom (expr)
                  then return (maplist ('typeof, expr)),
                  q: get (expr, 'type),
                  if q=false
                  then errcatch (error(expr,"is not numeric.")) else q)$
          (%i5) typeof (2*%e + x*%pi);
          x is not numeric.
          (%o5)  [[transcendental, []], [algebraic, transcendental]]
          (%i6) typeof (2*%e + %pi);
          (%o6)     [transcendental, [algebraic, transcendental]]

 -- 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.

     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]

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

 -- 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).

 -- 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.

 -- Function: listp (EXPR)
     Returns true if EXPR is a list else false.

 -- Function: makelist (EXPR, I, I_0, I_1)
 -- Function: makelist (EXPR, X, LIST)
     Constructs and returns a list, each element of which is generated from EXPR.

     makelist (EXPR, I, I_0, I_1) returns a list, the j'th element of which is equal to ev (EXPR, I=j) for j equal to I_0 through I_1.

     makelist (EXPR, X, LIST) returns a list, the j'th 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,1,6);
          (%o1)               [x1, x2, x3, x4, x5, x6]
          (%i2) makelist(x=y,y,[a,b,c]);
          (%o2)                 [x = a, x = b, x = c]

 -- 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

 -- Function: ninth (EXPR)
     Returns the 9'th item of expression or list EXPR. See first for more details.

 -- Function: rest (EXPR, N)
 -- Function: 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.  EXPR may be a list, matrix, or other expression.

 -- 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.

 -- Function: second (EXPR)
     Returns the 2'nd item of expression or list EXPR. See first for more details.

 -- Function: seventh (EXPR)
     Returns the 7'th item of expression or list EXPR. See first for more details.

 -- Function: sixth (EXPR)
     Returns the 6'th item of expression or list EXPR. See first for more details.

 -- 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]

 -- Function: tenth (EXPR)
     Returns the 10'th item of expression or list EXPR. See first for more details.

 -- Function: third (EXPR)
     Returns the 3'rd item of expression or list EXPR. See first for more details.