6.7.5.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 section Equality) in that all arguments must be arrays.

Scheme Procedure: array-map! dst proc src …

Scheme Procedure: array-map-in-order! dst proc src1 … srcN

C Function: scm_array_map_x (dst, proc, srclist)

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

Each call is (proc elem1 … elemN), 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 i1 … iN), where i1…iN 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)))

Scheme Procedure: uniform-array-read! ra [port_or_fd [start [end]]]

C Function: scm_uniform_array_read_x (ra, port_or_fd, start, end)

Attempt to read all elements of array ra, in lexicographic order, as binary objects from port_or_fd. If an end of file is encountered, the objects up to that point are put into ra (starting at the beginning) and the remainder of the array is unchanged.

The optional arguments start and end allow a specified region of a vector (or linearized array) to be read, leaving the remainder of the vector unchanged.

uniform-array-read! returns the number of objects read. port_or_fd may be omitted, in which case it defaults to the value returned by (current-input-port).

Scheme Procedure: uniform-array-write ra [port_or_fd [start [end]]]

C Function: scm_uniform_array_write (ra, port_or_fd, start, end)

Writes all elements of ra as binary objects to port_or_fd.

The optional arguments start and end allow a specified region of a vector (or linearized array) to be written.

The number of objects actually written is returned. port_or_fd may be omitted, in which case it defaults to the value returned by (current-output-port).

This document was generated on April 20, 2013 using texi2html 5.0.