This is a proposal for the WG2 multidimensional arrays package. These arrays are general: that is, the components may be any Scheme object. The components of arrays may be addressed by subscripts or in row-major order using a single index.
The axes of an array are its dimensions: a vector has one axis, a matrix has two, and so on. The rank of a vector is the number of axes it has.
Every array has a shape, which is a vector of non-negative exact integers that specify the maximum exclusive values of its axes. Thus an array with shape #(4) is a vector whose axis contains elements 0 to 3, and an array with shape #(2 7) is a 2 x 7 matrix whose rows range from 0 to 1 and whose columns range from 0 to 6 respectively. A component of the shape MAY be 0, in which case the vector has no components. A rank-0 vector's shape is #(), and it has exactly one component.
An array's size is its total number of components. This is the product of the components of the array's shape, or 1 if the shape has no components.
A Scheme vector is an object on which vector? returns #t. It is implementation-defined whether Scheme vectors are the same as rank-1 arrays or not.
In order to make the difference less visible, wherever a procedure accepts an array argument that can or must be rank-1, it MUST also accept a Scheme vector. Likewise, wherever a procedure other than a procedure that converts arrays to vectors returns a result that is a rank-1 array, the result MAY be a Scheme vector, but there is no requirement for all rank-1 arrays to be Scheme vectors. However, there is no requirement for vector? to return #t on every rank-1 array. In this proposal, we will simply speak of vectors.
Arrays with ranks other than 1 are a disjoint type from Scheme vectors and other types of Scheme objects.
The values put into arrays are eqv? to the values fetched from them.
This proposal redefines equal? to descend into arrays as well as pairs, vectors, and strings. However, arrays cannot be equal? unless their shapes are equal?.
(make-array shape [initial-value])
Constructs and returns an array of the specified shape. All the components of the new array are set to initial value if it is specified; otherwise their values are undefined.
(array? obj)
Returns #t if obj is an array and #f otherwise. Note that if (vector? obj) returns #t, then (array? obj) MUST return #t as well.
(array shape obj ...)
Constructs and returns an array whose shape is shape. Each obj is used to initialize the contents of the array in row-major order.
(array-shape array)
Returns the shape of array. This MAY be the same (in the sense of eqv?) as other arrays of the same shape. Modifying the result of this procedure has undefined effects.
(array-rank array)
Returns the rank of array.
(array-size array)
Returns the size of array.
(array-in-bounds? array subscript ...)
Returns #t if subscripts, which MUST be exact integers, are valid subscripts for array, and #f otherwise. A subscript is valid if it is non-negative and less than the corresponding component of the shape.
(array-ref array subscript ...)
Returns the component of array specified by subscripts, which MUST be exact integers. It is an error to specify an invalid subscript.
(array-set! array subscript ... value)
Sets the component of array specified by subscripts, which MUST be exact integers, to value. Returns undefined values. It is an error to specify an invalid subscript.
(array-row-major-index array subscript ...)
Returns the row-major index to array that corresponds to subscripts. It is an error to specify an invalid subscript.
(array-row-major-ref array ''index)
Returns the component of array specified by the row-major index index. It is an error to specify an index that is negative or not less than the size of the array.
(array-row-major-set! array index value)
Sets the component of array specified by index to value. Returns undefined values. It is an error to specify an index that is negative or not less than the size of the array.
(copy-array array)
Returns a new array with the same components (in the sense of eqv?) and shape as array.
(array-map proc array ...)
Applies proc to each component of the arrays in an unspecified order. It constructs and returns a new array with the same shape as array and containing components which are the results of the appropriate applications. All the arrays MUST have the same shape. Proc MUST accept at least as many arguments as there are arrays.
(array-for-each proc array ...)
Applies proc to each component of the arrays in an unspecified order, discarding the results. Returns undefined values. All the arrays MUST have the same shape. Proc MUST accept at least as many arguments as there are arrays.
(array-fold proc nil array ...)
Invokes proc on each corresponding components of arrays in row-major order, passing the result of the previous invocation as a final argument. For the first invocation, nil is used as the final argument. Returns the result of the last invocation.
(array->vector array)
Constructs and returns a Scheme vector containing the components of array in row-major order.
(array->list array)
Constructs and returns a list containing the components of array in row-major order.
(array->nested-vector array)
Constructs and returns a Scheme vector whose components are also newly constructed Scheme vectors, and so on as far down as necessary to cover every axis of the vector. Bottom-level vectors contain the components of 'array. Thus, if array has rank 1, the result is a vector; if the array has rank 2, the result is a vector of vectors, and so on. It is an error if array'' has rank 0.
(array->nested-list array)
Constructs and returns a list whose components are also newly constructed lists, and so on as far down as necessary to cover every axis of array. Bottom-level lists contain the components of 'array. Thus, if array has rank 1, the result is a list; if the array has rank 2, the result is a list of lists, and so on. It is an error if array'' has rank 0.
(vector->array [shape] vector)
Constructs and returns an array with shape shape containing the components of vector in row-major order. If shape is omitted, the result has the same shape as vector.
(list->array [shape] list)
Constructs and returns an array with shape shape containing the components of list. If shape is omitted, the result has rank 1 and a single axis equal to the length of list.
(nested-vector->array rank nested-vector)
Returns an array with rank rank whose components are initialized from nested-vector. It is an error if nested-vector is not rectangular. As a special case, if rank is 0, the sole component is vector, which need not be a vector.
(nested-list->array rank nested-list)
Returns an array with rank rank whose components are initialized from nested-list. It is an error if nested-list is not rectangular. As a special case, if rank is 0, the sole component is list, which need not be a list.
See AdvancedArraysCowan.