GUILE_PROC(scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0,
(SCM v),
-"")
+"Returns the number of elements in @var{uve}.")
#define FUNC_NAME s_scm_uniform_vector_length
{
SCM_ASRTGO (SCM_NIMP (v), badarg1);
GUILE_PROC(scm_array_p, "array?", 1, 1, 0,
(SCM v, SCM prot),
-"")
+"Returns @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.")
#define FUNC_NAME s_scm_array_p
{
int nprot;
GUILE_PROC(scm_array_rank, "array-rank", 1, 0, 0,
(SCM ra),
-"")
+"Returns the number of dimensions of @var{obj}. If @var{obj} is not an
+array, @code{0} is returned.")
#define FUNC_NAME s_scm_array_rank
{
if (SCM_IMP (ra))
GUILE_PROC(scm_array_dimensions, "array-dimensions", 1, 0, 0,
(SCM 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:
+@example
+(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)
+@end example")
#define FUNC_NAME s_scm_array_dimensions
{
SCM res = SCM_EOL;
GUILE_PROC(scm_dimensions_to_uniform_array, "dimensions->uniform-array", 2, 1, 0,
(SCM dims, SCM prot, SCM fill),
-"")
+"@deffnx primitive make-uniform-vector length prototype [fill]
+Creates and returns a uniform array or vector of type corresponding to
+@var{prototype} with dimensions @var{dims} or length @var{length}. If
+@var{fill} is supplied, it's used to fill the array, otherwise
+@var{prototype} is used.")
#define FUNC_NAME s_scm_dimensions_to_uniform_array
{
scm_sizet k, vlen = 1;
GUILE_PROC(scm_make_shared_array, "make-shared-array", 2, 0, 1,
(SCM oldra, SCM mapfunc, SCM dims),
-"")
+"@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")
#define FUNC_NAME s_scm_make_shared_array
{
SCM ra;
/* args are RA . DIMS */
GUILE_PROC(scm_transpose_array, "transpose-array", 0, 0, 1,
(SCM args),
-"")
+"Returns 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 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 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}.
+
+examples:
+@example
+(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))
+@end example")
#define FUNC_NAME s_scm_transpose_array
{
SCM ra, res, vargs, *ve = &vargs;
/* args are RA . AXES */
GUILE_PROC(scm_enclose_array, "enclose-array", 0, 0, 1,
(SCM axes),
-"")
+"@var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than
+the rank of @var{array}. @var{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
+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
+enclosed array is unspecified.
+
+examples:
+@example
+(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))>
+@end example")
#define FUNC_NAME s_scm_enclose_array
{
SCM axv, ra, res, ra_inr;
GUILE_PROC(scm_array_in_bounds_p, "array-in-bounds?", 0, 0, 1,
(SCM args),
-"")
+"Returns @code{#t} if its arguments would be acceptable to array-ref.")
#define FUNC_NAME s_scm_array_in_bounds_p
{
SCM v, ind = SCM_EOL;
GUILE_PROC(scm_uniform_vector_ref, "uniform-vector-ref", 2, 0, 0,
(SCM v, SCM args),
-"")
+"Returns the element at the @code{(index1, index2)} element in @var{array}.")
#define FUNC_NAME s_scm_uniform_vector_ref
{
long pos;
PROC is used (and it's called from C too). */
GUILE_PROC(scm_array_set_x, "array-set!", 2, 0, 1,
(SCM v, SCM obj, SCM args),
-"")
+"Sets the element at the @code{(index1, index2)} element in @var{array} to
+@var{new-value}. The value returned by array-set! is unspecified.")
#define FUNC_NAME s_scm_array_set_x
{
long pos = 0;
wouldn't have contiguous elements. */
GUILE_PROC(scm_array_contents, "array-contents", 1, 1, 0,
(SCM ra, SCM strict),
-"")
+"@deffnx primitive 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
+@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.
+
+If the optional argument @var{strict} is provided, a shared array will
+be returned only if its elements are stored internally contiguous in
+memory.")
#define FUNC_NAME s_scm_array_contents
{
SCM sra;
GUILE_PROC(scm_uniform_array_read_x, "uniform-array-read!", 1, 3, 0,
(SCM ra, SCM port_or_fd, SCM start, SCM end),
-"")
+"@deffnx primitive uniform-vector-read! uve [port-or-fdes] [start] [end]
+Attempts to read all elements of @var{ura}, in lexicographic order, as
+binary objects from @var{port-or-fdes}.
+If an end of file is encountered during
+uniform-array-read! the objects up to that point only are put into @var{ura}
+(starting at the beginning) and the remainder of the array is
+unchanged.
+
+The optional arguments @var{start} and @var{end} allow
+a specified region of a vector (or linearized array) to be read,
+leaving the remainder of the vector unchanged.
+
+@code{uniform-array-read!} returns the number of objects read.
+@var{port-or-fdes} may be omitted, in which case it defaults to the value
+returned by @code{(current-input-port)}.")
#define FUNC_NAME s_scm_uniform_array_read_x
{
SCM cra = SCM_UNDEFINED, v = ra;
GUILE_PROC(scm_uniform_array_write, "uniform-array-write", 1, 3, 0,
(SCM v, SCM port_or_fd, SCM start, SCM end),
-"")
+"@deffnx primitive uniform-vector-write uve [port-or-fdes] [start] [end]
+Writes all elements of @var{ura} as binary objects to
+@var{port-or-fdes}.
+
+The optional arguments @var{start}
+and @var{end} allow
+a specified region of a vector (or linearized array) to be written.
+
+The number of objects actually written is returned.
+@var{port-or-fdes} may be
+omitted, in which case it defaults to the value returned by
+@code{(current-output-port)}.")
#define FUNC_NAME s_scm_uniform_array_write
{
long sz, vlen, ans;
GUILE_PROC(scm_bit_count, "bit-count", 2, 0, 0,
(SCM item, SCM seq),
-"")
+"Returns the number occurrences of @var{bool} in @var{bv}.")
#define FUNC_NAME s_scm_bit_count
{
long i;
GUILE_PROC(scm_bit_position, "bit-position", 3, 0, 0,
(SCM item, SCM v, SCM k),
-"")
+"Returns the minimum index of an occurrence of @var{bool} in @var{bv}
+which is at least @var{k}. If no @var{bool} occurs within the specified
+range @code{#f} is returned.")
#define FUNC_NAME s_scm_bit_position
{
long i, lenw, xbits, pos;
GUILE_PROC(scm_bit_set_star_x, "bit-set*!", 3, 0, 0,
(SCM v, SCM kv, SCM obj),
-"")
+"If uve is a bit-vector @var{bv} and uve must be of the same length. If
+@var{bool} is @code{#t}, uve is OR'ed into @var{bv}; If @var{bool} is @code{#f}, the
+inversion of uve is AND'ed into @var{bv}.
+
+If uve is a unsigned integer vector all the elements of uve must be
+between 0 and the @code{LENGTH} of @var{bv}. The bits of @var{bv}
+corresponding to the indexes in uve are set to @var{bool}.
+
+The return value is unspecified.")
#define FUNC_NAME s_scm_bit_set_star_x
{
register long i, k, vlen;
GUILE_PROC(scm_bit_count_star, "bit-count*", 3, 0, 0,
(SCM v, SCM kv, SCM obj),
-"")
+"Returns
+@example
+(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
+@end example
+@var{bv} is not modified.")
#define FUNC_NAME s_scm_bit_count_star
{
register long i, vlen, count = 0;
GUILE_PROC(scm_bit_invert_x, "bit-invert!", 1, 0, 0,
(SCM v),
-"")
+"Modifies @var{bv} by replacing each element with its negation.")
#define FUNC_NAME s_scm_bit_invert_x
{
register long k;
GUILE_PROC(scm_array_to_list, "array->list", 1, 0, 0,
(SCM v),
-"")
+"Returns a list consisting of all the elements, in order, of @var{array}.")
#define FUNC_NAME s_scm_array_to_list
{
SCM res = SCM_EOL;
GUILE_PROC(scm_list_to_uniform_array, "list->uniform-array", 3, 0, 0,
(SCM ndim, SCM prot, SCM lst),
-"")
+"@deffnx procedure list->uniform-vector prot lst
+Returns a uniform array of the type indicated by prototype @var{prot}
+with elements the same as those of @var{lst}. Elements must be of the
+appropriate type, no coercions are done.")
#define FUNC_NAME s_scm_list_to_uniform_array
{
SCM shp = SCM_EOL;
GUILE_PROC(scm_array_prototype, "array-prototype", 1, 0, 0,
(SCM ra),
-"")
+"Returns an object that would produce an array of the same type as
+@var{array}, if used as the @var{prototype} for
+@code{make-uniform-array}.")
#define FUNC_NAME s_scm_array_prototype
{
int enclosed = 0;
HCoop / bpt / guile.git / blobdiff