[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Guile-commits] 16/25: Draft documentation for (array-for-each-cell)
From: |
Daniel Llorens |
Subject: |
[Guile-commits] 16/25: Draft documentation for (array-for-each-cell) |
Date: |
Mon, 11 Jul 2016 08:21:12 +0000 (UTC) |
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
- [Guile-commits] 20/25: Clean up (array-for-each-cell), (continued)
- [Guile-commits] 20/25: Clean up (array-for-each-cell), Daniel Llorens, 2016/07/11
- [Guile-commits] 03/25: Unuse array 'contiguous' flag, Daniel Llorens, 2016/07/11
- [Guile-commits] 19/25: Avoid variable stack use in scm_array_for_each_cell(), Daniel Llorens, 2016/07/11
- [Guile-commits] 17/25: New export (array-for-each-cell-in-order), Daniel Llorens, 2016/07/11
- [Guile-commits] 13/25: Remove deprecated and unused generalized-vector functions, Daniel Llorens, 2016/07/11
- [Guile-commits] 09/25: Don't use array handles in scm_c_array_rank, Daniel Llorens, 2016/07/11
- [Guile-commits] 08/25: Rename array-set-from!, scm_array_set_from_x to array-amend!, scm_array_amend_x, Daniel Llorens, 2016/07/11
- [Guile-commits] 24/25: Remove uniform-array-read!, uniform-array-write from the manual, Daniel Llorens, 2016/07/11
- [Guile-commits] 07/25: Tests & doc for array-from, array-from*, array-set-from!, Daniel Llorens, 2016/07/11
- [Guile-commits] 23/25: Remove commented stack version of scm_array_for_each_cell(), Daniel Llorens, 2016/07/11
- [Guile-commits] 16/25: Draft documentation for (array-for-each-cell),
Daniel Llorens <=
- [Guile-commits] 12/25: Speed up for multi-arg cases of scm_ramap functions, Daniel Llorens, 2016/07/11
- [Guile-commits] 21/25: Fix a corner case with empty arrays in (array-for-each-cell), Daniel Llorens, 2016/07/11
- [Guile-commits] 15/25: Draft of (array-for-each-cell), Daniel Llorens, 2016/07/11
- [Guile-commits] 22/25: Fix pool version of scm_array_for_each_cell by aligning pointers, Daniel Llorens, 2016/07/11
- [Guile-commits] 25/25: Support typed arrays in some sort functions, Daniel Llorens, 2016/07/11