[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.1 gauche.array - Arrays

Module: gauche.array
This module provides multi-dimensional array data type and operations. The primitive API follows SRFI-25. This module also defines several useful operations. This module also implements an external representation of arrays, using SRFI-10 mechanism.

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

Reader syntax: #,(<array> shape obj ...)
An array is written out in this format. 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.

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: 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 1 3 2 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).

Function: array-for-each-index array proc &optional index

Function: shape-for-each shape proc &optional index

Function: tabulate-array shape proc &optional index

Function: array-retabulate! array shape proc &optional index
Function: array-retabulate! array proc &optional index

Function: array-map! array shape proc array0 array1 ...
Function: array-map! array proc array0 array1 ...

Function: array-map shape proc array0 array1 ...
Function: array-map proc array0 array1 ...

Function: array->vector array
Function: array->list array


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by Ken Dickey on November, 28 2002 using texi2html