Returns a shape, in the (r 2) form. The sequence bound ... must consist of an even number of exact integers that are pairwise not decreasing. Each pair gives the lower and upper bound of a dimension. If the shape is used to specify the dimensions of an array and bound ... is the sequence b0 e0 ... bk ek ... of n pairs of bounds, then a valid index to the array is any sequence j0 ... jk ... of n exact integers where each jk satisfies (<= bk jk) and (< jk ek).

The shape of a d-dimensional array is a d * 2 array where the element at k 0 contains the lower bound for an index along dimension k and the element at k 1 contains the corresponding upper bound, where k satisfies (<= 0 k) and (< k d).

(apply shape bounds) is equivalent to: (apply array (vector 2 (/ (length bounds) 2)) bounds)

Returns the number of dimensions of array.

(array-rank
  (make-array (shape 1 2 3 4)))

Returns 2.

Returns the lower bound (inclusive) for the index along dimension k. This is most commonly 0.

Returns the upper bound for the index along dimension k. The bound is exclusive - i.e. the first integer higher than the last legal index.

Return the total number of elements of array. This is the product of (- (array-end array k) (array-start array k)) for every valid k.

Returns a new array whose shape is given by shape and the initial contents of the elements are obj ... in row major order. The array does not retain a reference to shape.

Returns a newly allocated array whose shape is given by shape. If value is provided, then each element is initialized to it. If there is more than one value, they are used in order, starting over when the values are exhausted. If there is no value, the initial contents of each element is unspecified. The array does not retain a reference to shape.

(make-array #(2 4) 1 2 3 4 5) ⇨
╔#2a:2:4╗
║1│2│3│4║
╟─┼─┼─┼─╢
║5│1│2│3║
╚═╧═╧═╧═╝

Compatibility: Guile has an incompatible make-array procedure.

Construct a “virtual array” of the given shape, which uses no storage for the elements. Instead, elements are calculated on-demand by calling procedure, which takes a single argument, an index vector.

There is no caching or memoization.

(build-array #2a((10 12) (0 3))
  (lambda (ind)
    (let ((x (ind 0)) (y (ind 1)))
      (- x y)))) ⇨
#2a@10:2:3
║10│ 9│8║
╟──┼──┼─╢
║11│10│9║
╚══╧══╧═╝

Return a new immutable array of the specified shape where each element is the corresponding row-major index. Same as (array-reshape [0 <: size] shape) where size is the array-size of the resulting array.

(index-array #2a((1 3) (2 6))) ⇨
#2a@1:2@2:4
║0│1│2│3║
╟─┼─┼─┼─╢
║4│5│6│7║
╚═╧═╧═╧═╝

Returns the contents of the element of array at index k .... The sequence k ... must be a valid index to array. In the second form, index must be a vector (a 0-based 1-dimensional array) containing k ....

(array-ref (array [2 3]
              'uno 'dos 'tres
              'cuatro 'cinco 'seis)
   1 0)

Returns cuatro.

(let ((a (array (shape 4 7 1 2) 3 1 4)))
   (list (array-ref a 4 1)
         (array-ref a (vector 5 1))
         (array-ref a (array (shape 0 2)
                         6 1))))

Returns (3 1 4).

Generalized APL-style array indexing, where each index can be either an array or an integer.

If each index is an integer, then the result is the same as array-ref.

Otherwise, the result is an immutable array whose rank is the sum of the ranks of each index. An integer is treated as rank-0 array.

If marr is the result of (array-index-ref arr M1 M2 ...) then:

(marr i11 i12 ... i21 i22 ...)

is defined as:

(arr (M1 i11 i12 ...) (M2 i21 i22 ...) ...)

Each Mk gets as many indexes as its rank. If Mk is an integer, then it we use it directly without any indexing.

Here are some examples, starting with simple indexing.

(define arr (array #2a((1 4) (0 4))
                   10 11 12 13 20 21 22 23 30 31 32 33))
arr ⇨
╔#2a@1:3:4══╗
║10│11│12│13║
╟──┼──┼──┼──╢
║20│21│22│23║
╟──┼──┼──┼──╢
║30│31│32│33║
╚══╧══╧══╧══╝
(array-index-ref arr 2 3) ⇨
23

If one index is a vector and the rest are scalar integers, then the result is a vector:

(array-index-ref arr 2 #(3 1)) ⇨
#(23 21)

You can select a “sub-matrix” when all indexes are vectors:

(array-index-ref arr #(2 1) #(3 1 3)) ⇨
╔#2a:2:3═╗
║23│21│23║
╟──┼──┼──╢
║13│11│13║
╚══╧══╧══╝

Using ranges for index vectors selects a rectangular sub-matrix.

(array-index-ref arr (range< 3 1) (range< 4 1)) ⇨
╔#2a:2:3═╗
║11│12│13║
╟──┼──┼──╢
║21│22│23║
╚══╧══╧══╝

You can add new dimensions:

(array-index-ref arr #(2 1) #2a((3 1) (3 2))) ⇨
#3a╤══╗
║23│21║
╟──┼──╢
║23│22║
╠══╪══╣
║13│11║
╟──┼──╢
║13│12║
╚══╧══╝

FIX: Need alternate non-Kawa way to expression pseudo-ranges. The pseudo-range [<:] can be used to select all the indexes along a dimension. To select row 2 (1-origin):

(array-index-ref arr 2 [<:]) ⇨
#(20 21 22 23)

To reverse the order use [>:]:

(array-index-ref arr 2 [>:]) ⇨
#(23 22 21 20)

To select column 3:

(array-index-ref arr [<:] [3]) ⇨
#2a╗
║13║
╟──╢
║23║
╟──╢
║33║
╚══╝

To expand that column to 5 colums you can repeat the column index:

(range-take 5 3 0)
#(3 3 3 3 3)
(array-index-ref arr [<:] (range-take 5 3 0)) ⇨
╔#2a:3:5═╤══╤══╗
║13│13│13│13│13║
╟──┼──┼──┼──┼──╢
║23│23│23│23│23║
╟──┼──┼──┼──┼──╢
║33│33│33│33│33║
╚══╧══╧══╧══╧══╝

Stores obj in the element of array at index k .... Returns the void value. The sequence k ... must be a valid index to array. In the second form, index must be either a vector or a 0-based 1-dimensional array containing k ....

(let ((a (make-array
            (shape 4 5 4 5 4 5))))
   (array-set! a 4 4 4 "huuhkaja")
   (array-ref a 4 4 4))

Returns "huuhkaja".

Compatibility: SRFI-47, Guile and Scheme-48 have array-set! with a different argument order.

Compatibility: Guile has a array-copy! with the reversed argument order.

Set all the values array to value. You can use (array-fill! (array-index-share array indexes...) value) to set a subset of the array.

This is a general mechanism for creating a view. The result is a new array with the given shape. Accessing this new array is implemented by calling the transform function on the index vector, which must return a new index vector valid for indexing the original array. Here is an example (using the same arr as in the array-index-ref example):

(define arr (array #2a((1 4) (0 4))
                   10 11 12 13 20 21 22 23 30 31 32 33))
(array-transform arr #2a((0 3) (1 3) (0 2))
  (lambda (ix) (let ((i (ix 0)) (j (ix 1)) (k (ix 2)))
                 [(+ i 1)
                  (+ (* 2 (- j 1)) k)]))) ⇨
#3a:3@1:2:2
║10│11║
╟──┼──╢
║12│13║
╠══╪══╣
║20│21║
╟──┼──╢
║22│23║
╠══╪══╣
║30│31║
╟──┼──╢
║32│33║
╚══╧══╝

The array-transform is generalization of share-array, in that it does not require the transform to be affine. Also note the different calling conversions for the tranform: array-transform takes a single argument (a vector of indexes), and returns a single result (a vector of indexes); share-array takes one argument for each index, and returns one value for each index. The difference is historical.

This does the same generalized APL-style indexing as array-index-ref. However, the resulting array is a modifiable view into the argument array.

Creates a new array narray of the given shape, such that (array->vector array) and (array->vector narray) are equivalent. I.e. the i’th element in row-major-order of narray is the i’th element in row-major-order of array. Hence (array-size narray) (as specified from the shape) must be equal to (array-size array). The resulting narray is a view such that modifying array also modifies narray and vice versa.

Returns a new array of shape shape that shares elements of array through proc. The procedure proc must implement an affine function that returns indices of array when given indices of the array returned by share-array. The array does not retain a reference to shape.

(define i_4
   (let* ((i (make-array
                (shape 0 4 0 4)
                0))
          (d (share-array i
                (shape 0 4)
                (lambda (k)
                   (values k k)))))
      (do ((k 0 (+ k 1)))
          ((= k 4))
         (array-set! d k 1))
      i))

Note: the affinity requirement for proc means that each value must be a sum of multiples of the arguments passed to proc, plus a constant.

Implementation note: arrays have to maintain an internal index mapping from indices k1 ... kd to a single index into a backing vector; the composition of this mapping and proc can be recognised as (+ n0 (* n1 k1) ... (* nd kd)) by setting each index in turn to 1 and others to 0, and all to 0 for the constant term; the composition can then be compiled away, together with any complexity that the user introduced in their procedure.

Here is an example where the array is a uniform vector:

(share-array
  (f64vector 1.0 2.0 3.0 4.0 5.0 6.0)
  (shape 0 2 0 3)
  (lambda (i j) (+ (* 2 i) j)))
   ⇨  #2f64((1.0 2.0 3.0) (4.0 5.0 6.0))

Return a vector consisting of the elements of the array in row-major-order.

The result of array-flatten is a fresh (mutable) copy, not a view. The result of array->vector is a view: If array is mutable, then modifying array changes the flattened result and vice versa.

If array is “simple”, array->vector returns the original vector. Specifically, if vec is a vector then:

(eq? vec (array->vector (array-reshape vec shape)))