This site is a static rendering of the Trac instance that was used by R7RS-WG1 for its work on R7RS-small (PDF), which was ratified in 2013. For more information, see Home.

Source for wiki ArraysCowan version 15

author

cowan

comment

ipnr

127.11.51.1

name

ArraysCowan

readonly

text

== Arrays ==

This is a proposal for the WG2 multidimensional arrays package.  These arrays are general: that is, the components may be any Scheme object.  However, future proposals may add support for numeric-only arrays.

== Terminology ==

The ''axes'' of an array are its dimensions: a vector has one axis, a matrix has two, and so on.  The ''rank'' of a vector is the number of axes it has.  Note that in this proposal, the objects called "vectors" in Scheme are referred to as "Scheme vectors".

Every array has a ''shape'', which is a Scheme vector of non-negative exact integers that specify the number of distinct values on each of its axes.  Thus an array with shape `#(4)` is a vector whose axis contains 4 elements, by default labeled from 0 to 3, and an array with shape `#(2 7)` is a 2 x 7 matrix whose rows range by default from 0 to 1 and whose columns range by default from 0 to 6 respectively.  A component of the shape MAY be 0, in which case the vector has no components.  A rank-0 vector's shape is `#()`, and it has exactly one component.

It is possible to create arrays whose indexes have a lower bound other than 0, in which case the upper bound is not the same as the shape.  In addition, the valid index values of a specific axis may be restricted to exact multiples of an integer known as the ''step''.

Each array has associated with it a ''storage object'', which for the purposes of this proposal is a Scheme vector.  It is possible for many arrays to be associated with a single storage object.  The locations associated with a storage object are known as ''storage elements''.  The values put into storage elements are `eqv?` to the values fetched from them.

An array's ''size'' is the total number of storage objects associated with it.  This is the product of the components of the array's shape, or 1 if the shape has no components.

== Constructors ==

`(make-array `''shape'' [''initial-value'']`)`

`(make-array `''lower-bounds upper-bounds'' [ ''steps'' [ ''initial-value'' ] ]`)`

The first form of this procedure returns a newly allocated array whose shape is ''shape''.  The second form specifies the lower bounds (inclusive) and the upper bounds (exclusive) of the dimensions, along with the step values, if any (which default to 1 in each axis).  All of these arguments are Scheme vectors.  It is an error if they do not have the same length.

All the components of the new array are set to  ''initial value'' if it is specified; otherwise their values are undefined.  

`(array `''shape obj'' ...`)`

Returns a newly allocatedn array whose shape is ''shape''.  Each ''obj'' is used to initialize the contents of the array in row-major order.  This procedure cannot specify lower bounds or steps.

`(vector->array `''shape'' ''vector''`)`

`(vector->array `''lower-bounds upper-bounds'' [ ''steps'' ] ''vector''`)`

`(list->array `''shape'' ''list''`)`

`(list->array `''lower-bounds upper-bounds'' [ ''steps'' ] ''list''`)`

Returns a newly allocated array with shape ''shape'', or with the specified lower-bounds, upper-bounds, and steps, containing the components of ''vector'' or ''list'' in storage order.  If ''shape'' is omitted, the result has the same shape as ''vector''.

`(array-tabulate `''shape proc''`)`

`(array-tabulate `''lower-bounds upper-bounds'' [ ''steps'' ] ''proc''`)`

Returns a newly allocated array with the specified ''shape, lower-bounds, upper-bounds'', and ''steps''.  ''Proc'' For each valid combination of indexes, ''proc'' is invoked, passing the indexes as a Scheme vector, which may be the same vector each time or distinct vectors.  Whatever ''proc'' returns becomes the value of the storage element corresponding to those indexes.

== Predicates ==

`(array? `''obj''`)`

Returns `#t` if ''obj'' is an array and `#f` otherwise.

== Array structure ==

`(array-shape `''array''`)`

`(array-lower-bounds `''array''`)`

`(array-upper-bounds `''array''`)`

`(array-steps `''array''`)`

`(array-strides `''array''`)`

Returns the shape, lower bounds, upper bounds, steps, or strides of ''array'' as Scheme vectors.  It is an error to m may be the same (in the sense of `eqv?`) as other arrays of the same shape.  It is an error to mutate the results of these procedures.

`(array-rank `''array''`)`

Returns the rank of ''array''.

`(array-size `''array''`)`

Returns the size of ''array''.

`(array-in-bounds? `''array subscript'' ...`)`

Returns `#t` if ''subscripts'', which MUST be exact integers, are valid subscripts for ''array'', and #f otherwise.  A subscript is valid if it is non-negative and less than the corresponding component of the shape.

== Storage procedures ==

`(array-storage `''array''`)`

Returns the storage associated with an array.

`(array-copy `''array''`)`

Returns a new array with the same shape, bounds, steps, and strides as ''array''.  However, the storage object is a copy of the storage object of ''array''.

`(array-ref `''array subscript'' ...`)`

Returns the component of ''array'' specified by ''subscripts'', which MUST be exact integers.  It is an error to specify an invalid ''subscript''.

`(array-set! `''array subscript'' ... ''value''`)`

Sets the component of ''array'' specified by ''subscripts'', which MUST be exact integers, to ''value''.  Returns undefined values.  It is an error to specify an invalid ''subscript''.

== Mapping and folding ==

`(array-map `''proc array'' ...`)`

Applies ''proc'' to each corresponding component of the ''arrays'' in row-major order.  It returns a newly allocated array with the same shape as ''array'' and containing components which are the results of the appropriate applications.  It is an error unless all the ''arrays'' have the same shape.  It is also an error unless ''proc'' accepts at least as many arguments as there are arrays.

`(array-map! `''proc array'' ...`)`

Applies ''proc'' to each corresponding component of the ''arrays'' in row-major order and places the results into  ''array''.  It is an error unless all the ''arrays'' have the same shape.  It is also an error unless ''proc'' accepts at least as many arguments as there are arrays.

`(array-for-each `''proc array'' ...`)`

Applies ''proc'' to each corresponding component of the ''arrays'' in storage order, discarding the results.  Returns undefined values.  It is an error unless all the ''arrays'' have the same shape.  It is also an error unless ''proc'' accepts at least as many arguments as there are arrays.

`(array-fold `''proc nil array'' ...`)`

Invokes ''proc'' on each component of ''arrays'' in storage order.  Each invocation is passed as arguments a Scheme vector containing the array indices of the current component, and the result of the previous invocation, in that order.  The Scheme vector may be reused by successive calls on ''proc''.  For the first invocation, ''nil'' is used as the final argument.  Returns the result of the last invocation.  It is an error unless all the ''arrays'' have the same shape.  It is also an error unless ''proc'' accepts at least as many arguments as there are arrays.

== Conversions ==

`(array->vector `''array''`)`

Returns a newly allocated Scheme vector containing the components of ''array'' in row-major order.

`(array->list `''array''`)`

Returns a newly allocated list containing the components of ''array'' in row-major order.

`(array->nested-vector `''array''`)`

Returns a newly allocated Scheme vector whose components are also newly constructed Scheme vectors, and so on as far down as necessary to cover every axis of the vector.  Bottom-level vectors contain the components of ''array''.  Thus, if ''array'' has rank 1, the result is a vector; if the array has rank 2, the result is a vector of vectors, and so on.  It is an error if ''array'' has rank 0.

`(array->nested-list `''array''`)`

Returns a newly allocated list whose components are also newly constructed lists, and so on as far down as necessary to cover every axis of ''array''.  Bottom-level lists contain the components of ''array''.  Thus, if ''array'' has rank 1, the result is a list; if the array has rank 2, the result is a list of lists, and so on.    It is an error if ''array'' has rank 0.

`(nested-vector->array `''rank nested-vector''`)`

Returns a newly allocated array with rank ''rank'' whose components are initialized from ''nested-vector''.  It is an error if ''nested-vector'' is not rectangular.  As a special case, if ''rank'' is 0, the sole component is ''nested-vector'', which need not be a vector.

`(nested-list->array `''rank nested-list''`)`

Returns an array with rank ''rank'' whose components are initialized from ''nested-list''.  It is an error if ''nested-list'' is not rectangular.  As a special case, if ''rank'' is 0, the sole component is ''nested-list'', which need not be a list.


== Advanced procedures ==

See AdvancedArraysCowan.

time

2014-10-03 01:37:37