[Guile-commits] 16/25: Draft documentation for (array-for-each-cell)

[Daniel Llorens]

lloda pushed a commit to branch lloda-array-support
in repository guile.

commit a8dd99d0de8d08bcfb63fa152c81b5cc110640c2
Author: Daniel Llorens <address@hidden>
Date:   Wed Sep 16 11:44:23 2015 +0200

    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).
---
 doc/ref/api-compound.texi |  161 ++++++++++++++++++++++++++++++++-------------
 1 file changed, 116 insertions(+), 45 deletions(-)

diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
index 7f70374..34a832f 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
 
+
address@hidden {Scheme Procedure} shared-array-increments array
address@hidden {C Function} scm_shared_array_increments (array)
+For each dimension, return the distance between elements in the root vector.
address@hidden deffn
+
address@hidden {Scheme Procedure} shared-array-offset array
address@hidden {C Function} scm_shared_array_offset (array)
+Return the root vector index of the first element in the array.
address@hidden deffn
+
address@hidden {Scheme Procedure} shared-array-root array
address@hidden {C Function} scm_shared_array_root (array)
+Return the root vector of a shared array.
address@hidden deffn
+
address@hidden {Scheme Procedure} array-contents array [strict]
address@hidden {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
address@hidden returns that shared array, otherwise it returns
address@hidden  All arrays made by @code{make-array} and
address@hidden may be unrolled, some arrays made by
address@hidden 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.
address@hidden deffn
+
address@hidden {Scheme Procedure} transpose-array array dim1 dim2 @dots{}
address@hidden {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
address@hidden argument for each dimension of @var{array}.
address@hidden, @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}.
+
address@hidden
+(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))
address@hidden lisp
address@hidden deffn
+
address@hidden Arrays as arrays of arrays
address@hidden Arrays as arrays of arrays
+
+The functions in this section allow you to treat an array of rank
address@hidden 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
address@hidden'. 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
address@hidden(n-k)}-rank prefix cell of @var{array} given by @var{idxlist}.
address@hidden(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
address@hidden This can be useful when using @var{ARRAY} as destination
-of copies.
address@hidden 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
 
 
address@hidden {Scheme Procedure} shared-array-increments array
address@hidden {C Function} scm_shared_array_increments (array)
-For each dimension, return the distance between elements in the root vector.
address@hidden deffn
address@hidden {Scheme Procedure} array-for-each-cell frame-rank op x @dots{}
address@hidden {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.
 
address@hidden {Scheme Procedure} shared-array-offset array
address@hidden {C Function} scm_shared_array_offset (array)
-Return the root vector index of the first element in the array.
address@hidden deffn
address@hidden 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.
 
address@hidden {Scheme Procedure} shared-array-root array
address@hidden {C Function} scm_shared_array_root (array)
-Return the root vector of a shared array.
address@hidden deffn
+This function returns an unspecified value.
 
address@hidden {Scheme Procedure} array-contents array [strict]
address@hidden {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
address@hidden returns that shared array, otherwise it returns
address@hidden  All arrays made by @code{make-array} and
address@hidden may be unrolled, some arrays made by
address@hidden 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.
address@hidden deffn
address@hidden
+Sort the rows of rank-2 array @code{a}:
address@hidden
+(array-for-each-cell 1 (lambda (x) (sort! x <)) a)
address@hidden lisp
address@hidden example
 
address@hidden {Scheme Procedure} transpose-array array dim1 dim2 @dots{}
address@hidden {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
address@hidden argument for each dimension of @var{array}.
address@hidden, @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.
address@hidden
+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
address@hidden:
address@hidden
+(array-for-each-cell 1
+  (lambda (a b)
+    (array-set! b (hypot (array-ref a 0) (array-ref a 1))))
+  a b)
address@hidden lisp
address@hidden 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}.
address@hidden(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