Conventional Arrays - Guile Reference Manual

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:

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

A conventional array with one dimension based at zero is identical to a vector. The arguments to each procedure are specified in opposite order, however:

— Scheme Procedure: make-array fill [bound ...]

Return a newly created array with elements initialized to fill. The array dimensions are equal to the number of bound arguments (which may be zero). Each bound is either a positive non-zero integer N, in which case the index for that dimension ranges from 0 through N-1; or an explicit index range specifier in the form (LOWER UPPER), where both LOWER and UPPER are integers, possibly negative, and possibly the same number (however, LOWER must be less than UPPER).

— Scheme Procedure: array? obj [prot]
— C Function: scm_array_p (obj, prot) |1 |1 |0

Return #t iff the obj is an array. The optional second arg prot is used with uniform arrays and must be equal? to the value described in the prototype table (see Uniform Arrays).

— Scheme Procedure: uniform-vector-ref v idx
— Scheme Procedure: array-ref v idx
— C Function: scm_uniform_vector_ref (v, idx)

Return the idxth element of uniform vector v.

— Scheme Procedure: array-in-bounds? v [args ...]
— C Function: scm_array_in_bounds_p (v, args) |1 |0 |1

Return #t if its arguments would be acceptable to array-ref.

— Scheme Procedure: array-set! array new-value [index1...]
— Scheme Procedure: uniform-array-set1! array new-value [index1...]
— C Function: scm_array_set_x (array, new-value, index1...)

Place new-value into the the index1, index2, ... element in array.

— Scheme Procedure: make-shared-array array mapper dim0 [dim1...]
— C Function: scm_make_shared_array (array, mapper, dim0, dim1...)

Create a shared subarray of array having dimensions dim0, dim1, ... (the number of dimensions may be less than, equal to, or greater than that of array, but there must be at least one).
The mapper is a procedure 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

— Scheme Procedure: shared-array-increments shared-array
— C Function: scm_shared_array_increments (shared-array)

For each dimension in shared-array, return the distance between elements in the root vector.

— Scheme Procedure: shared-array-offset shared-array
— C Function: scm_shared_array_offset (shared-array)

Return the root vector index of the first element in shared-array.

— Scheme Procedure: shared-array-root shared-array
— C Function: scm_shared_array_root (shared-array)

Return the root vector of shared-array.

— Scheme Procedure: transpose-array array [dim...]
— C Function: scm_transpose_array (array, dim...)

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.
Examples:
          (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))

— Scheme Procedure: enclose-array array dim0 [dim1...]
— C Function: scm_enclose_array (array, dim0, dim1...)

Return an enclosed array, resembling an array of shared arrays, made from the source array. dim0, dim1 ... are nonnegative integers less than the rank of array.
The dimensions of each shared array are the same as the dimth dimensions of the original array, whereas 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.
          (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))>

— Scheme Procedure: array-shape a

Return a list of inclusive bounds of integers for array a.
          (array-shape (make-array 'foo '(-1 3) 5))
          ⇒ ((-1 3) (0 4))

— Scheme Procedure: array-dimensions array
— C Function: scm_array_dimensions (array)

Return a list of inclusive bounds of integers for array. The result is similar to that of array-shape except that those elements with a 0 minimum are replaced with one greater than the maximum. So:
          (array-dimensions (make-array 'foo '(-1 3) 5))
          ⇒ ((-1 3) 5)

— Scheme Procedure: array-rank array
— C Function: scm_array_rank (array)

Return the number of dimensions of array.

— Scheme Procedure: array->list array
— C Function: scm_array_to_list (array)

Return a list consisting of all the elements, in order, of array.

— Scheme Procedure: array-copy! source destination
— Scheme Procedure: array-copy-in-order! source destination
— C Function: scm_array_copy_x (source, destination)

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.

— Scheme Procedure: array-fill! ra fill
— C Function: scm_array_fill_x (ra, fill)

Store fill in every element of array.

— Scheme Procedure: array-equal? ra0 ra1

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.

— Scheme Procedure: array-contents array [strict]
— C Function: scm_array_contents (array, strict)

If array can be unrolled into a one dimensional shared array without changing element order (last subscript changing fastest), then return that shared array, otherwise return #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 and non-#f, a shared array will be returned only if its elements are stored internally contiguous in memory.

22.6.1 Conventional Arrays