Next: , Previous: Array Syntax, Up: Arrays


5.6.7.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 underlaying 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

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

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 index 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: enclose-array array dim1 ...
— C Function: scm_enclose_array (array, dimlist)

dim1, dim2 ... 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.

For example,

          (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 array
— Scheme Procedure: array-dimensions array
— C Function: scm_array_dimensions (array)

Return a list of the bounds for each dimenson 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-rank obj
— C Function: scm_array_rank (obj)

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? array1 array2 ...

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? in that a one dimensional shared array may be array-equal? but not equal? to a vector or uniform vector.

— Scheme Procedure: array-map! dst proc src1 ... srcN
— 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 ... srcN
— C Function: scm_array_for_each (proc, src1, srclist)

Apply proc to each tuple of elements of src1 ... srcN, 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 ura, in lexicographic order, as binary objects from port-or-fdes. If an end of file is encountered, the objects up to that point are put into ura (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-fdes may be omitted, in which case it defaults to the value returned by (current-input-port).

— Scheme Procedure: uniform-array-write v [port_or_fd [start [end]]]
— C Function: scm_uniform_array_write (v, port_or_fd, start, end)

Writes all elements of ura as binary objects to port-or-fdes.

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-fdes may be omitted, in which case it defaults to the value returned by (current-output-port).