Kawa, the Java-based Scheme system

Node:Arrays, Next:Uniform vectors, Previous:Strings, Up:Extensions

### Multi-dimensional Arrays

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.

array? obj | Function

Returns `#t` if obj is an array, otherwise returns `#f`.

shape bound ... | Function

Returns 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`)`.

make-array shape | Function
make-array shape obj | Function

Returns 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 reference to shape.

array shape obj ... | Function

Returns 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 reference to shape.

array-rank array | Function

Returns the number of dimensions of array.
              (array-rank
                (make-array (shape 1 2 3 4)))
Returns 2.

array-start array k | Function

Returns the lower bound for the index along dimension k.

array-end array k | Function

Returns the upper bound for the index along dimension k.

array-ref array k ... | Function
array-ref array index | Function

Returns 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)
Returns `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))))
Returns `(3 1 4)`.

array-set! array k ... obj | Function
array-set! array index obj | Function

Stores obj in the element of array at index k .... Returns the void 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))
Returns `"huuhkaja"`.

share-array array shape proc | Function

Returns 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 reference 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))
                       (array-set! d k 1))
                    i))
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.

Multi-dimensional arrays are specified by SRFI-25. In Kawa, a one-dimensional array whose lower bound is 0 is also a sequence. Furthermore, if such an array is simple (not created `share-array`) it will be implemented using a `<vector>`. Uniform vectors and strings are also arrays in Kawa. For example:

         (share-array
          (f64vector 1.0 2.0 3.0 4.0 5.0 6.0)
          (shape 0 2 0 3)
          (lambda (i j) (+ (* 2 i) j)))

evaluates to a two-dimensionsal array of `<double>`:

         #2a((1.0 2.0 3.0) (3.0 4.0 5.0))