# FUNCTION

# Public

# COMBINE (ARRAY &OPTIONAL ELEMENT-TYPE)

The opposite of SUBARRAYS. If ELEMENT-TYPE is not given, it is inferred
from the first element of array, which also determines the dimensions. If
that element is not an array, the original ARRAY is returned as it is.

# COMPLEMENT-PERMUTATION (PERMUTATION RANK)

Return a list of increasing indices that complement PERMUTATION, ie form a
permutation when appended. Atoms are accepted and treated as lists of a
single element.

# COMPLETE-PERMUTATION (PERMUTATION RANK)

Return a completed version of permutation, appending it to its complement.

# COPY-INTO (TARGET SOURCE)

Copy SOURCE into TARGET, for array arguments of compatible
dimensions (checked). Return TARGET, making the implementation of the
semantics of SETF easy.

# DISPLACE (ARRAY DIMENSIONS &OPTIONAL (OFFSET 0))

Shorthand function for displacing an array.

# EACH (FUNCTION ARRAY &REST OTHER-ARRAYS)

Like EACH*, with ELEMENT-TYPE T.

# EACH* (ELEMENT-TYPE FUNCTION ARRAY &REST OTHER-ARRAYS)

Apply function to the array arguments elementwise, and return the result as
an array with the given ELEMENT-TYPE. Arguments are checked for dimension
compatibility.

# FLATTEN (ARRAY)

Return ARRAY flattened to a vector. Will share structure.

# GENERATE (FUNCTION DIMENSIONS &OPTIONAL ARGUMENTS)

Like GENERATE*, with ELEMENT-TYPE T.

# GENERATE* (ELEMENT-TYPE FUNCTION DIMENSIONS &OPTIONAL ARGUMENTS)

Return an array with given DIMENSIONS and ELEMENT-TYPE, with elements
generated by calling FUNCTION with
- no arguments, when ARGUMENTS is nil
- the position (= row major index), when ARGUMENTS is :POSITION
- a list of subscripts, when ARGUMENTS is :SUBSCRIPTS
- both when ARGUMENTS is :POSITION-AND-SUBSCRIPTS
The traversal order is unspecified and may be nonlinear.

# IDENTITY-PERMUTATION? (PERMUTATION &OPTIONAL (RANK (LENGTH PERMUTATION)))

Test if PERMUTATION is the identity permutation, ie a sequence of
consecutive integers starting at 0. Note that permutation is otherwise not
checked, ie it may not be a permutation.

# INVERT-PERMUTATION (PERMUTATION)

Invert a permutation.

# MAKE-ARRAY-LIKE (ARRAY &KEY (DIMENSIONS (DIMS ARRAY)) (ELEMENT-TYPE (ELEMENT-TYPE ARRAY)) (INITIAL-ELEMENT NIL INITIAL-ELEMENT?))

Create an array with the same dimensions and element-type as ARRAY (which can be an array-like object that has the appropriate methods defined). Each attribute can be overriden. When INITIAL-ELEMENT is given, it is coerced to ELEMENT-TYPE and used as the initial element.
The array returned is always a simple-array and shares no structure with anything else.

# MARGIN (FUNCTION ARRAY INNER &OPTIONAL (OUTER (COMPLEMENT-PERMUTATION INNER (ARRAY-RANK ARRAY))))

Like MARGIN*, with ELEMENT-TYPE T.

# MARGIN* (ELEMENT-TYPE FUNCTION ARRAY INNER &OPTIONAL (OUTER (COMPLEMENT-PERMUTATION INNER (ARRAY-RANK ARRAY))))

PERMUTE ARRAY with `(,@OUTER ,@INNER), split the inner subarrays, apply
FUNCTION to each, return the results in an array of dimensions OUTER, with the
given ELEMENT-TYPE.

# MATRIX? (MATRIX)

Test if MATRIX has rank 2.

# OUTER (FUNCTION &REST ARRAYS)

Like OUTER, with ELEMENT-TYPE t.

# OUTER* (ELEMENT-TYPE FUNCTION &REST ARRAYS)

Generalized outer product of ARRAYS with FUNCTION. The resulting array has the concatenated dimensions of ARRAYS, and the given ELEMENT-TYPE.

# PARTITION (ARRAY START &OPTIONAL (END (ARRAY-DIMENSION ARRAY 0)))

Return a subset of the array, on the first indexes between START and END.

# PERMUTE (PERMUTATION ARRAY)

Return ARRAY with the axes permuted by PERMUTATION, which is a sequence of
indexes. Specifically, an array A is transformed to B, where
B[b_1,...,b_n] = A[a_1,...,a_n] with b_i=a_{P[i]}
P is the permutation.
Array element type is preserved.

# RECYCLE (OBJECT &KEY INNER OUTER (ELEMENT-TYPE (IF (ARRAYP OBJECT) (ARRAY-ELEMENT-TYPE OBJECT) T)))

Recycle elements of object, extending the dimensions by outer (repeating
OBJECT) and inner (repeating each element of OBJECT). When both INNER and
OUTER are nil, the OBJECT is returned as is. Non-array objects are intepreted
as rank 0 arrays, following the usual semantics.

# RESHAPE (ARRAY DIMENSIONS &OPTIONAL (OFFSET 0))

Reshape ARRAY using DIMENSIONS (which can also be dimension
specifications). If DIMENSIONS is a list, it may contain a single element T
which will be calculated to match the total size of the resulting array.

# RESHAPE-COL (ARRAY)

Array reshaped as an Nx1 matrix.

# RESHAPE-ROW (ARRAY)

Array reshaped as an 1xN matrix.

# SPLIT (ARRAY RANK)

Return an array of subarrays, split off at RANK. All subarrays are
displaced and share structure.

# SQUARE-MATRIX? (MATRIX)

Test if MATRIX has two dimensions and that they are equal.

# STACK (AXIS ARRAY &REST ARRAYS)

Like STACK*, with element-type T.

# STACK* (ELEMENT-TYPE AXIS ARRAY &REST ARRAYS)

Stack array arguments along AXIS. ELEMENT-TYPE determines the element-type
of the result.

# SUB (ARRAY &REST SUBSCRIPTS)

Given a partial list of subscripts, return the subarray that starts there,
with all the other subscripts set to 0, dimensions inferred from the original.
If no subscripts are given, the original array is returned. Implemented by
displacing, may share structure.

# SUBVEC (VECTOR START &OPTIONAL (END (LENGTH VECTOR)))

Displaced vector between START and END.

# Undocumented

# SETFPARTITION (VALUE ARRAY START &OPTIONAL (END (ARRAY-DIMENSION ARRAY 0)))

# SETFSUB (VALUE ARRAY &REST SUBSCRIPTS)

# SETFSUBVEC (VALUE VECTOR START &OPTIONAL (END (LENGTH VECTOR)))

# Private

# CHECK-PERMUTATION (PERMUTATION &OPTIONAL (RANK (LENGTH PERMUTATION) RANK?))

Check if PERMUTATION is a valid permutation (of the given RANK), and signal
an error if necessary.

# ENSURE-DIMENSIONS (OBJECT)

Return a list of dimensions corresponding to OBJECT. Positive integers are
treated as dimensions of rank 1, lists are returned as they are, and arrays
are queried for their dimensions.
OBJECTS accepted by this function as valid dimensions are called `dimension
specifications' in this library.

# FILL-IN-DIMENSIONS (DIMENSIONS SIZE)

If one of the dimensions is missing (indicated with T), replace it with a
dimension so that the total product equals SIZE. If that's not possible,
signal an error. If there are no missing dimensions, just check that the
product equals size. Also accepts other dimension specifications (integer,
array).

# PERMUTATION-FLAGS (PERMUTATION &OPTIONAL (RANK (LENGTH PERMUTATION)))

Make a bit vector of flags with indexes from PERMUTATION, signalling errors
for invalid and repeated indices. NOT EXPORTED.

# PRODUCT (DIMENSIONS)

Product of elements in the argument. NOT EXPORTED.

# SAME-DIMENSIONS? (ARRAY &REST ARRAYS)

Test if arguments have the same dimensions. NOT EXPORTED.

# STACK*0 (ELEMENT-TYPE ARRAYS)

Stack arrays along the 0 axis, returning an array with given ELEMENT-TYPE.

# SUB-LOCATION% (DIMENSIONS SUBSCRIPTS)

Return (values OFFSET REMAINING-DIMENSIONS) that can be used to displace a
row-major subarray starting at SUBSCRIPTS in an array with the given
DIMENSIONS. NOT EXPORTED.

# MACRO

# Public

# &DIMS (&WHOLE WHOLE42 &REST DIMENSIONS)

Dimensions of array-like object.

# WALK-SUBSCRIPTS ((DIMENSIONS SUBSCRIPTS &OPTIONAL (POSITION (GENSYM POSITION))) &BODY BODY)

Iterate over the subscripts of an array with given DIMENSIONS. SUBSCRIPTS
contains the current subscripts as a vector of fixnums, POSITION has the
row-major index. Consequences are undefined if either POSITION or SUBSCRIPTS
is modified.

# WALK-SUBSCRIPTS-LIST ((DIMENSIONS SUBSCRIPTS &OPTIONAL (POSITION (GENSYM POSITION))) &BODY BODY)

Like WALK-SUBSCRIPTS, but SUBSCRIPTS is a newly created list for each
position that does not share structure and can be freely used/modified/kept
etc.

# Private

# MULTF (PLACE &REST VALUES &ENVIRONMENT ENV)

Multiply by the arguments

# GENERIC-FUNCTION

# Public

# AS-ARRAY (OBJECT)

Return the contents of OBJECT as an array. Exact semantics depends on OBJECT, but generally objects which contain elements in a rectilinear coordinate system should have a natural mapping to arrays.
When the second value is T, the array itself does not share structure with OBJECT, but its elements may. Otherwise, it is indeterminate whether the two objects share structure, and consequences of modifying the result are not defined. Methods are encouraged but not required to return a second value.

# DIM (ARRAY AXIS)

Return specificed dimension of ARRAY.

# DIMS (ARRAY)

Return a list of dimensions.
For non-array objects, SIZE, DIM, NROW and NCOL use this method by default, so it is enough to define it (unless efficiency is a concern).
When DIMS is not defined for an object, it falls back to as-array, which may be very inefficient for objects which need to be consed. It is always advisable to define DIMS.

# ELEMENT-TYPE (ARRAY)

Return TYPE such that
1. all elements of ARRAY are guaranteed to be a subtype of TYPE,
2. if applicable, elements of ARRAY can be set to values which are of a type that is a subtype of TYPE.

# NCOL (ARRAY)

Number of columns. Will signal an error if ARRAY is not a matrix.

# NROW (ARRAY)

Number of rows. Will signal an error if ARRAY is not a matrix.

# RANK (ARRAY)

Return the rank of ARRAY.

# SIZE (ARRAY)

Return the total number of elements in array.