2.13.3 Specification

Arrays are heterogeneous data structures whose elements are indexed by integer sequences of fixed length. The length of a valid index sequence is the rank or the number of dimensions of an array. The shape of an array consists of bounds for each index.

The lower bound B and the upper bound E of a dimension are exact integers with (<= B E).

A valid index along the dimension is an exact integer K that satisfies both (<= B K) and (< K E). The length of the array along the dimension is the difference (- E B). The size of an array is the product of the lengths of its dimensions.

A shape is specified as an even number of exact integers. These are alternately the lower and upper bounds for the dimensions of an array.

The following ten procedures should be implemented.

Function: array? obj

Return #t if obj is an array, otherwise return #f.

Function: make-array shape

Function: make-array shape obj

Return a newly allocated array whose shape is given by shape. If obj is provided, then each element is initialized to it. Otherwise the initial contents of each element is unspecified. The array does not retain a dependence to shape.

Function: shape bound …

Return a shape. The sequence bound … must consist of an even number of exact integers that are pairwise not decreasing. Each pair gives the lower and upper bound of a dimension. If the shape is used to specify the dimensions of an array and bound … is the sequence b0 e0 … bk ek … of N pairs of bounds, then a valid index to the array is any sequence j0 … jk … of N exact integers where each jk satisfies (<= bk jk) and (< jk ek).

The shape of a d-dimensional array is a d * 2 array where the element at K = 0 contains the lower bound for an index along dimension K and the element at K = 1 contains the corresponding upper bound, where K satisfies (<= 0 K) and (< K d).

Function: array shape obj …

Return a new array whose shape is given by shape and the initial contents of the elements are obj … in row major order. The array does not retain a dependence to shape.

Function: array-rank array

Return the number of dimensions of array.

(array-rank (make-array (shape 1 2 3 4)))
⇒ 2

Function: array-start array K

Return the lower bound for the index along dimension K.

Function: array-end array K

Return the upper bound for the index along dimension K.

Function: array-ref array K …

Function: array-ref array index

Return the contents of the element of array at index K …. The sequence K … must be a valid index to array. In the second form, index must be either a vector or a 0-based 1-dimensional array containing K ….

(array-ref (array (shape 0 2 0 3)
                  'uno 'dos 'tres
                  'cuatro 'cinco 'seis)
           1 0)
⇒ cuatro

(let ((a (array (shape 4 7 1 2) 3 1 4)))
  (list (array-ref a 4 1)
        (array-ref a (vector 5 1))
        (array-ref a (array (shape 0 2) 6 1))))
⇒ (3 1 4)

Function: array-set! array K … obj

Function: array-set! array index obj

Store obj in the element of array at index K …. Return an unspecified value. The sequence K … must be a valid index to array. In the second form, index must be either a vector or a 0-based 1-dimensional array containing K ….

(let ((a (make-array (shape 4 5 4 5 4 5))))
  (array-set! a 4 4 4 'huuhkaja)
  (array-ref  a 4 4 4))
⇒ huuhkaja

Function: share-array array shape proc

Return a new array of shape shape that shares elements of array through proc. The procedure proc must implement an affine function that returns indices of array when given indices of the array returned by share-array. The array does not retain a dependence to shape.

(define i_4
  (let* ((i (make-array (shape 0 4 0 4) 0))
         (d (share-array i (shape 0 4)
                         (lambda (k)
                           (values k k)))))
    (do ((k 0 (+ k 1)))
         ((= k 4)
          i)
      (array-set! d k 1))))

NOTE The affinity requirement for proc means that each value must be a sum of multiples of the arguments passed to proc, plus a constant.

IMPLEMENTATION NOTE Arrays have to maintain an internal index mapping from indices k1 … kd to a single index into a backing vector; the composition of this mapping and proc can be recognised as:

(+ n0 (* n1 k1) ... (* nd kd))

by setting each index in turn to 1 and others to 0, and all to 0 for the constant term; the composition can then be compiled away, together with any complexity that the user introduced in their procedure.

This document does not specify any external representation for arrays. This document does not specify when arrays are equal?. (Indeed, R5RS equal? will do the wrong thing.)