Node:Conventional Arrays,
Next:Array Mapping,
Up:Arrays
22.6.1 Conventional Arrays
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
zerobased index:
(makearray '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:
(makearray 'ho '(0 1) '(0 2)) =>
#2((ho ho ho) (ho ho ho))
A conventional array with one dimension based at zero is identical to
a vector:
(makearray 'ho 3) =>
#(ho ho ho)
The following procedures can be used with conventional arrays (or vectors).
array? v [prot]

Scheme Procedure 
scm_array_p (v, prot)

C Function 
Return #t if the obj is an array, and #f if
not. The prototype argument is used with uniform arrays
and is described elsewhere.

makearray initialvalue bound1 bound2 ...

Scheme Procedure 
Create and return an array that has as many dimensions as there are
bounds and fill it with initialvalue. Each bound
may be a positive nonzero integer N, in which case the index for
that dimension can range from 0 through N1; 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).

uniformvectorref v args

Scheme Procedure 
arrayref v . args

Scheme Procedure 
scm_uniform_vector_ref (v, args)

C Function 
Return the element at the (index1, index2) element in
array.

arrayinbounds? v . args

Scheme Procedure 
scm_array_in_bounds_p (v, args)

C Function 
Return #t if its arguments would be acceptable to
arrayref .

arrayset! v obj . args

Scheme Procedure 
uniformarrayset1! v obj args

Scheme Procedure 
scm_array_set_x (v, obj, args)

C Function 
Set the element at the (index1, index2) element in array to
newvalue. The value returned by arrayset! is unspecified.

makesharedarray oldra mapfunc . dims

Scheme Procedure 
scm_make_shared_array (oldra, mapfunc, dims)

C Function 
makesharedarray can be used to create shared subarrays of other
arrays. The mapper is a function 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 (makearray #f 8 8))
(define fredsdiagonal
(makesharedarray fred (lambda (i) (list i i)) 8))
(arrayset! fredsdiagonal 'foo 3)
(arrayref fred 3 3) => foo
(define fredscenter
(makesharedarray fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
(arrayref fredscenter 0 0) => foo

sharedarrayincrements ra

Scheme Procedure 
scm_shared_array_increments (ra)

C Function 
For each dimension, return the distance between elements in the root vector.

sharedarrayoffset ra

Scheme Procedure 
scm_shared_array_offset (ra)

C Function 
Return the root vector index of the first element in the array.

sharedarrayroot ra

Scheme Procedure 
scm_shared_array_root (ra)

C Function 
Return the root vector of a shared array.

transposearray ra . args

Scheme Procedure 
scm_transpose_array (ra, args)

C Function 
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.
(transposearray '#2((a b) (c d)) 1 0) => #2((a c) (b d))
(transposearray '#2((a b) (c d)) 0 0) => #1(a d)
(transposearray '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) =>
#2((a 4) (b 5) (c 6))

enclosearray ra . axes

Scheme Procedure 
scm_enclose_array (ra, axes)

C Function 
dim0, dim1 ... should be nonnegative integers less than
the rank of array. enclosearray 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 arrayset! . Two references to the same element of
an enclosed array will be equal? but will not in general be
eq? . The value returned by arrayprototype when given an
enclosed array is unspecified.
examples:
(enclosearray '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) =>
#<enclosedarray (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
(enclosearray '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) =>
#<enclosedarray #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>

arrayshape array

Scheme Procedure 
Return a list of inclusive bounds of integers.
(arrayshape (makearray 'foo '(1 3) 5)) => ((1 3) (0 4))

arraydimensions ra

Scheme Procedure 
scm_array_dimensions (ra)

C Function 
Arraydimensions is similar to arrayshape but replaces
elements with a 0 minimum with one greater than the maximum. So:
(arraydimensions (makearray 'foo '(1 3) 5)) => ((1 3) 5)

arrayrank ra

Scheme Procedure 
scm_array_rank (ra)

C Function 
Return the number of dimensions of obj. If obj is
not an array, 0 is returned.

array>list v

Scheme Procedure 
scm_array_to_list (v)

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

arraycopy! src dst

Scheme Procedure 
arraycopyinorder! src dst

Scheme Procedure 
scm_array_copy_x (src, dst)

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

arrayfill! ra fill

Scheme Procedure 
scm_array_fill_x (ra, fill)

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

arrayequal? ra0 ra1

Scheme Procedure 
Return #t iff all arguments are arrays with the same shape, the
same type, and have corresponding elements which are either
equal? or arrayequal? . This function differs from
equal? in that a one dimensional shared array may be
arrayequal? but not equal? to a vector or uniform vector.

arraycontents array [strict]

Scheme Procedure 
scm_array_contents (array, strict)

C Function 
If array may be unrolled into a one dimensional shared array
without changing their order (last subscript changing fastest), then
arraycontents returns that shared array, otherwise it returns
#f . All arrays made by makearray and
makeuniformarray may be unrolled, some arrays made by
makesharedarray may not be.
If the optional argument strict is provided, a shared array will
be returned only if its elements are stored internally contiguous in
memory.
