Next: Shared Arrays, Previous: Array Syntax, Up: Arrays [Contents][Index]

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

`bound`s 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`(`

for each dimension.`lower``upper`)`array-dimensions`

instead returns justfor dimensions with a 0 lower bound. Both are suitable as input to`upper`+1`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

`(`

, where each`proc``elem`…)`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

`(`

, where`proc``i1`…`iN`)`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)))

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.

Next: Shared Arrays, Previous: Array Syntax, Up: Arrays [Contents][Index]