Common Lisp Package: ARRAY-OPERATIONS

README:

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.

CONDITION

Public

Undocumented

PERMUTATION-INCOMPATIBLE-RANK

PERMUTATION-INVALID-INDEX

PERMUTATION-REPEATED-INDEX