[Guile-commits] 11/12: Document new array functions

[Daniel Llorens]

lloda pushed a commit to branch lloda-squash1
in repository guile.

commit ddb5f40f5e633984fa41eaf2c655935d2ca87636
Author: Daniel Llorens <address@hidden>
Date:   Fri Nov 18 13:14:53 2016 +0100

    Document new array functions
    
    * doc/ref/api-compound.texi: Document array-from, array-from*,
      array-amend!, array-for-each-cell, array-for-each-cell-in-order.
---
 doc/ref/api-compound.texi |  172 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 172 insertions(+)

diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
index 97aaba3..936b495 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
 
@@ -1676,6 +1677,13 @@ base and stride for new array indices in @var{oldarray} 
data.  A few
 sample points are enough because @var{mapfunc} is linear.
 @end deffn
 
+
address@hidden {Scheme Procedure} array-ref array idx @dots{}
address@hidden {C Function} scm_array_ref (array, idxlist)
+Return the element at @code{(idx @dots{})} in @var{array}.
address@hidden 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.
@@ -1728,6 +1736,170 @@ have smaller rank than @var{array}.
 @end lisp
 @end 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.
+
address@hidden {Scheme Procedure} array-from array idx @dots{}
address@hidden {C Function} scm_array_from (array, idxlist)
+If the length of @var{idxlist} equals the rank @math{n} of
address@hidden, return the element at @code{(idx @dots{})}, just like
address@hidden(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 cell of @var{array} given by @var{idxlist}.
+
+For example:
+
address@hidden
+(array-from #2((a b) (c d)) 0) @result{} #(a b)
+(array-from #2((a b) (c d)) 1) @result{} #(c d)
+(array-from #2((a b) (c d)) 1 1) @result{} d
+(array-from #2((a b) (c d))) @result{} #2((a b) (c d))
address@hidden lisp
+
address@hidden(apply array-from array indices)} is equivalent to
+
address@hidden
+(let ((len (length indices)))
+  (if (= (array-rank a) len)
+    (apply array-ref a indices)
+    (apply make-shared-array a
+           (lambda t (append indices t))
+           (drop (array-dimensions a) len))))
address@hidden lisp
+
+The name `from' comes from the J language.
address@hidden deffn
+
address@hidden {Scheme Procedure} array-from* array idx @dots{}
address@hidden {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 a place to
+write into.
+
+Compare:
+
address@hidden
+(array-from #2((a b) (c d)) 1 1) @result{} d
+(array-from* #2((a b) (c d)) 1) @result{} #0(d)
+(define a (make-array 'a 2 2))
+(array-fill! (array-from* a 1 1) 'b)
+a @result{} #2((a a) (a b)).
+(array-fill! (array-from a 1 1) 'b) @result{} error: not an array
address@hidden lisp
+
address@hidden(apply array-from* array indices)} is equivalent to
+
address@hidden
+(apply make-shared-array a
+  (lambda t (append indices t))
+  (drop (array-dimensions a) (length indices)))
address@hidden lisp
address@hidden deffn
+
+
address@hidden {Scheme Procedure} array-amend! array x idx @dots{}
address@hidden {C Function} scm_array_amend_x (array, x, idxlist)
+If the length of @var{idxlist} equals the rank @math{n} of
address@hidden, set the element at @code{(idx @dots{})} of @var{array} to
address@hidden, just like @code{(array-set! array x idx @dots{})}. If,
+however, the length @math{k} of @var{idxlist} is shorter than
address@hidden, then copy the @math{(n-k)}-rank array @var{x}
+into the @math{(n-k)}-cell of @var{array} given by
address@hidden In this case, the last @math{(n-k)} dimensions of
address@hidden and the dimensions of @var{x} must match exactly.
+
+This function returns the modified @var{array}.
+
+For example:
+
address@hidden
+(array-amend! (make-array 'a 2 2) b 1 1) @result{} #2((a a) (a b))
+(array-amend! (make-array 'a 2 2) #(x y) 1) @result{} #2((a a) (x y))
address@hidden lisp
+
+Note that @code{array-amend!} will expect elements, not arrays, when the
+destination has rank 0. One can work around this using
address@hidden instead.
+
address@hidden
+(array-amend! (make-array 'a 2 2) #0(b) 1 1) @result{} #2((a a) (a #0(b)))
+(let ((a (make-array 'a 2 2))) (array-copy! #0(b) (array-from* a 1 1)) a) 
@result{} #2((a a) (a b))
address@hidden lisp
+
address@hidden(apply array-amend! array x indices)} is equivalent to
+
address@hidden
+(let ((len (length indices)))
+  (if (= (array-rank array) len)
+    (apply array-set! array x indices)
+    (array-copy! x (apply array-from array indices)))
+  array)
address@hidden lisp
+
+The name `amend' comes from the J language.
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 ≥ @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
+(rank(@var{x}) - @var{frame-rank})-cells from @var{x}, in unspecified order.
+
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.
+
+This function returns an unspecified value.
+
+For example, to sort the rows of rank-2 array @code{a}:
+
address@hidden
+(array-for-each-cell 1 (lambda (x) (sort! x <)) a)
address@hidden lisp
+
+As another example, let @code{a} be a rank-2 array where each row is a 
2-vector @math{(x,y)}.
+Let's compute the arguments of these vectors and store them in rank-1 array 
@code{b}.
address@hidden
+(array-for-each-cell 1
+  (lambda (a b)
+    (array-set! b (atan (array-ref a 1) (array-ref a 0))))
+  a b)
address@hidden lisp
+
address@hidden(apply array-for-each-cell frame-rank op x)} is functionally
+equivalent to
+
address@hidden
+(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)))))
address@hidden lisp
+
address@hidden deffn
+
+
 @node Accessing Arrays from C
 @subsubsection Accessing Arrays from C