(Conventional Arrays): Revise for clarity.

In array-equal?, show multiple arguments allowed.
(Uniform Arrays): Remove duplicate array?.

diff --git a/doc/ref/scheme-compound.texi b/doc/ref/scheme-compound.texi
index 5137ecf..8f0d4bf 100644 (file)
--- a/doc/ref/scheme-compound.texi
+++ b/doc/ref/scheme-compound.texi
@@ -1186,91 +1186,115 @@ Return the vtable tag of the structure @var{handle}.
 @dfn{Conventional arrays} are a collection of cells organized into an
 arbitrary number of dimensions.  Each cell can hold any kind of Scheme
 value and can be accessed in constant time by supplying an index for
-each dimension.  This contrasts with uniform arrays, which use memory
-more efficiently but can hold data of only a single type, and lists
-where inserting and deleting cells is more efficient, but more time
-is usually required to access a particular cell.
+each dimension.
+
+This contrasts with uniform arrays, which use memory more efficiently
+but can hold data of only a single type.  It contrasts also with lists
+where inserting and deleting cells is more efficient, but more time is
+usually required to access a particular cell.
 
 A conventional array is displayed as @code{#} followed by the @dfn{rank}
 (number of dimensions) followed by the cells, organized into dimensions
 using parentheses.  The nesting depth of the parentheses is equal to
 the rank.
 
-When an array is created, the number of dimensions and range of each
-dimension must be specified, e.g., to create a 2x3 array with a
-zero-based index:
+When an array is created, the range of each dimension must be
+specified, e.g., to create a 2@cross{}3 array with a zero-based index:
 
 @example
-(make-array 'ho 2 3) @result{}
-#2((ho ho ho) (ho ho ho))
+(make-array 'ho 2 3) @result{} #2((ho ho ho) (ho ho ho))
 @end example
 
 The range of each dimension can also be given explicitly, e.g., another
 way to create the same array:
 
 @example
-(make-array 'ho '(0 1) '(0 2)) @result{}
-#2((ho ho ho) (ho ho ho))
+(make-array 'ho '(0 1) '(0 2)) @result{} #2((ho ho ho) (ho ho ho))
 @end example
 
 A conventional array with one dimension based at zero is identical to
 a vector:
 
 @example
-(make-array 'ho 3) @result{}
-#(ho ho ho)
+(make-array 'ho 3) @result{} #(ho ho ho)
 @end example
 
-The following procedures can be used with conventional arrays (or vectors).
+The following procedures can be used with conventional arrays (or
+vectors).  An argument shown as @var{idx}@dots{} means one parameter
+for each dimension in the array.  Or a @var{idxlist} is a list of such
+values, one for each dimension.
 
-@deffn {Scheme Procedure} array? v [prot]
-@deffnx {C Function} scm_array_p (v, prot)
+@deffn {Scheme Procedure} array? obj [prot]
+@deffnx {C Function} scm_array_p (obj, prot)
 Return @code{#t} if the @var{obj} is an array, and @code{#f} if
-not.  The @var{prototype} argument is used with uniform arrays
-and is described elsewhere.
+not.
+
+The @var{prot} argument is used with uniform arrays (@pxref{Uniform
+Arrays}).  If given then the return is @code{#t} if @var{obj} is an
+array and of that prototype.
 @end deffn
 
-@deffn {Scheme Procedure} make-array initial-value bound1 bound2 @dots{}
+@deffn {Scheme Procedure} make-array initial-value bound @dots{}
 Create and return an array that has as many dimensions as there are
-@var{bound}s and fill it with @var{initial-value}.  Each @var{bound}
+@var{bound}s and fill it with @var{initial-value}.
+
+Each @var{bound}
 may be a positive non-zero integer @var{N}, in which case the index for
 that dimension can range from 0 through @var{N-1}; or an explicit index
 range specifier in the form @code{(LOWER UPPER)}, where both @var{lower}
 and @var{upper} are integers, possibly less than zero, and possibly the
 same number (however, @var{lower} cannot be greater than @var{upper}).
+See examples above.
 @end deffn
 
 @c array-ref's type is `compiled-closure'.  There's some weird stuff
 @c going on in array.c, too.  Let's call it a primitive. -twp
 
-@deffn {Scheme Procedure} uniform-vector-ref v args
-@deffnx {Scheme Procedure} array-ref v . args
-@deffnx {C Function} scm_uniform_vector_ref (v, args)
-Return the element at the @code{(index1, index2)} element in
-@var{array}.
+@deffn {Scheme Procedure} array-ref array idx @dots{}
+@deffnx {Scheme Procedure} uniform-vector-ref vec args
+@deffnx {C Function} scm_uniform_vector_ref (vec, args)
+Return the element at @code{(idx @dots{})} in @var{array}.
+
+@example
+(define a (make-array 999 '(1 2) '(3 4)))
+(array-ref a 2 4) @result{} 999
+@end example
 @end deffn
 
-@deffn {Scheme Procedure} array-in-bounds? v . args
-@deffnx {C Function} scm_array_in_bounds_p (v, args)
-Return @code{#t} if its arguments would be acceptable to
+@deffn {Scheme Procedure} array-in-bounds? array idx @dots{}
+@deffnx {C Function} scm_array_in_bounds_p (array, idxlist)
+Return @code{#t} if the given index would be acceptable to
 @code{array-ref}.
+
+@example
+(define a (make-array #f '(1 2) '(3 4)))
+(array-in-bounds? a 2 3) @result{} #f
+(array-in-bounds? a 0 0) @result{} #f
+@end example
 @end deffn
 
 @c fixme: why do these sigs differ?  -ttn 2001/07/19 01:14:12
-@deffn {Scheme Procedure} array-set! v obj . args
-@deffnx {Scheme Procedure} uniform-array-set1! v obj args
-@deffnx {C Function} scm_array_set_x (v, obj, args)
-Set the element at the @code{(index1, index2)} element in @var{array} to
-@var{new-value}.  The value returned by array-set! is unspecified.
+@deffn {Scheme Procedure} array-set! array obj idx @dots{}
+@deffnx {Scheme Procedure} uniform-array-set1! array obj idxlist
+@deffnx {C Function} scm_array_set_x (array, obj, idxlist)
+Set the element at @code{(idx @dots{})} in @var{array} to @var{obj}.
+The return value is unspecified.
+
+@example
+(define a (make-array #f '(0 1) '(0 1)))
+(array-set! a #t 1 1)
+a @result{} #2((#f #f) (#f #t))
+@end example
 @end deffn
 
-@deffn {Scheme Procedure} make-shared-array oldra mapfunc . dims
-@deffnx {C Function} scm_make_shared_array (oldra, mapfunc, dims)
+@deffn {Scheme Procedure} make-shared-array oldarray mapfunc bound @dots{}
+@deffnx {C Function} scm_make_shared_array (oldarray, mapfunc, boundlist)
 @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:
+
 @lisp
 (define fred (make-array #f 8 8))
 (define freds-diagonal
@@ -1283,32 +1307,32 @@ it can be otherwise arbitrary.  A simple example:
 @end lisp
 @end deffn
 
-@deffn {Scheme Procedure} shared-array-increments ra
-@deffnx {C Function} scm_shared_array_increments (ra)
+@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 ra
-@deffnx {C Function} scm_shared_array_offset (ra)
+@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 ra
-@deffnx {C Function} scm_shared_array_root (ra)
+@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} transpose-array ra . args
-@deffnx {C Function} scm_transpose_array (ra, args)
+@deffn {Scheme Procedure} transpose-array array dim1 @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{dim0}, @var{dim1}, @dots{} should be integers between 0
+@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{dim0}, @var{dim1}, @dots{} correspond to
-dimensions in the array to be returned, their positions in the
+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}.
@@ -1321,10 +1345,10 @@ have smaller rank than @var{array}.
 @end lisp
 @end deffn
 
-@deffn {Scheme Procedure} enclose-array ra . axes
-@deffnx {C Function} scm_enclose_array (ra, axes)
-@var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than
-the rank of @var{array}.  @var{enclose-array} returns an array
+@deffn {Scheme Procedure} enclose-array array dim1 @dots{}
+@deffnx {C Function} scm_enclose_array (array, dimlist)
+@var{dim1}, @var{dim2} @dots{} should be nonnegative integers less than
+the rank of @var{array}.  @code{enclose-array} returns an array
 resembling an array of shared arrays.  The dimensions of each shared
 array are the same as the @var{dim}th dimensions of the original array,
 the dimensions of the outer array are the same as those of the original
@@ -1333,67 +1357,76 @@ array that did not match a @var{dim}.
 An enclosed array is not a general Scheme array.  Its elements may not
 be set using @code{array-set!}.  Two references to the same element of
 an enclosed array will be @code{equal?} but will not in general be
-@code{eq?}.  The value returned by @var{array-prototype} when given an
+@code{eq?}.  The value returned by @code{array-prototype} when given an
 enclosed array is unspecified.
 
-examples:
+For example,
+
 @lisp
-(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}
-   #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
+(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1)
+@result{}
+#<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
 
-(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}
-   #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
+(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0)
+@result{}
+#<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
 @end lisp
 @end deffn
 
 @deffn {Scheme Procedure} array-shape array
-Return a list of inclusive bounds of integers.
+@deffnx {Scheme Procedure} array-dimensions array
+@deffnx {C Function} scm_array_dimensions (array)
+Return a list of the bounds for each dimenson of @var{array}.
+
+@code{array-shape} gives @code{(@var{lower} @var{upper})} for each
+dimension.  @code{array-dimensions} instead returns just
+@math{@var{upper}+1} for dimensions with a 0 lower bound.  Both are
+suitable as input to @code{make-array}.
+
+For example,
+
 @example
-(array-shape (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) (0 4))
+(define a (make-array 'foo '(-1 3) 5))
+(array-shape a)      @result{} ((-1 3) (0 4))
+(array-dimensions a) @result{} ((-1 3) 5)
 @end example
 @end deffn
 
-@deffn {Scheme Procedure} array-dimensions ra
-@deffnx {C Function} scm_array_dimensions (ra)
-@code{Array-dimensions} is similar to @code{array-shape} but replaces
-elements with a @code{0} minimum with one greater than the maximum. So:
-@lisp
-(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)
-@end lisp
+@deffn {Scheme Procedure} array-rank obj
+@deffnx {C Function} scm_array_rank (obj)
+Return the number of dimensions of an array @var{obj}, or if @var{obj}
+is not an array then return 0.
 @end deffn
 
-@deffn {Scheme Procedure} array-rank ra
-@deffnx {C Function} scm_array_rank (ra)
-Return the number of dimensions of @var{obj}.  If @var{obj} is
-not an array, @code{0} is returned.
-@end deffn
-
-@deffn {Scheme Procedure} array->list v
-@deffnx {C Function} scm_array_to_list (v)
+@deffn {Scheme Procedure} array->list array
+@deffnx {C Function} scm_array_to_list (array)
 Return a list consisting of all the elements, in order, of
 @var{array}.
 @end deffn
 
+@c  FIXME: Describe how the order affects the copying (it matters for
+@c  shared arrays with the same underlying root vector, presumably).
+@c
 @deffn {Scheme Procedure} array-copy! src dst
 @deffnx {Scheme Procedure} array-copy-in-order! src dst
 @deffnx {C Function} scm_array_copy_x (src, dst)
-Copy every element from vector or array @var{source} to the
-corresponding element of @var{destination}.  @var{destination} must have
-the same rank as @var{source}, and be at least as large in each
-dimension.  The order is unspecified.
+Copy every element from vector or array @var{src} to the corresponding
+element of @var{dst}.  @var{dst} must have the same rank as @var{src},
+and be at least as large in each dimension.  The return value is
+unspecified.
 @end deffn
 
-@deffn {Scheme Procedure} array-fill! ra fill
-@deffnx {C Function} scm_array_fill_x (ra, fill)
+@deffn {Scheme Procedure} array-fill! array fill
+@deffnx {C Function} scm_array_fill_x (array, fill)
 Store @var{fill} in every element of @var{array}.  The value returned
 is unspecified.
 @end deffn
 
 @c begin (texi-doc-string "guile" "array-equal?")
-@deffn {Scheme Procedure} array-equal? ra0 ra1
-Return @code{#t} iff all arguments are arrays with the same shape, the
+@deffn {Scheme Procedure} array-equal? array1 array2 @dots{}
+Return @code{#t} if all arguments are arrays with the same shape, the
 same type, and have corresponding elements which are either
-@code{equal?}  or @code{array-equal?}.  This function differs from
+@code{equal?} or @code{array-equal?}.  This function differs from
 @code{equal?} in that a one dimensional shared array may be
 @var{array-equal?} but not @var{equal?} to a vector or uniform vector.
 @end deffn
@@ -1403,9 +1436,9 @@ same type, and have corresponding elements which are either
 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 @var{make-array} and
-@var{make-uniform-array} may be unrolled, some arrays made by
-@var{make-shared-array} may not be.
+@code{#f}.  All arrays made by @code{make-array} and
+@code{make-uniform-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
@@ -1544,13 +1577,6 @@ except that a single character from the above table is put between
 @code{#} and @code{(}.  For example, a uniform vector of signed
 long integers is displayed in the form @code{'#e(3 5 9)}.
 
-@deffn {Scheme Procedure} array? v [prot]
-Return @code{#t} if the @var{obj} is an array, and @code{#f} if not.
-
-The @var{prototype} argument is used with uniform arrays and is described
-elsewhere.
-@end deffn
-
 @deffn {Scheme Procedure} make-uniform-array prototype bound1 bound2 @dots{}
 Create and return a uniform array of type corresponding to
 @var{prototype} that has as many dimensions as there are @var{bound}s
@@ -1676,11 +1702,12 @@ Modify @var{bitvector} by replacing each element with its negation.
 @deffn {Scheme Procedure} bit-set*! bitvector uvec bool
 @deffnx {C Function} scm_bit_set_star_x (bitvector, uvec, bool)
 Set entries of @var{bitvector} to @var{bool}, with @var{uvec}
-selecting the entries to change.
+selecting the entries to change.  The return value is unspecified.
 
 If @var{uvec} is a bit vector, then those entries where it has
 @code{#t} are the ones in @var{bitvector} which are set to @var{bool}.
-When @var{bool} is @code{#t} it's like @var{uvec} is OR'ed into
+@var{uvec} and @var{bitvector} must be the same length.  When
+@var{bool} is @code{#t} it's like @var{uvec} is OR'ed into
 @var{bitvector}.  Or when @var{bool} is @code{#f} it can be seen as an
 ANDNOT.