@c -----------------------------------------------------------------------------
@page
@node Arrays, Structures, Lists, Data Types and Structures
@section Arrays
@c -----------------------------------------------------------------------------

@menu
* Functions and Variables for Arrays::  
@end menu

@c -----------------------------------------------------------------------------
@node Functions and Variables for Arrays,  , Arrays, Arrays
@subsection Functions and Variables for Arrays
@c -----------------------------------------------------------------------------

@c -----------------------------------------------------------------------------
@anchor{array}
@deffn  {Function} array (@var{name}, @var{dim_1}, @dots{}, @var{dim_n})
@deffnx {Function} array (@var{name}, @var{type}, @var{dim_1}, @dots{}, @var{dim_n})
@deffnx {Function} array ([@var{name_1}, @dots{}, @var{name_m}], @var{dim_1}, @dots{}, @var{dim_n})

Creates an @math{n}-dimensional array.  @math{n} may be less than or equal to 5.
The subscripts for the @math{i}'th dimension are the integers running from 0 to
@var{dim_i}.

@code{array (@var{name}, @var{dim_1}, ..., @var{dim_n})} creates a general
array.

@code{array (@var{name}, @var{type}, @var{dim_1}, ..., @var{dim_n})} creates
an array, with elements of a specified type.  @var{type} can be @code{fixnum}
for integers of limited size or @code{flonum} for floating-point numbers.

@code{array ([@var{name_1}, ..., @var{name_m}], @var{dim_1}, ..., @var{dim_n})}
creates @math{m} arrays, all of the same dimensions.
@c SAME TYPE AS WELL ??

@c THIS DISCUSSION OF UNDECLARED ARRAYS REALLY WANTS TO BE SOMEWHERE ELSE
If the user assigns to a subscripted variable before declaring the
corresponding array, an undeclared array is created.
Undeclared arrays, otherwise known as hashed arrays (because hash
coding is done on the subscripts), are more general than declared
arrays.  The user does not declare their maximum size, and they grow
dynamically by hashing as more elements are assigned values.  The
subscripts of undeclared arrays need not even be numbers.  However,
unless an array is rather sparse, it is probably more efficient to
declare it when possible than to leave it undeclared.  The @code{array}
function can be used to transform an undeclared array into a declared
array.
@c HOW DOES ONE CHANGE AN UNDECLARED ARRAY INTO A DECLARED ARRAY EXACTLY ??

@opencatbox
@category{Arrays}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{arrayapply}
@deffn {Function} arrayapply (@var{A}, [@var{i_1}, @dots{}, @var{i_n}])

Evaluates @code{@var{A} [@var{i_1}, ..., @var{i_n}]},
where @var{A} is an array and @var{i_1}, @dots{}, @var{i_n} are integers.

This is reminiscent of @mrefcomma{apply} except the first argument is an array
instead of a function.

@opencatbox
@category{Expressions} @category{Arrays}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{arrayinfo}
@deffn {Function} arrayinfo (@var{A})

Returns information about the array @var{A}.
The argument @var{A} may be a declared array, an undeclared (hashed) array,
an array function, or a subscripted function.

For declared arrays, @code{arrayinfo} returns a list comprising the atom
@code{declared}, the number of dimensions, and the size of each dimension.
The elements of the array, both bound and unbound, are returned by
@code{listarray}.

For undeclared arrays (hashed arrays), @code{arrayinfo} returns a list
comprising the atom @code{hashed}, the number of subscripts,
and the subscripts of every element which has a value.
The values are returned by @code{listarray}.

For array functions, @code{arrayinfo} returns a list comprising the atom
@code{hashed}, the number of subscripts,
and any subscript values for which there are stored function values.
The stored function values are returned by @code{listarray}.

For subscripted functions, @code{arrayinfo} returns a list comprising the atom
@code{hashed}, the number of subscripts,
and any subscript values for which there are lambda expressions.
The lambda expressions are returned by @code{listarray}.

See also @mrefdot{listarray}

Examples:

@code{arrayinfo} and @code{listarray} applied to a declared array.

@c ===beg===
@c array (aa, 2, 3);
@c aa [2, 3] : %pi;
@c aa [1, 2] : %e;
@c arrayinfo (aa);
@c listarray (aa);
@c ===end===
@example
@group
(%i1) array (aa, 2, 3);
(%o1)                          aa
@end group
@group
(%i2) aa [2, 3] : %pi;
(%o2)                          %pi
@end group
@group
(%i3) aa [1, 2] : %e;
(%o3)                          %e
@end group
@group
(%i4) arrayinfo (aa);
(%o4)                 [declared, 2, [2, 3]]
@end group
@group
(%i5) listarray (aa);
(%o5) [#####, #####, #####, #####, #####, #####, %e, #####, 
                                        #####, #####, #####, %pi]
@end group
@end example

@code{arrayinfo} and @code{listarray} applied to an undeclared (hashed) array.

@c ===beg===
@c bb [FOO] : (a + b)^2;
@c bb [BAR] : (c - d)^3;
@c arrayinfo (bb);
@c listarray (bb);
@c ===end===
@example
@group
(%i1) bb [FOO] : (a + b)^2;
                                   2
(%o1)                       (b + a)
@end group
@group
(%i2) bb [BAR] : (c - d)^3;
                                   3
(%o2)                       (c - d)
@end group
@group
(%i3) arrayinfo (bb);
(%o3)               [hashed, 1, [BAR], [FOO]]
@end group
@group
(%i4) listarray (bb);
                              3         2
(%o4)                 [(c - d) , (b + a) ]
@end group
@end example

@code{arrayinfo} and @code{listarray} applied to an array function.

@c ===beg===
@c cc [x, y] := y / x;
@c cc [u, v];
@c cc [4, z];
@c arrayinfo (cc);
@c listarray (cc);
@c ===end===
@example
@group
(%i1) cc [x, y] := y / x;
                                     y
(%o1)                      cc     := -
                             x, y    x
@end group
@group
(%i2) cc [u, v];
                                v
(%o2)                           -
                                u
@end group
@group
(%i3) cc [4, z];
                                z
(%o3)                           -
                                4
@end group
@group
(%i4) arrayinfo (cc);
(%o4)              [hashed, 2, [4, z], [u, v]]
@end group
@group
(%i5) listarray (cc);
                              z  v
(%o5)                        [-, -]
                              4  u
@end group
@end example

@code{arrayinfo} and @code{listarray} applied to a subscripted function.

@c ===beg===
@c dd [x] (y) := y ^ x;
@c dd [a + b];
@c dd [v - u];
@c arrayinfo (dd);
@c listarray (dd);
@c ===end===
@example
@group
(%i1) dd [x] (y) := y ^ x;
                                     x
(%o1)                     dd (y) := y
                            x
@end group
@group
(%i2) dd [a + b];
                                    b + a
(%o2)                  lambda([y], y     )
@end group
@group
(%i3) dd [v - u];
                                    v - u
(%o3)                  lambda([y], y     )
@end group
@group
(%i4) arrayinfo (dd);
(%o4)             [hashed, 1, [b + a], [v - u]]
@end group
@group
(%i5) listarray (dd);
                         b + a                v - u
(%o5)      [lambda([y], y     ), lambda([y], y     )]
@end group
@end example

@opencatbox
@category{Arrays}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{arraymake}
@deffn {Function} arraymake (@var{A}, [@var{i_1}, @dots{}, @var{i_n}])

Returns the expression @code{@var{A}[@var{i_1}, ..., @var{i_n}]}.
The result is an unevaluated array reference.

@code{arraymake} is reminiscent of @mrefcomma{funmake} except the return value
is an unevaluated array reference instead of an unevaluated function call.

Examples:
@c ===beg===
@c arraymake (A, [1]);
@c arraymake (A, [k]);
@c arraymake (A, [i, j, 3]);
@c array (A, fixnum, 10);
@c fillarray (A, makelist (i^2, i, 1, 11));
@c arraymake (A, [5]);
@c ''%;
@c L : [a, b, c, d, e];
@c arraymake ('L, [n]);
@c ''%, n = 3;
@c A2 : make_array (fixnum, 10);
@c fillarray (A2, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
@c arraymake ('A2, [8]);
@c ''%;
@c ===end===
@example
@group
(%i1) arraymake (A, [1]);
(%o1)                          A
                                1
@end group
@group
(%i2) arraymake (A, [k]);
(%o2)                          A
                                k
@end group
@group
(%i3) arraymake (A, [i, j, 3]);
(%o3)                       A
                             i, j, 3
@end group
@group
(%i4) array (A, fixnum, 10);
(%o4)                           A
@end group
@group
(%i5) fillarray (A, makelist (i^2, i, 1, 11));
(%o5)                           A
@end group
@group
(%i6) arraymake (A, [5]);
(%o6)                          A
                                5
@end group
@group
(%i7) ''%;
(%o7)                          36
@end group
@group
(%i8) L : [a, b, c, d, e];
(%o8)                    [a, b, c, d, e]
@end group
@group
(%i9) arraymake ('L, [n]);
(%o9)                          L
                                n
@end group
@group
(%i10) ''%, n = 3;
(%o10)                          c
@end group
@group
(%i11) A2 : make_array (fixnum, 10);
(%o11)          @{Array:  #(0 0 0 0 0 0 0 0 0 0)@}
@end group
@group
(%i12) fillarray (A2, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
(%o12)          @{Array:  #(1 2 3 4 5 6 7 8 9 10)@}
@end group
@group
(%i13) arraymake ('A2, [8]);
(%o13)                         A2
                                 8
@end group
@group
(%i14) ''%;
(%o14)                          9
@end group
@end example

@opencatbox
@category{Expressions} @category{Arrays}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{arrays}
@defvr {System variable} arrays
Default value: @code{[]}

@code{arrays} is a list of arrays that have been allocated.
These comprise arrays declared by @code{array}, hashed arrays constructed by
implicit definition (assigning something to an array element),
and array functions defined by @code{:=} and @code{define}.
Arrays defined by @mref{make_array} are not included.

See also
@mrefcomma{array} @mrefcomma{arrayapply} @mrefcomma{arrayinfo}@w{}
@mrefcomma{arraymake} @mrefcomma{fillarray} @mrefcomma{listarray} and
@mrefdot{rearray}
@c IS THIS AN EXHAUSTIVE LIST ??

Examples:

@c ===beg===
@c array (aa, 5, 7);
@c bb [FOO] : (a + b)^2;
@c cc [x] := x/100;
@c dd : make_array ('any, 7);
@c arrays;
@c ===end===
@example
@group
(%i1) array (aa, 5, 7);
(%o1)                          aa
@end group
@group
(%i2) bb [FOO] : (a + b)^2;
                                   2
(%o2)                       (b + a)
@end group
@group
(%i3) cc [x] := x/100;
                                   x
(%o3)                      cc  := ---
                             x    100
@end group
@group
(%i4) dd : make_array ('any, 7);
(%o4)       @{Array:  #(NIL NIL NIL NIL NIL NIL NIL)@}
@end group
@group
(%i5) arrays;
(%o5)                     [aa, bb, cc]
@end group
@end example

@opencatbox
@category{Arrays} @category{Global variables}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{arraysetapply}
@deffn {Function} arraysetapply (@var{A}, [@var{i_1}, @dots{}, @var{i_n}], @var{x})

Assigns @var{x} to @code{@var{A}[@var{i_1}, ..., @var{i_n}]},
where @var{A} is an array and @var{i_1}, @dots{}, @var{i_n} are integers.

@code{arraysetapply} evaluates its arguments.

@opencatbox
@category{Expressions} @category{Arrays}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{fillarray}
@deffn {Function} fillarray (@var{A}, @var{B})

Fills array @var{A} from @var{B}, which is a list or an array.

If a specific type was declared for @var{A} when it was created,
it can only be filled with elements of that same type;
it is an error if an attempt is made to copy an element of a different type.

If the dimensions of the arrays @var{A} and @var{B} are
different, @var{A} is filled in row-major order.  If there are not enough
elements in @var{B} the last element is used to fill out the
rest of @var{A}.  If there are too many, the remaining ones are ignored.

@code{fillarray} returns its first argument.

Examples:

Create an array of 9 elements and fill it from a list.
@c ===beg===
@c array (a1, fixnum, 8);
@c listarray (a1);
@c fillarray (a1, [1, 2, 3, 4, 5, 6, 7, 8, 9]);
@c listarray (a1);
@c ===end===
@example
@group
(%i1) array (a1, fixnum, 8);
(%o1)                          a1
@end group
@group
(%i2) listarray (a1);
(%o2)              [0, 0, 0, 0, 0, 0, 0, 0, 0]
@end group
@group
(%i3) fillarray (a1, [1, 2, 3, 4, 5, 6, 7, 8, 9]);
(%o3)                          a1
@end group
@group
(%i4) listarray (a1);
(%o4)              [1, 2, 3, 4, 5, 6, 7, 8, 9]
@end group
@end example

When there are too few elements to fill the array,
the last element is repeated.
When there are too many elements,
the extra elements are ignored.
@c ===beg===
@c a2 : make_array (fixnum, 8);
@c fillarray (a2, [1, 2, 3, 4, 5]);
@c fillarray (a2, [4]);
@c fillarray (a2, makelist (i, i, 1, 100));
@c ===end===
@example
@group
(%i1) a2 : make_array (fixnum, 8);
(%o1)             @{Array:  #(0 0 0 0 0 0 0 0)@}
@end group
@group
(%i2) fillarray (a2, [1, 2, 3, 4, 5]);
(%o2)             @{Array:  #(1 2 3 4 5 5 5 5)@}
@end group
@group
(%i3) fillarray (a2, [4]);
(%o3)             @{Array:  #(4 4 4 4 4 4 4 4)@}
@end group
@group
(%i4) fillarray (a2, makelist (i, i, 1, 100));
(%o4)             @{Array:  #(1 2 3 4 5 6 7 8)@}
@end group
@end example

Multple-dimension arrays are filled in row-major order.

@c ===beg===
@c a3 : make_array (fixnum, 2, 5);
@c fillarray (a3, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
@c a4 : make_array (fixnum, 5, 2);
@c fillarray (a4, a3);
@c ===end===
@example
@group
(%i1) a3 : make_array (fixnum, 2, 5);
(%o1)        @{Array:  #2A((0 0 0 0 0) (0 0 0 0 0))@}
@end group
@group
(%i2) fillarray (a3, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
(%o2)        @{Array:  #2A((1 2 3 4 5) (6 7 8 9 10))@}
@end group
@group
(%i3) a4 : make_array (fixnum, 5, 2);
(%o3)     @{Array:  #2A((0 0) (0 0) (0 0) (0 0) (0 0))@}
@end group
@group
(%i4) fillarray (a4, a3);
(%o4)     @{Array:  #2A((1 2) (3 4) (5 6) (7 8) (9 10))@}
@end group
@end example

@opencatbox
@category{Arrays}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{listarray}
@deffn {Function} listarray (@var{A})

Returns a list of the elements of the array @var{A}.
The argument @var{A} may be a declared array, an undeclared (hashed) array,
an array function, or a subscripted function.

Elements are listed in row-major order.
That is, elements are sorted according to the first index, then according to
the second index, and so on.  The sorting order of index values is the same as
the order established by @mrefdot{orderless}

For undeclared arrays, array functions, and subscripted functions,
the elements correspond to the index values returned by @mrefdot{arrayinfo}

Unbound elements of declared general arrays (that is, not @code{fixnum} and not
@code{flonum}) are returned as @code{#####}.
Unbound elements of declared @code{fixnum} or @code{flonum} arrays
are returned as 0 or 0.0, respectively.
Unbound elements of undeclared arrays, array functions,
and subscripted functions are not returned.

Examples:

@code{listarray} and @code{arrayinfo} applied to a declared array.

@c ===beg===
@c array (aa, 2, 3);
@c aa [2, 3] : %pi;
@c aa [1, 2] : %e;
@c listarray (aa);
@c arrayinfo (aa);
@c ===end===
@example
@group
(%i1) array (aa, 2, 3);
(%o1)                          aa
@end group
@group
(%i2) aa [2, 3] : %pi;
(%o2)                          %pi
@end group
@group
(%i3) aa [1, 2] : %e;
(%o3)                          %e
@end group
@group
(%i4) listarray (aa);
(%o4) [#####, #####, #####, #####, #####, #####, %e, #####, 
                                        #####, #####, #####, %pi]
@end group
@group
(%i5) arrayinfo (aa);
(%o5)                 [declared, 2, [2, 3]]
@end group
@end example

@code{listarray} and @code{arrayinfo} applied to an undeclared (hashed) array.

@c ===beg===
@c bb [FOO] : (a + b)^2;
@c bb [BAR] : (c - d)^3;
@c listarray (bb);
@c arrayinfo (bb);
@c ===end===
@example
@group
(%i1) bb [FOO] : (a + b)^2;
                                   2
(%o1)                       (b + a)
@end group
@group
(%i2) bb [BAR] : (c - d)^3;
                                   3
(%o2)                       (c - d)
@end group
@group
(%i3) listarray (bb);
                              3         2
(%o3)                 [(c - d) , (b + a) ]
@end group
@group
(%i4) arrayinfo (bb);
(%o4)               [hashed, 1, [BAR], [FOO]]
@end group
@end example

@code{listarray} and @code{arrayinfo} applied to an array function.

@c ===beg===
@c cc [x, y] := y / x;
@c cc [u, v];
@c cc [4, z];
@c listarray (cc);
@c arrayinfo (cc);
@c ===end===
@example
@group
(%i1) cc [x, y] := y / x;
                                     y
(%o1)                      cc     := -
                             x, y    x
@end group
@group
(%i2) cc [u, v];
                                v
(%o2)                           -
                                u
@end group
@group
(%i3) cc [4, z];
                                z
(%o3)                           -
                                4
@end group
@group
(%i4) listarray (cc);
                              z  v
(%o4)                        [-, -]
                              4  u
@end group
@group
(%i5) arrayinfo (cc);
(%o5)              [hashed, 2, [4, z], [u, v]]
@end group
@end example

@code{listarray} and @code{arrayinfo} applied to a subscripted function.

@c ===beg===
@c dd [x] (y) := y ^ x;
@c dd [a + b];
@c dd [v - u];
@c listarray (dd);
@c arrayinfo (dd);
@c ===end===
@example
@group
(%i1) dd [x] (y) := y ^ x;
                                     x
(%o1)                     dd (y) := y
                            x
@end group
@group
(%i2) dd [a + b];
                                    b + a
(%o2)                  lambda([y], y     )
@end group
@group
(%i3) dd [v - u];
                                    v - u
(%o3)                  lambda([y], y     )
@end group
@group
(%i4) listarray (dd);
                         b + a                v - u
(%o4)      [lambda([y], y     ), lambda([y], y     )]
@end group
@group
(%i5) arrayinfo (dd);
(%o5)             [hashed, 1, [b + a], [v - u]]
@end group
@end example

@opencatbox
@category{Arrays}
@closecatbox
@end deffn

@c NEEDS CLARIFICATION

@c -----------------------------------------------------------------------------
@anchor{make_array}
@deffn {Function} make_array (@var{type}, @var{dim_1}, @dots{}, @var{dim_n})

Creates and returns a Lisp array.  @var{type} may
be @code{any}, @code{flonum}, @code{fixnum}, @code{hashed} or 
@code{functional}.
There are @math{n} indices,
and the @math{i}'th index runs from 0 to @math{@var{dim_i} - 1}.

The advantage of @code{make_array} over @mref{array} is that the return value
doesn't have a name, and once a pointer to it goes away, it will also go away.
For example, if @code{y: make_array (...)} then @code{y} points to an object 
which takes up space, but after @code{y: false}, @code{y} no longer
points to that object, so the object can be garbage collected.

@c 'FUNCTIONAL ARGUMENT IN MAKE_ARRAY APPEARS TO BE BROKEN
@c EVEN AFTER READING THE CODE (SRC/AR.LISP) I CAN'T TELL HOW THIS IS SUPPOSED TO WORK
@c COMMENTING OUT THIS STUFF TO PREVENT CONFUSION AND HEARTBREAK
@c RESTORE IT WHEN MAKE_ARRAY ('FUNCTIONAL, ...) IS FIXED
@c @code{y: make_array ('functional, 'f, 'hashed, 1)} - the second argument to
@c @code{make_array} in this case is the function to call to calculate array
@c elements, and the rest of the arguments are passed recursively to
@c @code{make_array} to generate the "memory" for the array function object.

Examples:

@c ===beg===
@c A1 : make_array (fixnum, 10);
@c A1 [8] : 1729;
@c A1;
@c A2 : make_array (flonum, 10);
@c A2 [2] : 2.718281828;
@c A2;
@c A3 : make_array (any, 10);
@c A3 [4] : x - y - z;
@c A3;
@c A4 : make_array (fixnum, 2, 3, 5);
@c fillarray (A4, makelist (i, i, 1, 2*3*5));
@c A4 [0, 2, 1];
@c ===end===
@example
@group
(%i1) A1 : make_array (fixnum, 10);
(%o1)           @{Array:  #(0 0 0 0 0 0 0 0 0 0)@}
@end group
@group
(%i2) A1 [8] : 1729;
(%o2)                         1729
@end group
@group
(%i3) A1;
(%o3)          @{Array:  #(0 0 0 0 0 0 0 0 1729 0)@}
@end group
@group
(%i4) A2 : make_array (flonum, 10);
(%o4) @{Array:  #(0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0)@}
@end group
@group
(%i5) A2 [2] : 2.718281828;
(%o5)                      2.718281828
@end group
@group
(%i6) A2;
(%o6) 
     @{Array:  #(0.0 0.0 2.718281828 0.0 0.0 0.0 0.0 0.0 0.0 0.0)@}
@end group
@group
(%i7) A3 : make_array (any, 10);
(%o7) @{Array:  #(NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)@}
@end group
@group
(%i8) A3 [4] : x - y - z;
(%o8)                      - z - y + x
@end group
@group
(%i9) A3;
(%o9) @{Array:  #(NIL NIL NIL NIL ((MPLUS SIMP) $X ((MTIMES SIMP)\
 -1 $Y) ((MTIMES SIMP) -1 $Z))
  NIL NIL NIL NIL NIL)@}
@end group
@group
(%i10) A4 : make_array (fixnum, 2, 3, 5);
(%o10) @{Array:  #3A(((0 0 0 0 0) (0 0 0 0 0) (0 0 0 0 0)) ((0 0 \
0 0 0) (0 0 0 0 0) (0 0 0 0 0)))@}
@end group
@group
(%i11) fillarray (A4, makelist (i, i, 1, 2*3*5));
(%o11) @{Array:  #3A(((1 2 3 4 5) (6 7 8 9 10) (11 12 13 14 15))
    ((16 17 18 19 20) (21 22 23 24 25) (26 27 28 29 30)))@}
@end group
@group
(%i12) A4 [0, 2, 1];
(%o12)                         12
@end group
@end example

@opencatbox
@category{Arrays}
@closecatbox
@end deffn

@c DOES THIS MODIFY A OR DOES IT CREATE A NEW ARRAY ??

@c -----------------------------------------------------------------------------
@anchor{rearray}
@deffn {Function} rearray (@var{A}, @var{dim_1}, @dots{}, @var{dim_n})

Changes the dimensions of an array.
The new array will be filled with the elements of the old one in
row-major order.  If the old array was too small, 
the remaining elements are filled with
@code{false}, @code{0.0} or @code{0},
depending on the type of the array.  The type of the array cannot be
changed.

@opencatbox
@category{Arrays}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{remarray}
@deffn  {Function} remarray (@var{A_1}, @dots{}, @var{A_n})
@deffnx {Function} remarray (all)

Removes arrays and array associated functions and frees the storage occupied.
The arguments may be declared arrays, undeclared (hashed) arrays, array
functions, and subscripted functions.

@code{remarray (all)} removes all items in the global list @mrefdot{arrays}

@c WHAT DOES THIS MEAN EXACTLY ??
It may be necessary to use this function if it is
desired to redefine the values in a hashed array.

@code{remarray} returns the list of arrays removed.

@code{remarray} quotes its arguments.

@opencatbox
@category{Arrays}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{subvar}
@deffn {Function} subvar (@var{x}, @var{i})

Evaluates the subscripted expression @code{@var{x}[@var{i}]}.

@code{subvar} evaluates its arguments.

@code{arraymake (@var{x}, [@var{i}])} constructs the expression
@code{@var{x}[@var{i}]}, but does not evaluate it.

Examples:

@c ===beg===
@c x : foo $
@c i : 3 $
@c subvar (x, i);
@c foo : [aa, bb, cc, dd, ee]$
@c subvar (x, i);
@c arraymake (x, [i]);
@c ''%;
@c ===end===
@example
(%i1) x : foo $
(%i2) i : 3 $
@group
(%i3) subvar (x, i);
(%o3)                         foo
                                 3
@end group
(%i4) foo : [aa, bb, cc, dd, ee]$
@group
(%i5) subvar (x, i);
(%o5)                          cc
@end group
@group
(%i6) arraymake (x, [i]);
(%o6)                         foo
                                 3
@end group
@group
(%i7) ''%;
(%o7)                          cc
@end group
@end example

@opencatbox
@category{Expressions} @category{Arrays}
@closecatbox
@end deffn

@c NEEDS EXPANSION AND EXAMPLES

@c -----------------------------------------------------------------------------
@anchor{subvarp}
@deffn {Function} subvarp (@var{expr})

Returns @code{true} if @var{expr} is a subscripted variable, for example
@code{a[i]}.

@opencatbox
@category{Predicate functions}
@closecatbox
@end deffn

@c THIS IS REALLY CONFUSING

@c -----------------------------------------------------------------------------
@anchor{use_fast_arrays}
@defvr {Option variable} use_fast_arrays

If @code{true} then only two types of arrays are recognized:

@enumerate
@item
The art-q array (t in Common Lisp) which may have several dimensions
indexed by integers, and may hold any Lisp or Maxima object as an
entry.  To construct such an array, enter @code{a:make_array(any,3,4);} 
then @code{a} will have as value, an array with twelve slots, and the 
indexing is zero based.

@item
The Hash_table array which is the default type of array created if one
does @code{b[x+1]:y^2} (and @code{b} is not already an array, a list, or a
matrix -- if it were one of these an error would be caused since
@code{x+1} would not be a valid subscript for an art-q array, a list or
a matrix).  Its indices (also known as keys) may be any object.
It only takes one key at a time (@code{b[x+1,u]:y} would ignore the @code{u}).
Referencing is done by @code{b[x+1] ==> y^2}.  Of course the key may be
a list, e.g. @code{b[[x+1,u]]:y} would be valid.  This is incompatible 
with the old Maxima hash arrays, but saves consing.
@end enumerate

An advantage of storing the arrays as values of the symbol is that the
usual conventions about local variables of a function apply to arrays as
well.  The Hash_table type also uses less consing and is more efficient
than the old type of Maxima hashar.  To obtain consistent behaviour in
translated and compiled code set @code{translate_fast_arrays} to be
@code{true}.

@opencatbox
@category{Arrays} @category{Global flags}
@closecatbox
@end defvr

