GNU Info
(guile.info)Conventional Arrays
Conventional Arrays
-------------------
"Conventional arrays" are a collection of cells organised 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, organised 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
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))
A conventional array with one dimension based at zero is identical to a
vector:
(make-array 'ho 3) =>
#(ho ho ho)
The following procedures can be used with conventional arrays (or
vectors).
- primitive: array? v [prot]
Returns `#t' if the OBJ is an array, and `#f' if not.
The PROTOTYPE argument is used with uniform arrays and is described
elsewhere.
- procedure: make-array initial-value bound1 bound2 ...
Creates and returns an array that has as many dimensions as there
are BOUNDs and fills it with INITIAL-VALUE.
- primitive: uniform-vector-ref v args
- primitive: array-ref v . args
Returns the element at the `(index1, index2)' element in ARRAY.
- primitive: array-in-bounds? v . args
Returns `#t' if its arguments would be acceptable to array-ref.
- primitive: array-set! v obj . args
- primitive: uniform-array-set1! v obj args
Sets the element at the `(index1, index2)' element in ARRAY to
NEW-VALUE. The value returned by array-set! is unspecified.
- primitive: make-shared-array oldra mapfunc . dims
`make-shared-array' 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 (make-array #f 8 8))
(define freds-diagonal
(make-shared-array fred (lambda (i) (list i i)) 8))
(array-set! freds-diagonal 'foo 3)
(array-ref fred 3 3) => foo
(define freds-center
(make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
(array-ref freds-center 0 0) => foo
- primitive: shared-array-increments ra
For each dimension, return the distance between elements in the
root vector.
- primitive: shared-array-offset ra
Return the root vector index of the first element in the array.
- primitive: shared-array-root ra
Return the root vector of a shared array.
- primitive: transpose-array ra . args
Returns 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.
examples:
(transpose-array '#2((a b) (c d)) 1 0) => #2((a c) (b d))
(transpose-array '#2((a b) (c d)) 0 0) => #1(a d)
(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) =>
#2((a 4) (b 5) (c 6))
- primitive: enclose-array ra . axes
DIM0, DIM1 ... 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.
examples:
(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))>
- procedure: array-shape array
Returns a list of inclusive bounds of integers.
(array-shape (make-array 'foo '(-1 3) 5)) => ((-1 3) (0 4))
- primitive: array-dimensions ra
`Array-dimensions' is similar to `array-shape' but replaces
elements with a `0' minimum with one greater than the maximum. So:
(array-dimensions (make-array 'foo '(-1 3) 5)) => ((-1 3) 5)
- primitive: array-rank ra
Returns the number of dimensions of OBJ. If OBJ is not an array,
`0' is returned.
- primitive: array->list v
Returns a list consisting of all the elements, in order, of ARRAY.
- primitive: array-copy! src dst
- primitive: array-copy-in-order! src dst
Copies 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.
- primitive: array-fill! ra fill
Stores FILL in every element of ARRAY. The value returned is
unspecified.
- primitive: array-equal? ra0 ra1
Returns `#t' iff 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.
- primitive: array-contents ra [strict]
- primitive: array-contents array strict
If ARRAY may be "unrolled" into a one dimensional shared array
without changing their order (last subscript changing fastest),
then `array-contents' returns that shared array, otherwise it
returns `#f'. All arrays made by MAKE-ARRAY and
MAKE-UNIFORM-ARRAY may be unrolled, some arrays made by
MAKE-SHARED-ARRAY 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.
automatically generated by info2www version 1.2.2.9