diff options
author | Daniel Llorens <daniel.llorens@bluewin.ch> | 2015-09-16 11:44:23 +0200 |
---|---|---|
committer | Daniel Llorens <daniel.llorens@bluewin.ch> | 2016-07-11 09:11:50 +0200 |
commit | a8dd99d0de8d08bcfb63fa152c81b5cc110640c2 (patch) | |
tree | cefe990e4cb9355776d0efa8ee458d6bdaab1b19 | |
parent | fb4d4d966c75723ddb5ee339db87b24078f8c900 (diff) | |
download | guile-a8dd99d0de8d08bcfb63fa152c81b5cc110640c2.tar.gz |
Draft documentation for (array-for-each-cell)
* doc/ref/api-compound.texi: New section 'Arrays as arrays of
arrays'. Move the documentation for (array-from), (array-from*) and
(array-amend!) in here. Add documentation for (array-for-each-cell).
-rw-r--r-- | doc/ref/api-compound.texi | 161 |
1 files changed, 116 insertions, 45 deletions
diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi index 7f70374dc..34a832fa1 100644 --- a/doc/ref/api-compound.texi +++ b/doc/ref/api-compound.texi @@ -1203,6 +1203,7 @@ dimensional arrays. * Array Syntax:: * Array Procedures:: * Shared Arrays:: +* Arrays as arrays of arrays:: * Accessing Arrays from C:: @end menu @@ -1715,13 +1716,82 @@ sample points are enough because @var{mapfunc} is linear. Return the element at @code{(idx @dots{})} in @var{array}. @end deffn + +@deffn {Scheme Procedure} shared-array-increments array +@deffnx {C Function} scm_shared_array_increments (array) +For each dimension, return the distance between elements in the root vector. +@end deffn + +@deffn {Scheme Procedure} shared-array-offset array +@deffnx {C Function} scm_shared_array_offset (array) +Return the root vector index of the first element in the array. +@end deffn + +@deffn {Scheme Procedure} shared-array-root array +@deffnx {C Function} scm_shared_array_root (array) +Return the root vector of a shared array. +@end deffn + +@deffn {Scheme Procedure} array-contents array [strict] +@deffnx {C Function} scm_array_contents (array, strict) +If @var{array} may be @dfn{unrolled} into a one dimensional shared array +without changing their order (last subscript changing fastest), then +@code{array-contents} returns that shared array, otherwise it returns +@code{#f}. All arrays made by @code{make-array} and +@code{make-typed-array} may be unrolled, some arrays made by +@code{make-shared-array} may not be. + +If the optional argument @var{strict} is provided, a shared array will +be returned only if its elements are stored internally contiguous in +memory. +@end deffn + +@deffn {Scheme Procedure} transpose-array array dim1 dim2 @dots{} +@deffnx {C Function} scm_transpose_array (array, dimlist) +Return an array sharing contents with @var{array}, but with +dimensions arranged in a different order. There must be one +@var{dim} argument for each dimension of @var{array}. +@var{dim1}, @var{dim2}, @dots{} 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 @var{dim1}, @var{dim2}, @dots{} correspond to +dimensions in the array to be returned, and their positions in the +argument list to dimensions of @var{array}. Several @var{dim}s +may have the same value, in which case the returned array will +have smaller rank than @var{array}. + +@lisp +(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d)) +(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d) +(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{} + #2((a 4) (b 5) (c 6)) +@end lisp +@end deffn + +@node Arrays as arrays of arrays +@subsubsection Arrays as arrays of arrays + +The functions in this section allow you to treat an array of rank +@math{n} as an array of lower rank @math{n-k} where the elements are +themselves arrays (`cells') of rank @math{k}. This replicates some of +the functionality of `enclosed arrays', a feature of old Guile that was +removed before @w{version 2.0}. However, these functions do not require +a special type and operate on any array. + +When we operate on an array in this way, we speak of the first @math{k} +dimensions of the array as the @math{k}-`frame' of the array, while the +last @math{n-k} dimensions are the dimensions of the +@math{n-k}-`cell'. For example, a 2D-array (a matrix) can be seen as a +1D array of rows. In this case, the rows are the 1-cells of the array. + @deffn {Scheme Procedure} array-from array idx @dots{} @deffnx {C Function} scm_array_from (array, idxlist) If the length of @var{idxlist} equals the rank @math{n} of @var{array}, return the element at @code{(idx @dots{})}, just like @code{(array-ref array idx @dots{})}. If, however, the length @math{k} of @var{idxlist} is shorter than @math{n}, then return the shared -@math{(n-k)}-rank prefix cell of @var{array} given by @var{idxlist}. +@math{(n-k)}-rank cell of @var{array} given by @var{idxlist}. For example: @@ -1752,8 +1822,8 @@ The name `from' comes from the J language. @deffnx {C Function} scm_array_from_s (array, idxlist) Like @code{(array-from array idx @dots{})}, but return a 0-rank shared array if the length of @var{idxlist} matches the rank of -@var{array}. This can be useful when using @var{ARRAY} as destination -of copies. +@var{array}. This can be useful when using @var{ARRAY} as a place to +write into. Compare: @@ -1785,7 +1855,7 @@ If the length of @var{idxlist} equals the rank @math{n} of @var{x}, just like @code{(array-set! array x idx @dots{})}. If, however, the length @math{k} of @var{idxlist} is shorter than @math{n}, then copy the @math{(n-k)}-rank array @var{x} -into @math{(n-k)}-rank prefix cell of @var{array} given by +into the @math{(n-k)}-cell of @var{array} given by @var{idxlist}. In this case, the last @math{(n-k)} dimensions of @var{array} and the dimensions of @var{x} must match exactly. @@ -1814,58 +1884,59 @@ The name `amend' comes from the J language. @end deffn -@deffn {Scheme Procedure} shared-array-increments array -@deffnx {C Function} scm_shared_array_increments (array) -For each dimension, return the distance between elements in the root vector. -@end deffn +@deffn {Scheme Procedure} array-for-each-cell frame-rank op x @dots{} +@deffnx {C Function} scm_array_for_each_cell (array, frame_rank, op, xlist) +Each @var{x} must be an array of rank @math{n_x} ≥ @var{frame-rank}, and +the first @var{frame-rank} dimensions of each @var{x} must all be the +same. @var{array-for-each-cell} calls @var{op} with each set of +(@math{n_x} - @var{frame-rank})-cells from @var{x}, in unspecified order. -@deffn {Scheme Procedure} shared-array-offset array -@deffnx {C Function} scm_shared_array_offset (array) -Return the root vector index of the first element in the array. -@end deffn +@var{array-for-each-cell} allows you to loop over cells of any rank +without having to carry an index list or construct slices manually. The +cells passed to @var{op} are shared arrays of @var{X} so it is possible +to write to them. -@deffn {Scheme Procedure} shared-array-root array -@deffnx {C Function} scm_shared_array_root (array) -Return the root vector of a shared array. -@end deffn +This function returns an unspecified value. -@deffn {Scheme Procedure} array-contents array [strict] -@deffnx {C Function} scm_array_contents (array, strict) -If @var{array} may be @dfn{unrolled} into a one dimensional shared array -without changing their order (last subscript changing fastest), then -@code{array-contents} returns that shared array, otherwise it returns -@code{#f}. All arrays made by @code{make-array} and -@code{make-typed-array} may be unrolled, some arrays made by -@code{make-shared-array} may not be. +For example: -If the optional argument @var{strict} is provided, a shared array will -be returned only if its elements are stored internally contiguous in -memory. -@end deffn +@example +Sort the rows of rank-2 array @code{a}: +@lisp +(array-for-each-cell 1 (lambda (x) (sort! x <)) a) +@end lisp +@end example -@deffn {Scheme Procedure} transpose-array array dim1 dim2 @dots{} -@deffnx {C Function} scm_transpose_array (array, dimlist) -Return an array sharing contents with @var{array}, but with -dimensions arranged in a different order. There must be one -@var{dim} argument for each dimension of @var{array}. -@var{dim1}, @var{dim2}, @dots{} 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. +@example +Let @code{a} be a rank-2 array where each row is a 2-vector @math{x, +y}. Compute the norms of these vectors and store them in rank-1 array +@code{b}: +@lisp +(array-for-each-cell 1 + (lambda (a b) + (array-set! b (hypot (array-ref a 0) (array-ref a 1)))) + a b) +@end lisp +@end example -The values of @var{dim1}, @var{dim2}, @dots{} correspond to -dimensions in the array to be returned, and their positions in the -argument list to dimensions of @var{array}. Several @var{dim}s -may have the same value, in which case the returned array will -have smaller rank than @var{array}. +@code{(apply array-for-each-cell frame-rank op x)} is functionally +equivalent to @lisp -(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d)) -(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d) -(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{} - #2((a 4) (b 5) (c 6)) +(let ((frame (take (array-dimensions (car x)) frank))) + (unless (every (lambda (x) + (equal? frame (take (array-dimensions x) frank))) + (cdr x)) + (error)) + (array-index-map! + (apply make-shared-array (make-array #t) (const '()) frame) + (lambda i (apply op (map (lambda (x) (apply array-from* x i)) x))))) @end lisp + +The name `amend' comes from the J language. @end deffn + @node Accessing Arrays from C @subsubsection Accessing Arrays from C |