X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/75948d1b314685312f8d62315c4bec6bd003fca4..4079f87ed21341a8654ecaa29ac3e6a2344d9252:/libguile/unif.c diff --git a/libguile/unif.c b/libguile/unif.c index 401b461f3..b595e6297 100644 --- a/libguile/unif.c +++ b/libguile/unif.c @@ -239,7 +239,7 @@ scm_make_uve (long k, SCM prot) 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); @@ -269,7 +269,10 @@ GUILE_PROC(scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0, 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; @@ -336,7 +339,8 @@ loop: 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)) @@ -370,7 +374,11 @@ GUILE_PROC(scm_array_rank, "array-rank", 1, 0, 0, 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; @@ -504,7 +512,11 @@ scm_shap2ra (SCM args, const char *what) 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; @@ -611,7 +623,21 @@ scm_ra_set_contp (SCM ra) 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; @@ -723,7 +749,25 @@ GUILE_PROC(scm_make_shared_array, "make-shared-array", 2, 0, 1, /* 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; @@ -817,7 +861,27 @@ GUILE_PROC(scm_transpose_array, "transpose-array", 0, 0, 1, /* 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{} + # + +(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{} + # +@end example") #define FUNC_NAME s_scm_enclose_array { SCM axv, ra, res, ra_inr; @@ -900,7 +964,7 @@ GUILE_PROC(scm_enclose_array, "enclose-array", 0, 0, 1, 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; @@ -983,7 +1047,7 @@ SCM_REGISTER_PROC(s_array_ref, "array-ref", 1, 0, 1, scm_uniform_vector_ref); 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; @@ -1177,7 +1241,8 @@ SCM_REGISTER_PROC(s_uniform_array_set1_x, "uniform-array-set1!", 3, 0, 0, scm_ar 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; @@ -1282,7 +1347,17 @@ GUILE_PROC(scm_array_set_x, "array-set!", 2, 0, 1, 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; @@ -1378,7 +1453,21 @@ scm_ra2contig (SCM ra, int copy) 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; @@ -1524,7 +1613,18 @@ loop: 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; @@ -1638,7 +1738,7 @@ static char cnt_tab[16] = 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; @@ -1673,7 +1773,9 @@ GUILE_PROC(scm_bit_count, "bit-count", 2, 0, 0, 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; @@ -1739,7 +1841,15 @@ GUILE_PROC(scm_bit_position, "bit-position", 3, 0, 0, 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; @@ -1793,7 +1903,11 @@ GUILE_PROC(scm_bit_set_star_x, "bit-set*!", 3, 0, 0, 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; @@ -1857,7 +1971,7 @@ GUILE_PROC(scm_bit_count_star, "bit-count*", 3, 0, 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; @@ -1940,7 +2054,7 @@ ra2l (SCM ra,scm_sizet base,scm_sizet 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; @@ -2047,7 +2161,10 @@ static int l2ra(SCM lst, SCM ra, scm_sizet base, scm_sizet k); 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; @@ -2399,7 +2516,9 @@ tail: 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;