From b380b88547226544d5a2b7d09379c79fbe300e10 Mon Sep 17 00:00:00 2001 From: Mikael Djurfeldt Date: Tue, 18 Jan 2000 11:24:03 +0000 Subject: * alist.c, chars.c, debug.c, dynl.c, dynwind.c, error.c, eval.c, evalext.c, filesys.c, gc.c, hash.c, hashtab.c, ioext.c, keywords.c, list.c, load.c, macros.c, net_db.c, numbers.c, objprop.c, ports.c, posix.c, print.c, procprop.c, procs.c, ramap.c, regex-posix.c, root.c, scmsigs.c, simpos.c, socket.c, stacks.c, stime.c, strings.c, strop.c, strports.c, struct.c, symbols.c, throw.c, unif.c, vectors.c, version.c, vports.c, weaks.c: Converted docstrings to ANSI C format. --- libguile/unif.c | 269 +++++++++++++++++++++++++++----------------------------- 1 file changed, 128 insertions(+), 141 deletions(-) (limited to 'libguile/unif.c') diff --git a/libguile/unif.c b/libguile/unif.c index 85325d408..9948bed28 100644 --- a/libguile/unif.c +++ b/libguile/unif.c @@ -239,7 +239,7 @@ scm_make_uve (long k, SCM prot) SCM_DEFINE (scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0, (SCM v), -"Returns the number of elements in @var{uve}.") + "Returns the number of elements in @var{uve}.") #define FUNC_NAME s_scm_uniform_vector_length { SCM_ASRTGO (SCM_NIMP (v), badarg1); @@ -269,10 +269,9 @@ SCM_DEFINE (scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0, SCM_DEFINE (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.") + "Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not.\n\n" + "The @var{prototype} argument is used with uniform arrays and is described\n" + "elsewhere.") #define FUNC_NAME s_scm_array_p { int nprot; @@ -337,8 +336,8 @@ loop: SCM_DEFINE (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.") + "Returns the number of dimensions of @var{obj}. If @var{obj} is not an\n" + "array, @code{0} is returned.") #define FUNC_NAME s_scm_array_rank { if (SCM_IMP (ra)) @@ -372,11 +371,11 @@ array, @code{0} is returned.") SCM_DEFINE (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") + "@code{Array-dimensions} is similar to @code{array-shape} but replaces\n" + "elements with a @code{0} minimum with one greater than the maximum. So:\n" + "@example\n" + "(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)\n" + "@end example") #define FUNC_NAME s_scm_array_dimensions { SCM res = SCM_EOL; @@ -510,11 +509,11 @@ scm_shap2ra (SCM args, const char *what) SCM_DEFINE (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.") + "@deffnx primitive make-uniform-vector length prototype [fill]\n" + "Creates and returns a uniform array or vector of type corresponding to\n" + "@var{prototype} with dimensions @var{dims} or length @var{length}. If\n" + "@var{fill} is supplied, it's used to fill the array, otherwise \n" + "@var{prototype} is used.") #define FUNC_NAME s_scm_dimensions_to_uniform_array { scm_sizet k, vlen = 1; @@ -621,21 +620,21 @@ scm_ra_set_contp (SCM ra) SCM_DEFINE (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") + "@code{make-shared-array} can be used to create shared subarrays of other\n" + "arrays. The @var{mapper} is a function that translates coordinates in\n" + "the new array into coordinates in the old array. A @var{mapper} must be\n" + "linear, and its range must stay within the bounds of the old array, but\n" + "it can be otherwise arbitrary. A simple example:\n" + "@example\n" + "(define fred (make-array #f 8 8))\n" + "(define freds-diagonal\n" + " (make-shared-array fred (lambda (i) (list i i)) 8))\n" + "(array-set! freds-diagonal 'foo 3)\n" + "(array-ref fred 3 3) @result{} foo\n" + "(define freds-center\n" + " (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))\n" + "(array-ref freds-center 0 0) @result{} foo\n" + "@end example") #define FUNC_NAME s_scm_make_shared_array { SCM ra; @@ -747,25 +746,23 @@ it can be otherwise arbitrary. A simple example: /* args are RA . DIMS */ SCM_DEFINE (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") + "Returns an array sharing contents with @var{array}, but with dimensions\n" + "arranged in a different order. There must be one @var{dim} argument for\n" + "each dimension of @var{array}. @var{dim0}, @var{dim1}, @dots{} should\n" + "be integers between 0 and the rank of the array to be returned. Each\n" + "integer in that range must appear at least once in the argument list.\n\n" + "The values of @var{dim0}, @var{dim1}, @dots{} correspond to dimensions\n" + "in the array to be returned, their positions in the argument list to\n" + "dimensions of @var{array}. Several @var{dim}s may have the same value,\n" + "in which case the returned array will have smaller rank than\n" + "@var{array}.\n\n" + "examples:\n" + "@example\n" + "(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))\n" + "(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)\n" + "(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}\n" + " #2((a 4) (b 5) (c 6))\n" + "@end example") #define FUNC_NAME s_scm_transpose_array { SCM ra, res, vargs, *ve = &vargs; @@ -859,27 +856,24 @@ examples: /* args are RA . AXES */ SCM_DEFINE (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") + "@var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than\n" + "the rank of @var{array}. @var{enclose-array} returns an array\n" + "resembling an array of shared arrays. The dimensions of each shared\n" + "array are the same as the @var{dim}th dimensions of the original array,\n" + "the dimensions of the outer array are the same as those of the original\n" + "array that did not match a @var{dim}.\n\n" + "An enclosed array is not a general Scheme array. Its elements may not\n" + "be set using @code{array-set!}. Two references to the same element of\n" + "an enclosed array will be @code{equal?} but will not in general be\n" + "@code{eq?}. The value returned by @var{array-prototype} when given an\n" + "enclosed array is unspecified.\n\n" + "examples:\n" + "@example\n" + "(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}\n" + " #\n\n" + "(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}\n" + " #\n" + "@end example") #define FUNC_NAME s_scm_enclose_array { SCM axv, ra, res, ra_inr; @@ -962,7 +956,7 @@ examples: SCM_DEFINE (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.") + "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; @@ -1045,7 +1039,7 @@ SCM_REGISTER_PROC(s_array_ref, "array-ref", 1, 0, 1, scm_uniform_vector_ref); SCM_DEFINE (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}.") + "Returns the element at the @code{(index1, index2)} element in @var{array}.") #define FUNC_NAME s_scm_uniform_vector_ref { long pos; @@ -1239,8 +1233,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). */ SCM_DEFINE (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.") + "Sets the element at the @code{(index1, index2)} element in @var{array} to\n" + "@var{new-value}. The value returned by array-set! is unspecified.") #define FUNC_NAME s_scm_array_set_x { long pos = 0; @@ -1345,17 +1339,16 @@ SCM_DEFINE (scm_array_set_x, "array-set!", 2, 0, 1, wouldn't have contiguous elements. */ SCM_DEFINE (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.") + "@deffnx primitive array-contents array strict\n" + "If @var{array} may be @dfn{unrolled} into a one dimensional shared array\n" + "without changing their order (last subscript changing fastest), then\n" + "@code{array-contents} returns that shared array, otherwise it returns\n" + "@code{#f}. All arrays made by @var{make-array} and\n" + "@var{make-uniform-array} may be unrolled, some arrays made by\n" + "@var{make-shared-array} may not be.\n\n" + "If the optional argument @var{strict} is provided, a shared array will\n" + "be returned only if its elements are stored internally contiguous in\n" + "memory.") #define FUNC_NAME s_scm_array_contents { SCM sra; @@ -1451,21 +1444,19 @@ scm_ra2contig (SCM ra, int copy) SCM_DEFINE (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)}.") + "@deffnx primitive uniform-vector-read! uve [port-or-fdes] [start] [end]\n" + "Attempts to read all elements of @var{ura}, in lexicographic order, as\n" + "binary objects from @var{port-or-fdes}.\n" + "If an end of file is encountered during\n" + "uniform-array-read! the objects up to that point only are put into @var{ura}\n" + "(starting at the beginning) and the remainder of the array is\n" + "unchanged.\n\n" + "The optional arguments @var{start} and @var{end} allow\n" + "a specified region of a vector (or linearized array) to be read,\n" + "leaving the remainder of the vector unchanged.\n\n" + "@code{uniform-array-read!} returns the number of objects read.\n" + "@var{port-or-fdes} may be omitted, in which case it defaults to the value\n" + "returned by @code{(current-input-port)}.") #define FUNC_NAME s_scm_uniform_array_read_x { SCM cra = SCM_UNDEFINED, v = ra; @@ -1609,18 +1600,16 @@ loop: SCM_DEFINE (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)}.") + "@deffnx primitive uniform-vector-write uve [port-or-fdes] [start] [end]\n" + "Writes all elements of @var{ura} as binary objects to\n" + "@var{port-or-fdes}.\n\n" + "The optional arguments @var{start}\n" + "and @var{end} allow\n" + "a specified region of a vector (or linearized array) to be written.\n\n" + "The number of objects actually written is returned. \n" + "@var{port-or-fdes} may be\n" + "omitted, in which case it defaults to the value returned by\n" + "@code{(current-output-port)}.") #define FUNC_NAME s_scm_uniform_array_write { long sz, vlen, ans; @@ -1734,7 +1723,7 @@ static char cnt_tab[16] = SCM_DEFINE (scm_bit_count, "bit-count", 2, 0, 0, (SCM item, SCM seq), -"Returns the number occurrences of @var{bool} in @var{bv}.") + "Returns the number occurrences of @var{bool} in @var{bv}.") #define FUNC_NAME s_scm_bit_count { long i; @@ -1769,9 +1758,9 @@ SCM_DEFINE (scm_bit_count, "bit-count", 2, 0, 0, SCM_DEFINE (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.") + "Returns the minimum index of an occurrence of @var{bool} in @var{bv}\n" + "which is at least @var{k}. If no @var{bool} occurs within the specified\n" + "range @code{#f} is returned.") #define FUNC_NAME s_scm_bit_position { long i, lenw, xbits, pos; @@ -1837,15 +1826,13 @@ range @code{#f} is returned.") SCM_DEFINE (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.") + "If uve is a bit-vector @var{bv} and uve must be of the same length. If\n" + "@var{bool} is @code{#t}, uve is OR'ed into @var{bv}; If @var{bool} is @code{#f}, the\n" + "inversion of uve is AND'ed into @var{bv}.\n\n" + "If uve is a unsigned integer vector all the elements of uve must be\n" + "between 0 and the @code{LENGTH} of @var{bv}. The bits of @var{bv}\n" + "corresponding to the indexes in uve are set to @var{bool}.\n\n" + "The return value is unspecified.") #define FUNC_NAME s_scm_bit_set_star_x { register long i, k, vlen; @@ -1899,11 +1886,11 @@ The return value is unspecified.") SCM_DEFINE (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.") + "Returns\n" + "@example\n" + "(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).\n" + "@end example\n" + "@var{bv} is not modified.") #define FUNC_NAME s_scm_bit_count_star { register long i, vlen, count = 0; @@ -1967,7 +1954,7 @@ SCM_DEFINE (scm_bit_count_star, "bit-count*", 3, 0, 0, SCM_DEFINE (scm_bit_invert_x, "bit-invert!", 1, 0, 0, (SCM v), -"Modifies @var{bv} by replacing each element with its negation.") + "Modifies @var{bv} by replacing each element with its negation.") #define FUNC_NAME s_scm_bit_invert_x { register long k; @@ -2050,7 +2037,7 @@ ra2l (SCM ra,scm_sizet base,scm_sizet k) SCM_DEFINE (scm_array_to_list, "array->list", 1, 0, 0, (SCM v), -"Returns a list consisting of all the elements, in order, of @var{array}.") + "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; @@ -2157,10 +2144,10 @@ static int l2ra(SCM lst, SCM ra, scm_sizet base, scm_sizet k); SCM_DEFINE (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.") + "@deffnx procedure list->uniform-vector prot lst\n" + "Returns a uniform array of the type indicated by prototype @var{prot}\n" + "with elements the same as those of @var{lst}. Elements must be of the\n" + "appropriate type, no coercions are done.") #define FUNC_NAME s_scm_list_to_uniform_array { SCM shp = SCM_EOL; @@ -2512,9 +2499,9 @@ tail: SCM_DEFINE (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}.") + "Returns an object that would produce an array of the same type as\n" + "@var{array}, if used as the @var{prototype} for\n" + "@code{make-uniform-array}.") #define FUNC_NAME s_scm_array_prototype { int enclosed = 0; -- cgit v1.2.1