summaryrefslogtreecommitdiffstats
path: root/array.txi
diff options
context:
space:
mode:
authorBryan Newbold <bnewbold@robocracy.org>2017-02-20 00:05:31 -0800
committerBryan Newbold <bnewbold@robocracy.org>2017-02-20 00:05:31 -0800
commit5145dd3aa0c02c9fc496d1432fc4410674206e1d (patch)
tree540afc30c51da085f5bd8ec3f4c89f6496e7900d /array.txi
parent8466d8cfa486fb30d1755c4261b781135083787b (diff)
downloadslib-5145dd3aa0c02c9fc496d1432fc4410674206e1d.tar.gz
slib-5145dd3aa0c02c9fc496d1432fc4410674206e1d.zip
Import Upstream version 3a2upstream/3a2
Diffstat (limited to 'array.txi')
-rw-r--r--array.txi376
1 files changed, 261 insertions, 115 deletions
diff --git a/array.txi b/array.txi
index bb09e16..a00ab97 100644
--- a/array.txi
+++ b/array.txi
@@ -1,4 +1,4 @@
-@code{(require 'array)}
+@code{(require 'array)} or @code{(require 'srfi-63)}
@ftindex array
@@ -6,10 +6,11 @@
Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not.
@end defun
+
@noindent
-@emph{Note:} Arrays are not disjoint from other Scheme types. Strings
-and vectors also satisfy @code{array?}. A disjoint array predicate can
-be written:
+@emph{Note:} Arrays are not disjoint from other Scheme types.
+Vectors and possibly strings also satisfy @code{array?}.
+A disjoint array predicate can be written:
@example
(define (strict-array? obj)
@@ -17,32 +18,184 @@ be written:
@end example
-@defun array=? array1 array2
+@defun equal? obj1 obj2
+
+Returns @code{#t} if @var{obj1} and @var{obj2} have the same rank and dimensions and the
+corresponding elements of @var{obj1} and @var{obj2} are @code{equal?}.
-Returns @code{#t} if @var{array1} and @var{array2} have the same rank and shape and the
-corresponding elements of @var{array1} and @var{array2} are @code{equal?}.
+@code{equal?} recursively compares the contents of pairs, vectors, strings, and
+@emph{arrays}, applying @code{eqv?} on other objects such as numbers
+and symbols. A rule of thumb is that objects are generally @code{equal?} if
+they print the same. @code{equal?} may fail to terminate if its arguments are
+circular data structures.
@example
-(array=? (create-array '#(foo) 3 3)
- (create-array '#(foo) '(0 2) '(0 2)))
- @result{} #t
+(equal? 'a 'a) @result{} #t
+(equal? '(a) '(a)) @result{} #t
+(equal? '(a (b) c)
+ '(a (b) c)) @result{} #t
+(equal? "abc" "abc") @result{} #t
+(equal? 2 2) @result{} #t
+(equal? (make-vector 5 'a)
+ (make-vector 5 'a)) @result{} #t
+(equal? (make-array (A:fixN32b 4) 5 3)
+ (make-array (A:fixN32b 4) 5 3)) @result{} #t
+(equal? (make-array '#(foo) 3 3)
+ (make-array '#(foo) 3 3)) @result{} #t
+(equal? (lambda (x) x)
+ (lambda (y) y)) @result{} @emph{unspecified}
@end example
@end defun
-@defun create-array prototype bound1 bound2 @dots{}
+@defun array-rank obj
+
+Returns the number of dimensions of @var{obj}. If @var{obj} is not an array, 0 is
+returned.
+@end defun
+
+
+@defun array-dimensions array
+
+Returns a list of dimensions.
-Creates and returns an array of type @var{prototype} with dimensions @var{bound1}, @var{bound2},
-@dots{} and filled with elements from @var{prototype}. @var{prototype} must be an array,
-vector, or string. The implementation-dependent type of the returned
-array will be the same as the type of @var{prototype}; except if that would be a
-vector or string with non-zero origin, in which case some variety of
+@example
+(array-dimensions (make-array '#() 3 5))
+ @result{} (3 5)
+@end example
+@end defun
+
+
+@defun make-array prototype k1 @dots{}
+
+
+Creates and returns an array of type @var{prototype} with dimensions @var{k1}, @dots{}
+and filled with elements from @var{prototype}. @var{prototype} must be an array, vector, or
+string. The implementation-dependent type of the returned array
+will be the same as the type of @var{prototype}; except if that would be a vector
+or string with rank not equal to one, in which case some variety of
array will be returned.
If the @var{prototype} has no elements, then the initial contents of the returned
array are unspecified. Otherwise, the returned array will be filled
with the element at the origin of @var{prototype}.
@end defun
+
+
+@defun create-array prototype k1 @dots{}
+
+@code{create-array} is an alias for @code{make-array}.
+@end defun
+
+
+@defun make-shared-array array mapper k1 @dots{}
+
+@code{make-shared-array} can be used to create shared subarrays of other
+arrays. The @var{mapper} is a function that translates coordinates in
+the new array into coordinates in the old array. A @var{mapper} must be
+linear, and its range must stay within the bounds of the old array, but
+it can be otherwise arbitrary. A simple example:
+
+@example
+(define fred (make-array '#(#f) 8 8))
+(define freds-diagonal
+ (make-shared-array fred (lambda (i) (list i i)) 8))
+(array-set! freds-diagonal 'foo 3)
+(array-ref fred 3 3)
+ @result{} FOO
+(define freds-center
+ (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j)))
+ 2 2))
+(array-ref freds-center 0 0)
+ @result{} FOO
+@end example
+@end defun
+
+
+@defun list->array rank proto list
+
+@var{list} must be a rank-nested list consisting of all the elements, in
+row-major order, of the array to be created.
+
+@code{list->array} returns an array of rank @var{rank} and type @var{proto} consisting of all the
+elements, in row-major order, of @var{list}. When @var{rank} is 0, @var{list} is the lone
+array element; not necessarily a list.
+
+@example
+(list->array 2 '#() '((1 2) (3 4)))
+ @result{} #2A((1 2) (3 4))
+(list->array 0 '#() 3)
+ @result{} #0A 3
+@end example
+@end defun
+
+
+@defun array->list array
+
+Returns a rank-nested list consisting of all the elements, in
+row-major order, of @var{array}. In the case of a rank-0 array, @code{array->list} returns
+the single element.
+
+@example
+(array->list #2A((ho ho ho) (ho oh oh)))
+ @result{} ((ho ho ho) (ho oh oh))
+(array->list #0A ho)
+ @result{} ho
+@end example
+@end defun
+
+
+@defun vector->array vect proto dim1 @dots{}
+
+@var{vect} must be a vector of length equal to the product of exact
+nonnegative integers @var{dim1}, @dots{}.
+
+@code{vector->array} returns an array of type @var{proto} consisting of all the elements, in
+row-major order, of @var{vect}. In the case of a rank-0 array, @var{vect} has a
+single element.
+
+@example
+(vector->array #(1 2 3 4) #() 2 2)
+ @result{} #2A((1 2) (3 4))
+(vector->array '#(3) '#())
+ @result{} #0A 3
+@end example
+@end defun
+
+
+@defun array->vector array
+
+Returns a new vector consisting of all the elements of @var{array} in
+row-major order.
+
+@example
+(array->vector #2A ((1 2)( 3 4)))
+ @result{} #(1 2 3 4)
+(array->vector #0A ho)
+ @result{} #(ho)
+@end example
+@end defun
+
+
+@defun array-in-bounds? array index1 @dots{}
+
+Returns @code{#t} if its arguments would be acceptable to
+@code{array-ref}.
+@end defun
+
+
+@defun array-ref array k1 @dots{}
+
+Returns the (@var{k1}, @dots{}) element of @var{array}.
+@end defun
+
+
+@deffn {Procedure} array-set! array obj k1 @dots{}
+
+Stores @var{obj} in the (@var{k1}, @dots{}) element of @var{array}. The value returned
+by @code{array-set!} is unspecified.
+@end deffn
+
@noindent
These functions return a prototypical uniform-array enclosing the
optional argument (which must be of the correct type). If the
@@ -51,177 +204,170 @@ returned; defaulting to the next larger precision type; resorting
finally to vector.
-@defun ac64 z
+@defun a:floc128b z
-@defunx ac64
-Returns a high-precision complex uniform-array prototype.
+@defunx a:floc128b
+Returns an inexact 128.bit flonum complex uniform-array prototype.
@end defun
-@defun ac32 z
+
+@defun a:floc64b z
-@defunx ac32
-Returns a complex uniform-array prototype.
+@defunx a:floc64b
+Returns an inexact 64.bit flonum complex uniform-array prototype.
@end defun
-@defun ar64 x
+
+@defun a:floc32b z
-@defunx ar64
-Returns a high-precision real uniform-array prototype.
+@defunx a:floc32b
+Returns an inexact 32.bit flonum complex uniform-array prototype.
@end defun
-@defun ar32 x
+@defun a:floc16b z
-@defunx ar32
-Returns a real uniform-array prototype.
+
+@defunx a:floc16b
+Returns an inexact 16.bit flonum complex uniform-array prototype.
@end defun
-@defun as64 n
+@defun a:flor128b z
-@defunx as64
-Returns an exact signed integer uniform-array prototype with at least
-64 bits of precision.
+
+@defunx a:flor128b
+Returns an inexact 128.bit flonum real uniform-array prototype.
@end defun
-@defun as32 n
+@defun a:flor64b z
-@defunx as32
-Returns an exact signed integer uniform-array prototype with at least
-32 bits of precision.
+
+@defunx a:flor64b
+Returns an inexact 64.bit flonum real uniform-array prototype.
@end defun
-@defun as16 n
+@defun a:flor32b z
-@defunx as16
-Returns an exact signed integer uniform-array prototype with at least
-16 bits of precision.
+
+@defunx a:flor32b
+Returns an inexact 32.bit flonum real uniform-array prototype.
@end defun
-@defun as8 n
+@defun a:flor16b z
-@defunx as8
-Returns an exact signed integer uniform-array prototype with at least
-8 bits of precision.
+
+@defunx a:flor16b
+Returns an inexact 16.bit flonum real uniform-array prototype.
@end defun
-@defun au64 k
+@defun a:flor128b z
-@defunx au64
-Returns an exact non-negative integer uniform-array prototype with at
-least 64 bits of precision.
+
+@defunx a:flor128b
+Returns an exact 128.bit decimal flonum rational uniform-array prototype.
@end defun
-@defun au32 k
+@defun a:flor64b z
-@defunx au32
-Returns an exact non-negative integer uniform-array prototype with at
-least 32 bits of precision.
+
+@defunx a:flor64b
+Returns an exact 64.bit decimal flonum rational uniform-array prototype.
@end defun
-@defun au16 k
+@defun a:flor32b z
-@defunx au16
-Returns an exact non-negative integer uniform-array prototype with at
-least 16 bits of precision.
+
+@defunx a:flor32b
+Returns an exact 32.bit decimal flonum rational uniform-array prototype.
@end defun
-@defun au8 k
+@defun a:fixz64b n
-@defunx au8
-Returns an exact non-negative integer uniform-array prototype with at
-least 8 bits of precision.
+
+@defunx a:fixz64b
+Returns an exact binary fixnum uniform-array prototype with at least
+64 bits of precision.
@end defun
-@defun at1 bool
+@defun a:fixz32b n
-@defunx at1
-Returns a boolean uniform-array prototype.
-@end defun
-@noindent
-When constructing an array, @var{bound} is either an inclusive range of
-indices expressed as a two element list, or an upper bound expressed as
-a single integer. So
-@example
-(create-array '#(foo) 3 3) @equiv{} (create-array '#(foo) '(0 2) '(0 2))
-@end example
+@defunx a:fixz32b
+Returns an exact binary fixnum uniform-array prototype with at least
+32 bits of precision.
+@end defun
-@defun make-shared-array array mapper bound1 bound2 @dots{}
+@defun a:fixz16b n
-@code{make-shared-array} can be used to create shared subarrays of other
-arrays. The @var{mapper} is a function that translates coordinates in
-the new array into coordinates in the old array. A @var{mapper} must be
-linear, and its range must stay within the bounds of the old array, but
-it can be otherwise arbitrary. A simple example:
-@example
-(define fred (create-array '#(#f) 8 8))
-(define freds-diagonal
- (make-shared-array fred (lambda (i) (list i i)) 8))
-(array-set! freds-diagonal 'foo 3)
-(array-ref fred 3 3)
- @result{} FOO
-(define freds-center
- (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j)))
- 2 2))
-(array-ref freds-center 0 0)
- @result{} FOO
-@end example
+@defunx a:fixz16b
+Returns an exact binary fixnum uniform-array prototype with at least
+16 bits of precision.
@end defun
-@defun array-rank obj
-Returns the number of dimensions of @var{obj}. If @var{obj} is not an array, 0 is
-returned.
+@defun a:fixz8b n
+
+
+@defunx a:fixz8b
+Returns an exact binary fixnum uniform-array prototype with at least
+8 bits of precision.
@end defun
-@defun array-shape array
-Returns a list of inclusive bounds.
+@defun a:fixn64b k
-@example
-(array-shape (create-array '#() 3 5))
- @result{} ((0 2) (0 4))
-@end example
+
+@defunx a:fixn64b
+Returns an exact non-negative binary fixnum uniform-array prototype with at
+least 64 bits of precision.
@end defun
-@defun array-dimensions array
-@code{array-dimensions} is similar to @code{array-shape} but replaces
-elements with a 0 minimum with one greater than the maximum.
+@defun a:fixn32b k
-@example
-(array-dimensions (create-array '#() 3 5))
- @result{} (3 5)
-@end example
+
+@defunx a:fixn32b
+Returns an exact non-negative binary fixnum uniform-array prototype with at
+least 32 bits of precision.
@end defun
-@defun array-in-bounds? array index1 index2 @dots{}
-Returns @code{#t} if its arguments would be acceptable to
-@code{array-ref}.
+@defun a:fixn16b k
+
+
+@defunx a:fixn16b
+Returns an exact non-negative binary fixnum uniform-array prototype with at
+least 16 bits of precision.
@end defun
-@defun array-ref array index1 index2 @dots{}
-Returns the (@var{index1}, @var{index2}, @dots{}) element of @var{array}.
+@defun a:fixn8b k
+
+
+@defunx a:fixn8b
+Returns an exact non-negative binary fixnum uniform-array prototype with at
+least 8 bits of precision.
@end defun
-@deffn {Procedure} array-set! array obj index1 index2 @dots{}
-Stores @var{obj} in the (@var{index1}, @var{index2}, @dots{}) element of @var{array}. The value returned
-by @code{array-set!} is unspecified.
-@end deffn
+@defun a:bool bool
+
+
+@defunx a:bool
+Returns a boolean uniform-array prototype.
+@end defun
+