Import Upstream version 3a1upstream/3a1

1 files changed, 94 insertions, 0 deletions

diff --git a/subarray.txi b/subarray.txi
new file mode 100644
index 0000000..7d62ed6
--- /dev/null
+++ b/subarray.txi
@@ -0,0 +1,94 @@
+@code{(require 'subarray)}
+@ftindex subarray
+
+
+@defun subarray array select @dots{}
+
+selects a subset of an array.  For @var{array} of rank n, there must be at least
+n @var{selects} arguments.  For 0 <= @i{j} < n, @var{selects}@i{j} is either an integer, a
+list of two integers within the range for the @i{j}th index, or #f.
+
+When @var{selects}@i{j} is a list of two integers, then the @i{j}th index is
+restricted to that subrange in the returned array.
+
+When @var{selects}@i{j} is #f, then the full range of the @i{j}th index is
+accessible in the returned array.  An elided argument is equivalent to #f.
+
+When @var{selects}@i{j} is an integer, then the rank of the returned array is
+less than @var{array}, and only elements whose @i{j}th index equals @var{selects}@i{j} are
+shared.
+
+@example
+> (define ra '#2A((a b c) (d e f)))
+#<unspecified>
+> (subarray ra 0 #f)
+#1A(a b c)
+> (subarray ra 1 #f)
+#1A(d e f)
+> (subarray ra #f 1)
+#1A(b e)
+> (subarray ra '(0 1) #f)
+#2A((a b c) (d e f))
+> (subarray ra #f '(0 1))
+#2A((a b) (d e))
+> (subarray ra #f '(1 2))
+#2A((b c) (e f))
+@end example
+@end defun
+
+@defun subarray0 array select @dots{}
+
+Behaves like @r{subarray}, but @r{align}s the returned array origin to
+0 @dots{}.
+@end defun
+
+@defun array-align array coord @dots{}
+
+
+Returns an array shared with @var{array} but with a different origin.  The @var{coords}
+are the exact integer coordinates of the new origin.  Indexes
+corresponding to missing or #f coordinates are not realigned.
+
+For example:
+@example
+(define ra2 (create-array '#(5) '(5 9) '(-4 0)))
+(array-shape ra2)                       @result{} ((5 9) (-4 0))
+(array-shape (array-align ra2 0 0))     @result{} ((0 4) (0 4))
+(array-shape (array-align ra2 0))       @result{} ((0 4) (-4 0))
+(array-shape (array-align ra2))         @result{} ((5 9) (-4 0))
+(array-shape (array-align ra2 0 #f))    @result{} ((0 4) (-4 0))
+(array-shape (array-align ra2 #f 0))    @result{} ((5 9) (0 4))
+@end example
+@end defun
+  
+@defun array-trim array trim @dots{}
+
+
+Returns a subarray sharing contents with @var{array} except for slices removed
+from either side of each dimension.  Each of the @var{trims} is an exact
+integer indicating how much to trim.  A positive @var{s} trims the
+data from the lower end and reduces the upper bound of the result; a
+negative @var{s} trims from the upper end and increases the lower
+bound.
+
+For example:
+@example
+(array-trim '#(0 1 2 3 4) 1)  @result{} #1A(1 2 3 4) ;; shape is ((0 3))
+(array-trim '#(0 1 2 3 4) -1) @result{} #1A(0 1 2 3) ;; shape is ((1 4))
+
+(require 'array-for-each)
+(define (centered-difference ra)
+  (array-map - (array-trim ra 1) (array-trim ra -1)))
+(define (forward-difference ra)
+  (array-map - (array-trim ra 1) ra))
+(define (backward-difference ra)
+  (array-map - ra (array-trim ra -1)))
+
+(centered-difference '#(0 1 3 5 9 22))
+  @result{} #1A(3 4 6 17) ;;shape is ((1 4))
+(backward-difference '#(0 1 3 5 9 22))
+  @result{} #1A(1 2 2 4 13) ;; shape is ((1 5))
+(forward-difference '#(0 1 3 5 9 22))
+  @result{} #(1 2 2 4 13)  ;; shape is ((0 4))
+@end example
+@end defun