6.6.13.2 Array Procedures

When an array is created, the 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))

The following procedures can be used with arrays (or vectors). An argument shown as idx… means one parameter for each dimension in the array. A idxlist argument means a list of such values, one for each dimension.

Scheme Procedure: array? obj
C Function: scm_array_p (obj, unused)

Return #t if the obj is an array, and #f if not.

The second argument to scm_array_p is there for historical reasons, but it is not used. You should always pass SCM_UNDEFINED as its value.

Scheme Procedure: typed-array? obj type
C Function: scm_typed_array_p (obj, type)

Return #t if the obj is an array of type type, and #f if not.

C Function: int scm_is_array (SCM obj)

Return 1 if the obj is an array and 0 if not.

C Function: int scm_is_typed_array (SCM obj, SCM type)

Return 0 if the obj is an array of type type, and 1 if not.

Scheme Procedure: make-array fill bound …
C Function: scm_make_array (fill, bounds)

Equivalent to (make-typed-array #t fill bound ...).

Scheme Procedure: make-typed-array type fill bound …
C Function: scm_make_typed_array (type, fill, bounds)

Create and return an array that has as many dimensions as there are bounds and (maybe) fill it with fill.

The underlying storage vector is created according to type, which must be a symbol whose name is the ‘vectag’ of the array as explained above, or #t for ordinary, non-specialized arrays.

For example, using the symbol f64 for type will create an array that uses a f64vector for storing its elements, and a will use a string.

When fill is not the special unspecified value, the new array is filled with fill. Otherwise, the initial contents of the array is unspecified. The special unspecified value is stored in the variable *unspecified* so that for example (make-typed-array 'u32 *unspecified* 4) creates a uninitialized u32 vector of length 4.

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

Scheme Procedure: list->array dimspec list

Equivalent to (list->typed-array #t dimspec list).

Scheme Procedure: list->typed-array type dimspec list
C Function: scm_list_to_typed_array (type, dimspec, list)

Return an array of the type indicated by type with elements the same as those of list.

The argument dimspec determines the number of dimensions of the array and their lower bounds. When dimspec is an exact integer, it gives the number of dimensions directly and all lower bounds are zero. When it is a list of exact integers, then each element is the lower index bound of a dimension, and there will be as many dimensions as elements in the list.

Scheme Procedure: array-type array
C Function: scm_array_type (array)

Return the type of array. This is the ‘vectag’ used for printing array (or #t for ordinary arrays) and can be used with make-typed-array to create an array of the same kind as array.

Scheme Procedure: array-ref array idx …
C Function: scm_array_ref (array, idxlist)

Return the element at (idx …) in array.

(define a (make-array 999 '(1 2) '(3 4)))
(array-ref a 2 4) ⇒ 999
Scheme Procedure: array-in-bounds? array idx …
C Function: scm_array_in_bounds_p (array, idxlist)

Return #t if the given indices would be acceptable to array-ref.

(define a (make-array #f '(1 2) '(3 4)))
(array-in-bounds? a 2 3) ⇒ #t
(array-in-bounds? a 0 0) ⇒ #f
Scheme Procedure: array-set! array obj idx …
C Function: scm_array_set_x (array, obj, idxlist)

Set the element at (idx …) in array to obj. The return value is unspecified.

(define a (make-array #f '(0 1) '(0 1)))
(array-set! a #t 1 1)
a ⇒ #2((#f #f) (#f #t))
Scheme Procedure: array-shape array
Scheme Procedure: array-dimensions array
C Function: scm_array_dimensions (array)

Return a list of the bounds for each dimension of array.

array-shape gives (lower upper) for each dimension. array-dimensions instead returns just upper+1 for dimensions with a 0 lower bound. Both are suitable as input to make-array.

For example,

(define a (make-array 'foo '(-1 3) 5))
(array-shape a)      ⇒ ((-1 3) (0 4))
(array-dimensions a) ⇒ ((-1 3) 5)
Scheme Procedure: array-length array
C Function: scm_array_length (array)
C Function: size_t scm_c_array_length (array)

Return the length of an array: its first dimension. It is an error to ask for the length of an array of rank 0.

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

Return the rank of array.

C Function: size_t scm_c_array_rank (SCM array)

Return the rank of array as a size_t.

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! src dst
Scheme Procedure: array-copy-in-order! src dst
C Function: scm_array_copy_x (src, dst)

Copy every element from vector or array src to the corresponding element of dst. dst must have the same rank as src, and be at least as large in each dimension. The return value is unspecified.

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

Store fill in every element of array. The value returned is unspecified.

Scheme Procedure: array-equal? array …

Return #t if 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? (see Equality) in that all arguments must be arrays.

Scheme Procedure: array-map! dst proc src …
Scheme Procedure: array-map-in-order! dst proc src …
C Function: scm_array_map_x (dst, proc, srclist)

Set each element of the dst array to values obtained from calls to proc. The list of src arguments may be empty. The value returned is unspecified.

Each call is (proc elem …), where each elem is from the corresponding src array, at the dst index. array-map-in-order! makes the calls in row-major order, array-map! makes them in an unspecified order.

The src arrays must have the same number of dimensions as dst, and must have a range for each dimension which covers the range in dst. This ensures all dst indices are valid in each src.

Scheme Procedure: array-for-each proc src1 src2 …
C Function: scm_array_for_each (proc, src1, srclist)

Apply proc to each tuple of elements of src1 src2 …, in row-major order. The value returned is unspecified.

Scheme Procedure: array-index-map! dst proc
C Function: scm_array_index_map_x (dst, proc)

Set each element of the dst array to values returned by calls to proc. The value returned is unspecified.

Each call is (proc i1iN), where i1iN is the destination index, one parameter for each dimension. The order in which the calls are made is unspecified.

For example, to create a 4x4 matrix representing a cyclic group,

    / 0 1 2 3 \
    | 1 2 3 0 |
    | 2 3 0 1 |
    \ 3 0 1 2 /
(define a (make-array #f 4 4))
(array-index-map! a (lambda (i j)
                      (modulo (+ i j) 4)))

An additional array function is available in the module (ice-9 arrays). It can be used with:

(use-modules (ice-9 arrays))
Scheme Procedure: array-copy src

Return a new array with the same elements, type and shape as src. However, the array increments may not be the same as those of src. In the current implementation, the returned array will be in row-major order, but that might change in the future. Use array-copy! on an array of known order if that is a concern.