Warning: This is the manual of the legacy Guile 2.2 series. You may want to read the manual of the current stable series instead.

6.6.13.3 Shared Arrays

Scheme Procedure: make-shared-array oldarray mapfunc bound …

C Function: scm_make_shared_array (oldarray, mapfunc, boundlist)

Return a new array which shares the storage of oldarray. Changes made through either affect the same underlying storage. The bound … arguments are the shape of the new array, the same as make-array (see Array Procedures).

mapfunc translates coordinates from the new array to the oldarray. It’s called as (mapfunc newidx1 …) with one parameter for each dimension of the new array, and should return a list of indices for oldarray, one for each dimension of oldarray.

mapfunc must be affine linear, meaning that each oldarray index must be formed by adding integer multiples (possibly negative) of some or all of newidx1 etc, plus a possible integer offset. The multiples and offset must be the same in each call.

One good use for a shared array is to restrict the range of some dimensions, so as to apply say array-for-each or array-fill! to only part of an array. The plain list function can be used for mapfunc in this case, making no changes to the index values. For example,

(make-shared-array #2((a b c) (d e f) (g h i)) list 3 2)
⇒ #2((a b) (d e) (g h))

The new array can have fewer dimensions than oldarray, for example to take a column from an array.

(make-shared-array #2((a b c) (d e f) (g h i))
                   (lambda (i) (list i 2))
                   '(0 2))
⇒ #1(c f i)

A diagonal can be taken by using the single new array index for both row and column in the old array. For example,

(make-shared-array #2((a b c) (d e f) (g h i))
                   (lambda (i) (list i i))
                   '(0 2))
⇒ #1(a e i)

Dimensions can be increased by for instance considering portions of a one dimensional array as rows in a two dimensional array. (array-contents below can do the opposite, flattening an array.)

(make-shared-array #1(a b c d e f g h i j k l)
                   (lambda (i j) (list (+ (* i 3) j)))
                   4 3)
⇒ #2((a b c) (d e f) (g h i) (j k l))

By negating an index the order that elements appear can be reversed. The following just reverses the column order,

(make-shared-array #2((a b c) (d e f) (g h i))
                   (lambda (i j) (list i (- 2 j)))
                   3 3)
⇒ #2((c b a) (f e d) (i h g))

A fixed offset on indexes allows for instance a change from a 0 based to a 1 based array,

(define x #2((a b c) (d e f) (g h i)))
(define y (make-shared-array x
                             (lambda (i j) (list (1- i) (1- j)))
                             '(1 3) '(1 3)))
(array-ref x 0 0) ⇒ a
(array-ref y 1 1) ⇒ a

A multiple on an index allows every Nth element of an array to be taken. The following is every third element,

(make-shared-array #1(a b c d e f g h i j k l)
                   (lambda (i) (list (* i 3)))
                   4)
⇒ #1(a d g j)

The above examples can be combined to make weird and wonderful selections from an array, but it’s important to note that because mapfunc must be affine linear, arbitrary permutations are not possible.

In the current implementation, mapfunc is not called for every access to the new array but only on some sample points to establish a base and stride for new array indices in oldarray data. A few sample points are enough because mapfunc is linear.

Scheme Procedure: shared-array-increments array

C Function: scm_shared_array_increments (array)

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

Scheme Procedure: shared-array-offset array

C Function: scm_shared_array_offset (array)

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

Scheme Procedure: shared-array-root array

C Function: scm_shared_array_root (array)

Return the root vector of a shared array.

Scheme Procedure: array-contents array [strict]

C Function: scm_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-typed-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.

Scheme Procedure: transpose-array array dim1 dim2 …

C Function: scm_transpose_array (array, dimlist)

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. dim1, dim2, … 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 dim1, dim2, … correspond to dimensions in the array to be returned, and 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.

(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))