Node:Conventional Arrays, Next:, Up:Arrays


22.6.1 Conventional Arrays

Conventional arrays are a collection of cells organized into an arbitrary number of dimensions. Each cell can hold any kind of Scheme value and can be accessed in constant time by supplying an index for each dimension. This contrasts with uniform arrays, which use memory more efficiently but can hold data of only a single type, and lists where inserting and deleting cells is more efficient, but more time is usually required to access a particular cell.

A conventional array is displayed as # followed by the rank (number of dimensions) followed by the cells, organized into dimensions using parentheses. The nesting depth of the parentheses is equal to the rank.

When an array is created, the number of dimensions and range of each dimension must be specified, e.g., to create a 2x3 array with a zero-based index: 

(make-array 'ho 2 3) =>
#2((ho ho ho) (ho ho ho))

The range of each dimension can also be given explicitly, e.g., another way to create the same array: 

(make-array 'ho '(0 1) '(0 2)) =>
#2((ho ho ho) (ho ho ho))

A conventional array with one dimension based at zero is identical to a vector: 

(make-array 'ho 3) =>
#(ho ho ho)

The following procedures can be used with conventional arrays (or vectors).

array? v [prot] Scheme Procedure
scm_array_p (v, prot) C Function
Return #t if the obj is an array, and #f if not. The prototype argument is used with uniform arrays and is described elsewhere.

make-array initial-value bound1 bound2 ... Scheme Procedure
Create and return an array that has as many dimensions as there are bounds and fill it with initial-value. Each bound may be a positive non-zero integer N, in which case the index for that dimension can range from 0 through N-1; or an explicit index range specifier in the form (LOWER UPPER), where both lower and upper are integers, possibly less than zero, and possibly the same number (however, lower cannot be greater than upper).

uniform-vector-ref v args Scheme Procedure
array-ref v . args Scheme Procedure
scm_uniform_vector_ref (v, args) C Function
Return the element at the (index1, index2) element in array.

array-in-bounds? v . args Scheme Procedure
scm_array_in_bounds_p (v, args) C Function
Return #t if its arguments would be acceptable to array-ref.

array-set! v obj . args Scheme Procedure
uniform-array-set1! v obj args Scheme Procedure
scm_array_set_x (v, obj, args) C Function
Set the element at the (index1, index2) element in array to new-value. The value returned by array-set! is unspecified.

make-shared-array oldra mapfunc . dims Scheme Procedure
scm_make_shared_array (oldra, mapfunc, dims) C Function
make-shared-array can be used to create shared subarrays of other arrays. The mapper is a function that translates coordinates in the new array into coordinates in the old array. A mapper must be linear, and its range must stay within the bounds of the old array, but it can be otherwise arbitrary. A simple example: 
(define fred (make-array #f 8 8))
(define freds-diagonal
  (make-shared-array fred (lambda (i) (list i i)) 8))
(array-set! freds-diagonal 'foo 3)
(array-ref fred 3 3) => foo
(define freds-center
  (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
(array-ref freds-center 0 0) => foo

shared-array-increments ra Scheme Procedure
scm_shared_array_increments (ra) C Function
For each dimension, return the distance between elements in the root vector.

shared-array-offset ra Scheme Procedure
scm_shared_array_offset (ra) C Function
Return the root vector index of the first element in the array.

shared-array-root ra Scheme Procedure
scm_shared_array_root (ra) C Function
Return the root vector of a shared array.

transpose-array ra . args Scheme Procedure
scm_transpose_array (ra, args) C Function
Return an array sharing contents with array, but with dimensions arranged in a different order. There must be one dim argument for each dimension of array. dim0, dim1, ... should be integers between 0 and the rank of the array to be returned. Each integer in that range must appear at least once in the argument list.

The values of dim0, dim1, ... correspond to dimensions in the array to be returned, their positions in the argument list to dimensions of array. Several dims may have the same value, in which case the returned array will have smaller rank than array. 

(transpose-array '#2((a b) (c d)) 1 0) => #2((a c) (b d))
(transpose-array '#2((a b) (c d)) 0 0) => #1(a d)
(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) =>
                #2((a 4) (b 5) (c 6))

enclose-array ra . axes Scheme Procedure
scm_enclose_array (ra, axes) C Function
dim0, dim1 ... should be nonnegative integers less than the rank of array. enclose-array returns an array resembling an array of shared arrays. The dimensions of each shared array are the same as the dimth dimensions of the original array, the dimensions of the outer array are the same as those of the original array that did not match a dim.

An enclosed array is not a general Scheme array. Its elements may not be set using array-set!. Two references to the same element of an enclosed array will be equal? but will not in general be eq?. The value returned by array-prototype when given an enclosed array is unspecified.

examples: 

(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) =>
   #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>

(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) =>
   #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>

array-shape array Scheme Procedure
Return a list of inclusive bounds of integers. 
(array-shape (make-array 'foo '(-1 3) 5)) => ((-1 3) (0 4))

array-dimensions ra Scheme Procedure
scm_array_dimensions (ra) C Function
Array-dimensions is similar to array-shape but replaces elements with a 0 minimum with one greater than the maximum. So: 
(array-dimensions (make-array 'foo '(-1 3) 5)) => ((-1 3) 5)

array-rank ra Scheme Procedure
scm_array_rank (ra) C Function
Return the number of dimensions of obj. If obj is not an array, 0 is returned.

array->list v Scheme Procedure
scm_array_to_list (v) C Function
Return a list consisting of all the elements, in order, of array.

array-copy! src dst Scheme Procedure
array-copy-in-order! src dst Scheme Procedure
scm_array_copy_x (src, dst) C Function
Copy every element from vector or array source to the corresponding element of destination. destination must have the same rank as source, and be at least as large in each dimension. The order is unspecified.

array-fill! ra fill Scheme Procedure
scm_array_fill_x (ra, fill) C Function
Store fill in every element of array. The value returned is unspecified.

array-equal? ra0 ra1 Scheme Procedure
Return #t iff all arguments are arrays with the same shape, the same type, and have corresponding elements which are either equal? or array-equal?. This function differs from equal? in that a one dimensional shared array may be array-equal? but not equal? to a vector or uniform vector.

array-contents array [strict] Scheme Procedure
scm_array_contents (array, strict) C Function
If array may be unrolled into a one dimensional shared array without changing their order (last subscript changing fastest), then array-contents returns that shared array, otherwise it returns #f. All arrays made by make-array and make-uniform-array may be unrolled, some arrays made by make-shared-array may not be.

If the optional argument strict is provided, a shared array will be returned only if its elements are stored internally contiguous in memory.