@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
