From: Greg J. Badros Date: Thu, 27 Jan 2000 18:15:56 +0000 (+0000) Subject: * vectors.c, symbols.c, strorder.c: Documentation cut and pasted X-Git-Url: http://git.hcoop.net/bpt/guile.git/commitdiff_plain/5ffe9968de9362e2be93e5c079f2f933948dda3e * vectors.c, symbols.c, strorder.c: Documentation cut and pasted from Gregg Reynolds. Thanks Gregg! --- diff --git a/libguile/strorder.c b/libguile/strorder.c index 22715a3e4..43c144312 100644 --- a/libguile/strorder.c +++ b/libguile/strorder.c @@ -53,7 +53,12 @@ SCM_DEFINE1 (scm_string_equal_p, "string=?", scm_tc7_rpsubr, (SCM s1, SCM s2), -"") + "Lexicographic equality predicate; \n" + "Returns @t{#t} if the two strings are the same length and contain the same\n" + "characters in the same positions, otherwise returns @t{#f}. (r5rs)\n\n" + "@samp{String-ci=?} treats\n" + "upper and lower case letters as though they were the same character, but\n" + "@samp{string=?} treats upper and lower case as distinct characters.") #define FUNC_NAME s_scm_string_equal_p { register scm_sizet i; @@ -77,7 +82,9 @@ SCM_DEFINE1 (scm_string_equal_p, "string=?", scm_tc7_rpsubr, SCM_DEFINE1 (scm_string_ci_equal_p, "string-ci=?", scm_tc7_rpsubr, (SCM s1, SCM s2), -"") + "Case-insensitive string equality predicate; returns @t{#t} if\n" + "the two strings are the same length and their component characters\n" + "match (ignoring case) at each position; otherwise returns @t{#f}. (r5rs)") #define FUNC_NAME s_scm_string_ci_equal_p { register scm_sizet i; @@ -101,7 +108,8 @@ SCM_DEFINE1 (scm_string_ci_equal_p, "string-ci=?", scm_tc7_rpsubr, SCM_DEFINE1 (scm_string_less_p, "string?", scm_tc7_rpsubr, (SCM s1, SCM s2), -"") + "Lexicographic ordering predicate; returns @t{#t} if @var{s1}\n" + "is lexicographically greater than @var{s2}. (r5rs)") #define FUNC_NAME s_scm_string_gr_p { return scm_string_less_p (s2, s1); @@ -151,7 +161,8 @@ SCM_DEFINE1 (scm_string_gr_p, "string>?", scm_tc7_rpsubr, SCM_DEFINE1 (scm_string_geq_p, "string>=?", scm_tc7_rpsubr, (SCM s1, SCM s2), -"") + "Lexicographic ordering predicate; returns @t{#t} if @var{s1}\n" + "is lexicographically greater than or equal to @var{s2}. (r5rs)") #define FUNC_NAME s_scm_string_geq_p { return SCM_BOOL_NOT (scm_string_less_p (s1, s2)); @@ -160,7 +171,9 @@ SCM_DEFINE1 (scm_string_geq_p, "string>=?", scm_tc7_rpsubr, SCM_DEFINE1 (scm_string_ci_less_p, "string-ci?", scm_tc7_rpsubr, (SCM s1, SCM s2), -"") + "Case insensitive lexicographic ordering predicate; \n" + "returns @t{#t} if @var{s1} is lexicographically greater than\n" + "@var{s2} regardless of case. (r5rs)") #define FUNC_NAME s_scm_string_ci_gr_p { return scm_string_ci_less_p (s2, s1); @@ -202,7 +219,9 @@ SCM_DEFINE1 (scm_string_ci_gr_p, "string-ci>?", scm_tc7_rpsubr, SCM_DEFINE1 (scm_string_ci_geq_p, "string-ci>=?", scm_tc7_rpsubr, (SCM s1, SCM s2), -"") + "Case insensitive lexicographic ordering predicate; \n" + "returns @t{#t} if @var{s1} is lexicographically greater than\n" + "or equal to @var{s2} regardless of case. (r5rs)") #define FUNC_NAME s_scm_string_ci_geq_p { return SCM_BOOL_NOT (scm_string_ci_less_p (s1, s2)); diff --git a/libguile/symbols.c b/libguile/symbols.c index 173a5dc0e..30779bd97 100644 --- a/libguile/symbols.c +++ b/libguile/symbols.c @@ -420,18 +420,39 @@ scm_symbol_value0 (const char *name) } SCM_DEFINE (scm_symbol_p, "symbol?", 1, 0, 0, - (SCM x), -"") + (SCM obj), + "Returns @t{#t} if @var{obj} is a symbol, otherwise returns @t{#f}. (r5rs)") #define FUNC_NAME s_scm_symbol_p { - if SCM_IMP(x) return SCM_BOOL_F; - return SCM_BOOL(SCM_SYMBOLP(x)); + if SCM_IMP(obj) return SCM_BOOL_F; + return SCM_BOOL(SCM_SYMBOLP(obj)); } #undef FUNC_NAME SCM_DEFINE (scm_symbol_to_string, "symbol->string", 1, 0, 0, (SCM s), -"") + "Returns the name of @var{symbol} as a string. If the symbol was part of\n" + "an object returned as the value of a literal expression\n" + "(section @pxref{Literal expressions}) or by a call to the @samp{read} procedure,\n" + "and its name contains alphabetic characters, then the string returned\n" + "will contain characters in the implementation's preferred standard\n" + "case---some implementations will prefer upper case, others lower case.\n" + "If the symbol was returned by @samp{string->symbol}, the case of\n" + "characters in the string returned will be the same as the case in the\n" + "string that was passed to @samp{string->symbol}. It is an error\n" + "to apply mutation procedures like @code{string-set!} to strings returned\n" + "by this procedure. (r5rs)\n\n" + "The following examples assume that the implementation's standard case is\n" + "lower case:\n\n" + "@format\n" + "@t{(symbol->string 'flying-fish) \n" + " ==> \"flying-fish\"\n" + "(symbol->string 'Martin) ==> \"martin\"\n" + "(symbol->string\n" + " (string->symbol "Malvina")) \n" + " ==> \"Malvina\"\n" + "}\n" + "@end format") #define FUNC_NAME s_scm_symbol_to_string { SCM_VALIDATE_SYMBOL (1,s); @@ -442,7 +463,31 @@ SCM_DEFINE (scm_symbol_to_string, "symbol->string", 1, 0, 0, SCM_DEFINE (scm_string_to_symbol, "string->symbol", 1, 0, 0, (SCM s), -"") + "Returns the symbol whose name is @var{string}. This procedure can\n" + "create symbols with names containing special characters or letters in\n" + "the non-standard case, but it is usually a bad idea to create such\n" + "symbols because in some implementations of Scheme they cannot be read as\n" + "themselves. See @samp{symbol->string}.\n\n" + "The following examples assume that the implementation's standard case is\n" + "lower case:\n\n" +"@format\n" +"@t{(eq? 'mISSISSIppi 'mississippi) \n" +" ==> #t\n" +"(string->symbol \"mISSISSIppi\") \n" +" ==>\n" +" @r{}the symbol with name \"mISSISSIppi\"\n" +"(eq? 'bitBlt (string->symbol \"bitBlt\")) \n" +" ==> #f\n" +"(eq? 'JollyWog\n" +" (string->symbol\n" +" (symbol->string 'JollyWog))) \n" +" ==> #t\n" +"(string=? \"K. Harper, M.D.\"\n" +" (symbol->string\n" +" (string->symbol \"K. Harper, M.D.\"))) \n" +" ==> #t\n" +"}\n" + "@end format") #define FUNC_NAME s_scm_string_to_symbol { SCM vcell; @@ -776,7 +821,7 @@ copy_and_prune_obarray (SCM from, SCM to) SCM_DEFINE (scm_builtin_bindings, "builtin-bindings", 0, 0, 0, - (), + (), "Create and return a copy of the global symbol table, removing all\n" "unbound symbols.") #define FUNC_NAME s_scm_builtin_bindings @@ -790,7 +835,7 @@ SCM_DEFINE (scm_builtin_bindings, "builtin-bindings", 0, 0, 0, SCM_DEFINE (scm_builtin_weak_bindings, "builtin-weak-bindings", 0, 0, 0, - (), + (), "") #define FUNC_NAME s_scm_builtin_weak_bindings { diff --git a/libguile/vectors.c b/libguile/vectors.c index 7417ec8b6..eb7b20b00 100644 --- a/libguile/vectors.c +++ b/libguile/vectors.c @@ -123,18 +123,18 @@ scm_vector_set_length_x (SCM vect, SCM len) } SCM_DEFINE (scm_vector_p, "vector?", 1, 0, 0, - (SCM x), -"") + (SCM obj), + "Returns @t{#t} if @var{obj} is a vector, otherwise returns @t{#f}. (r5rs)") #define FUNC_NAME s_scm_vector_p { - if (SCM_IMP (x)) + if (SCM_IMP (obj)) return SCM_BOOL_F; - return SCM_BOOL (SCM_VECTORP (x)); + return SCM_BOOL (SCM_VECTORP (obj)); } #undef FUNC_NAME SCM_GPROC (s_vector_length, "vector-length", 1, 0, 0, scm_vector_length, g_vector_length); - +/* Returns the number of elements in @var{vector} as an exact integer. (r5rs) */ SCM scm_vector_length (SCM v) { @@ -144,10 +144,24 @@ scm_vector_length (SCM v) } SCM_REGISTER_PROC (s_list_to_vector, "list->vector", 1, 0, 0, scm_vector); - +/* + "@samp{List->vector} returns a newly\n" + "created vector initialized to the elements of the list @var{list}.\n\n" + "@format\n" + "@t{(vector->list '#(dah dah didah))\n" + "=> (dah dah didah)\n" + "list->vector '(dididit dah))\n" + "=> #(dididit dah)\n" + "}\n" + "@end format") +*/ SCM_DEFINE (scm_vector, "vector", 0, 0, 1, (SCM l), -"") + "Returns a newly allocated vector whose elements contain the given\n" + "arguments. Analogous to @samp{list}. (r5rs)\n\n" + "@format\n" + "@t{(vector 'a 'b 'c) ==> #(a b c) }\n" + "@end format") #define FUNC_NAME s_scm_vector { SCM res; @@ -164,6 +178,24 @@ SCM_DEFINE (scm_vector, "vector", 0, 0, 1, SCM_GPROC (s_vector_ref, "vector-ref", 2, 0, 0, scm_vector_ref, g_vector_ref); +/* + "@var{k} must be a valid index of @var{vector}.\n" + "@samp{Vector-ref} returns the contents of element @var{k} of\n" + "@var{vector}.\n\n" + "@format\n" + "@t{(vector-ref '#(1 1 2 3 5 8 13 21)\n" + " 5)\n" + " ==> 8\n" + "(vector-ref '#(1 1 2 3 5 8 13 21)\n" + " (let ((i (round (* 2 (acos -1)))))\n" + " (if (inexact? i)\n" + " (inexact->exact i)\n" + " i))) \n" + " ==> 13\n" + "}\n" + "@end format" +*/ + SCM scm_vector_ref (SCM v, SCM k) { @@ -178,6 +210,25 @@ scm_vector_ref (SCM v, SCM k) SCM_GPROC (s_vector_set_x, "vector-set!", 3, 0, 0, scm_vector_set_x, g_vector_set_x); +/* (r5rs) +@var{k} must be a valid index of @var{vector}. +@samp{Vector-set!} stores @var{obj} in element @var{k} of @var{vector}. +The value returned by @samp{vector-set!} is unspecified. +@c + + +@format +@t{(let ((vec (vector 0 '(2 2 2 2) "Anna"))) + (vector-set! vec 1 '("Sue" "Sue")) + vec) + ==> #(0 ("Sue" "Sue") "Anna") + +(vector-set! '#(0 1 2) 1 "doe") + ==> @emph{error} ; constant vector +} +@end format +*/ + SCM scm_vector_set_x (SCM v, SCM k, SCM obj) { @@ -196,7 +247,9 @@ scm_vector_set_x (SCM v, SCM k, SCM obj) SCM_DEFINE (scm_make_vector, "make-vector", 1, 1, 0, (SCM k, SCM fill), -"") + "Returns a newly allocated vector of @var{k} elements. If a second\n" + "argument is given, then each element is initialized to @var{fill}.\n" + "Otherwise the initial contents of each element is unspecified. (r5rs)") #define FUNC_NAME s_scm_make_vector { SCM v; @@ -223,7 +276,15 @@ SCM_DEFINE (scm_make_vector, "make-vector", 1, 1, 0, SCM_DEFINE (scm_vector_to_list, "vector->list", 1, 0, 0, (SCM v), -"") + "@samp{Vector->list} returns a newly allocated list of the objects contained\n" + "in the elements of @var{vector}. (r5rs)\n\n" + "@format\n" + "@t{(vector->list '#(dah dah didah))\n" + "=> (dah dah didah)\n" + "list->vector '(dididit dah))\n" + "=> #(dididit dah)\n" + "}\n" + "@end format") #define FUNC_NAME s_scm_vector_to_list { SCM res = SCM_EOL; @@ -239,7 +300,8 @@ SCM_DEFINE (scm_vector_to_list, "vector->list", 1, 0, 0, SCM_DEFINE (scm_vector_fill_x, "vector-fill!", 2, 0, 0, (SCM v, SCM fill_x), -"") + "Stores @var{fill} in every element of @var{vector}.\n" + "The value returned by @samp{vector-fill!} is unspecified. (r5rs)") #define FUNC_NAME s_scm_vector_fill_x { register long i; @@ -253,7 +315,6 @@ SCM_DEFINE (scm_vector_fill_x, "vector-fill!", 2, 0, 0, #undef FUNC_NAME - SCM scm_vector_equal_p(SCM x, SCM y) {