Gauche Users' Reference: 9.1 gauche.array

9.1 `gauche.array` - Arrays

Module: gauche.array

This module provides multi-dimensional array data type and operations. The primitive API follows SRFI-25. Besides a generic srfi-25 array that can store any Scheme objects, this module also provides array classes that stores numeric objects efficiently, backed up by homogeneous numeric vectors (See section gauche.uvector - Uniform vectors). An external representation of arrays, using SRFI-10 mechanism, is also provided.

Each element of an N-dimensional array can be accessed by N integer indices, [ i_0 i_1 … i_N-1 ]. An array has associated shape that knows lower-bound s_k and upper-bound e_k of index of each dimension, where s_k <= e_k, and the index i_k must satisfy s_k <= i_k < e_k. (Note: it is allowed to have s_k == e_k, but such array can't store any data. It is also allowed to have zero-dimensional array, that can store a single data.). The shape itself is a [ D x 2 ] array, where D is the dimension of the array which the shape represents.

You can pass index(es) to array access primitives in a few ways; each index can be passed as individual argument, or can be 'packed' in a vector or one-dimensional array. In the latter case, such a vector or an array is called an "index object". Using a vector is efficient in Gauche when you iterate over the elements by changing the vector elements, for it won't involve memory allocation.

Arrays can be compared by the equal? procedure. Equal? returns #t if two arrays have the same shape and their corresponding elements are the same in the sense of equal?.

Internally, an array consists of a backing storage and a mapping procedure. A backing storage is an object of aggregate type that can be accessed by an integer index. A mapping procedure takes multi-dimensional indices (or index object) and returns a scalar index into the backing storage.

Class: <array-base>: An abstract base class of array types, that implements generic operations on the array. To create an array instance, you should use one of the following concrete array classes.

Class: <array>
Class: <u8array>
Class: <s8array>
Class: <u16array>
Class: <s16array>
Class: <u32array>
Class: <s32array>
Class: <u64array>
Class: <s64array>
Class: <f16array>
Class: <f32array>
Class: <f64array>: Concrete array classes. The <array> class implements srfi-25 compatible array, i.e. an array that can store any Scheme objects. The <u8array> class through <f64array> classes uses a <u8vector> through <f64vector> as a backing storage, and can only store a limited range of integers or inexact real numbers, but they are space efficient.

Reader syntax: #,(<array> shape obj …)

An array is written out in this format. (Substitute <array> for <u8array> if the array is <u8array>, etc.) shape is a list of even number of integers, and each 2n-th integer and 2n+1-th integer specifies the inclusive lower-bound and exclusive upper-bound of n-th dimension, respectively. The following obj … are the values in the array listed in row-major order.

When read back, this syntax is read as an array with the same shape and content, so it is equal? to the original array.

; an array such that:
;   8 3 4
;   1 5 9
;   6 7 2
#,(<array> (0 3 0 3) 8 3 4 1 5 9 6 7 2)

; a 4x4 identity matrix
#,(<array> (0 4 0 4) 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1)

Function: array? obj: [SRFI-25] Returns #t if obj is an array, #f otherwise. It is equivalent to (is-a? obj <array-base>).

Function: make-array shape &optional init

[SRFI-25] Creates an array of shape shape. Shape must be a [ D x 2 ] array, and for each k (0 <= k < D), the [ k 0 ] element must be less than or equal to the [ k 1] element. If init is given, all the elements are initialized by it. Otherwise, the initial value of the elements are undefined.

(make-array (shape 0 2 0 2 0 2) 5)
 ⇒ #,(<array> (0 2 0 2 0 2) 5 5 5 5 5 5 5 5)

Function: make-u8array shape &optional init
Function: make-s8array shape &optional init: …

Function: make-f32array shape &optional init
Function: make-f64array shape &optional init: Like make-array, but creates and returns an uniform numeric array.

Function: shape bound …

[SRFI-25] Takes even number of exact integer arguments, and returns a two-dimensional array that is suitable for representing the shape of an array.

(shape 0 2 1 3 3 5)
 ⇒ #,(<array> (0 3 0 2) 0 2 1 3 3 5)

(shape)
 ⇒ #,(<array> (0 0 0 2))

Function: array shape init …

[SRFI-25] Creates an array of shape shape, initializing its elements by init ….

(array (shape 0 2 1 3) 'a 'b 'c 'd)
 ⇒ #,(<array> (0 2 1 3) a b c d)

Function: array-rank array

[SRFI-25] Returns the number of dimensions of an array array.

(array-rank (make-array (shape 0 2 0 2 0 2))) ⇒ 3
(array-rank (make-array (shape))) ⇒ 0

Function: array-shape array: Returns a shape array of array.

Function: array-start array dim

Function: array-end array dim

Function: array-length array dim

[SRFI-25+] Array-start returns the inclusive lower bound of index of dim-th dimension of an array array. Array-end returns the exclusive upper bound. And array-length returns the difference between two. Array-start and array-end are defined in SRFI-25.

(define a (make-array (shape 1 5 0 2)))

(array-start a 0)  ⇒ 1
(array-end a 0)    ⇒ 5
(array-length a 0) ⇒ 4
(array-start a 1)  ⇒ 0
(array-end a 1)    ⇒ 2
(array-length a 1) ⇒ 2

Function: array-size array

Returns the total number of elements in the array array.

(array-size (make-array (shape 5 9 1 3))) ⇒ 8
(array-size (make-array (shape))) ⇒ 1
(array-size (make-array (shape 0 0 0 2))) ⇒ 0

Function: array-ref array k …
Function: array-ref array index: [SRFI-25] Gets the element of array array. In the first form, the element is specified by indices k …. In the second form, the element is specified by an index object index, which must be a vector or an one-dimensional array.

Function: array-set! array k … value
Function: array-set! array index value: [SRFI-25] Sets the element of array array to value. In the first form, the element is specified by indices k …. In the second form, the element is specified by an index object index, which must be a vector or an one-dimensional array.

Function: share-array array shape proc: [SRFI-25] Creates and returns a new array of shape shape, that shares the backing storage with the given array array. The procedure proc maps the indices of the new array to the indices to the original array, i.e. proc must be a n-ary procedure that returns m values, where n is the dimension of the new array and m is the one of the original array. Furthermore, proc must be an affine function; each mapping has to be a linear combination of input arguments plus optional constant. (Share-array optimizes the mapping function based on the affinity assumption, so proc won't be called every time the new array is accessed).