summaryrefslogtreecommitdiff
path: root/doc/ref/api-compound.texi
diff options
context:
space:
mode:
authorDaniel Llorens <daniel.llorens@bluewin.ch>2015-09-08 16:57:30 +0200
committerDaniel Llorens <daniel.llorens@bluewin.ch>2016-11-18 12:03:30 +0100
commita5bb9da6ea3f69a0e03329b94dcb3bf1c3315ed5 (patch)
treecdd036904704464a2268d0c19bbf5e10b22e56cf /doc/ref/api-compound.texi
parent1945cdf491c669ce54f94b90fd083f71642d1b2e (diff)
downloadguile-a5bb9da6ea3f69a0e03329b94dcb3bf1c3315ed5.tar.gz
New functions (array-for-each-cell, array-for-each-cell-in-order)lloda-squash0
* libguile/array-map.c (scm_i_array_rebase, scm_array_for_each_cell): New functions. Export scm_array_for_each_cell() as (array-for-each-cell). (array-for-each-cell-in-order): Define additional export. * libguile/array-map.h (scm_i_array_rebase, scm_array_for_each_cell): Add prototypes. * 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). * test-suite/tests/array-map.test: Renamed from test-suite/tests/ramap.test, fix module name. Add tests for (array-for-each-cell). * test-suite/Makefile.am: Apply rename array-map.test -> ramap.test. * doc/ref/api-compound.texi: Minor documentation fixes.
Diffstat (limited to 'doc/ref/api-compound.texi')
-rw-r--r--doc/ref/api-compound.texi169
1 files changed, 118 insertions, 51 deletions
diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
index 6d1e118b6..936b4956c 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
@@ -1682,24 +1683,91 @@ 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:
-@example
@lisp
(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))
@end lisp
-@end example
@code{(apply array-from array indices)} is equivalent to
@@ -1719,12 +1787,11 @@ 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:
-@example
@lisp
(array-from #2((a b) (c d)) 1 1) @result{} d
(array-from* #2((a b) (c d)) 1) @result{} #0(d)
@@ -1733,7 +1800,6 @@ Compare:
a @result{} #2((a a) (a b)).
(array-fill! (array-from a 1 1) 'b) @result{} error: not an array
@end lisp
-@end example
@code{(apply array-from* array indices)} is equivalent to
@@ -1752,7 +1818,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.
@@ -1760,12 +1826,19 @@ This function returns the modified @var{array}.
For example:
-@example
@lisp
(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))
@end lisp
-@end example
+
+Note that @code{array-amend!} will expect elements, not arrays, when the
+destination has rank 0. One can work around this using
+@code{array-from*} instead.
+
+@lisp
+(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))
+@end lisp
@code{(apply array-amend! array x indices)} is equivalent to
@@ -1781,58 +1854,52 @@ 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 ≥ @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.
-@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, to sort the rows of rank-2 array @code{a}:
-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
+@lisp
+(array-for-each-cell 1 (lambda (x) (sort! x <)) a)
+@end lisp
-@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.
+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}.
+@lisp
+(array-for-each-cell 1
+ (lambda (a b)
+ (array-set! b (atan (array-ref a 1) (array-ref a 0))))
+ a b)
+@end lisp
-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
+
@end deffn
+
@node Accessing Arrays from C
@subsubsection Accessing Arrays from C