diff --git a/doc/ChangeLog b/doc/ChangeLog index 7530a8d5b..2cf27d9ea 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,5 +1,12 @@ 2001-04-09 Neil Jerram + * deprecated.texi (Shared And Read Only Strings): New section for + deprecated string stuff. I've also updated the text a bit to + reflect current usage of "read only" strings. + + * scheme-data.texi (Shared Substrings, Read Only Strings): Moved + to deprecated.texi. + * deprecated.texi, posix.texi, scheme-binding.texi, scheme-control.texi, scheme-data.texi, scheme-debug.texi, scheme-evaluation.texi, scheme-io.texi, scheme-memory.texi, diff --git a/doc/deprecated.texi b/doc/deprecated.texi index e7f5277db..0b2fdd30a 100644 --- a/doc/deprecated.texi +++ b/doc/deprecated.texi @@ -1,7 +1,146 @@ @node Deprecated @chapter Deprecated -@deffn primitive tag x -Return an integer corresponding to the type of X. Deprecated. +@menu +* Shared And Read Only Strings:: +* Tags:: +@end menu + + +@node Shared And Read Only Strings +@section Shared And Read Only Strings + +The procedures described in this section are deprecated because explicit +shared substrings are planned to disappear from Guile. + +Instead, all strings will be implemented using sharing internally, +combined with a copy-on-write strategy. Once internal string sharing +and copy-on-write have been implemented, it will be unnecessary to +preserve the concept of read only strings. + +@menu +* Shared Substrings:: Strings which share memory with each other. +* Read Only Strings:: Treating certain non-strings as strings. +@end menu + + +@node Shared Substrings +@subsection Shared Substrings + +Whenever you extract a substring using @code{substring}, the Scheme +interpreter allocates a new string and copies data from the old string. +This is expensive, but @code{substring} is so convenient for +manipulating text that programmers use it often. + +Guile Scheme provides the concept of the @dfn{shared substring} to +improve performance of many substring-related operations. A shared +substring is an object that mostly behaves just like an ordinary +substring, except that it actually shares storage space with its parent +string. + +@deffn primitive make-shared-substring str [start [end]] +Return a shared substring of @var{str}. The arguments are the +same as for the @code{substring} function: the shared substring +returned includes all of the text from @var{str} between +indexes @var{start} (inclusive) and @var{end} (exclusive). If +@var{end} is omitted, it defaults to the end of @var{str}. The +shared substring returned by @code{make-shared-substring} +occupies the same storage space as @var{str}. @end deffn +Example: + +@example +(define foo "the quick brown fox") +(define bar (make-shared-substring some-string 4 9)) + +foo => "t h e q u i c k b r o w n f o x" +bar =========> |---------| +@end example + +The shared substring @var{bar} is not given its own storage space. +Instead, the Guile interpreter notes internally that @var{bar} points to +a portion of the memory allocated to @var{foo}. However, @var{bar} +behaves like an ordinary string in most respects: it may be used with +string primitives like @code{string-length}, @code{string-ref}, +@code{string=?}. Guile makes the necessary translation between indices +of @var{bar} and indices of @var{foo} automatically. + +@example +(string-length? bar) @result{} 5 ; bar only extends from indices 4 to 9 +(string-ref bar 3) @result{} #\c ; same as (string-ref foo 7) +(make-shared-substring bar 2) + @result{} "ick" ; can even make a shared substring! +@end example + +Because creating a shared substring does not require allocating new +storage from the heap, it is a very fast operation. However, because it +shares memory with its parent string, a change to the contents of the +parent string will implicitly change the contents of its shared +substrings. + +@example +(string-set! foo 7 #\r) +bar @result{} "quirk" +@end example + +Guile considers shared substrings to be immutable. This is because +programmers might not always be aware that a given string is really a +shared substring, and might innocently try to mutate it without +realizing that the change would affect its parent string. (We are +currently considering a "copy-on-write" strategy that would permit +modifying shared substrings without affecting the parent string.) + +In general, shared substrings are useful in circumstances where it is +important to divide a string into smaller portions, but you do not +expect to change the contents of any of the strings involved. + + +@node Read Only Strings +@subsection Read Only Strings + +In previous versions of Guile, there was the idea that some string-based +primitives such as @code{string-append} could equally accept symbols as +arguments. For example, one could write + +@lisp +(string-append '/home/ 'vigilia) +@end lisp + +@noindent +and get @code{"/home/vigilia"} as the result. The term @dfn{read only +string} was adopted to describe the argument type expected by such +primitives. + +This idea has now been removed. The predicate @code{read-only-string?} +still exists, but deprecated, and is equivalent to + +@lisp +(lambda (x) (or (string? x) (symbol? x))) +@end lisp + +@noindent +But no Guile primitives now use @code{read-only-string?} to validate +their arguments. + +String-based primitives such as @code{string-append} +now require strings: + +@lisp +(string-append '/home/ 'vigilia) +@result{} +ERROR: Wrong type argument (expecting STRINGP): /home/ +@end lisp + +@deffn primitive read-only-string? obj +Return @code{#t} if @var{obj} is either a string or a symbol, +otherwise return @code{#f}. +@end deffn + + +@node Tags +@section Tags + +@deffn primitive tag x +Return an integer corresponding to the type of @var{x}. Deprecated. +@end deffn diff --git a/doc/maint/guile.texi b/doc/maint/guile.texi index 823e84f41..d0f54e487 100644 --- a/doc/maint/guile.texi +++ b/doc/maint/guile.texi @@ -169,38 +169,38 @@ add it to the system's list of active async objects. @end deffn async-mark -@c snarfed from async.c:317 +@c snarfed from async.c:311 @deffn primitive async-mark a Mark the async @var{a} for future execution. @end deffn system-async-mark -@c snarfed from async.c:333 +@c snarfed from async.c:327 @deffn primitive system-async-mark a Mark the async @var{a} for future execution. @end deffn run-asyncs -@c snarfed from async.c:353 +@c snarfed from async.c:347 @deffn primitive run-asyncs list_of_a Execute all thunks from the asyncs of the list @var{list_of_a}. @end deffn noop -@c snarfed from async.c:387 +@c snarfed from async.c:381 @deffn primitive noop . args Do nothing. When called without arguments, return @code{#f}, otherwise return the first argument. @end deffn unmask-signals -@c snarfed from async.c:439 +@c snarfed from async.c:433 @deffn primitive unmask-signals Unmask signals. The returned value is not specified. @end deffn mask-signals -@c snarfed from async.c:450 +@c snarfed from async.c:444 @deffn primitive mask-signals Mask signals. The returned value is not specified. @end deffn @@ -226,7 +226,7 @@ output. @end deffn display-backtrace -@c snarfed from backtrace.c:617 +@c snarfed from backtrace.c:619 @deffn primitive display-backtrace stack port [first [depth]] Display a backtrace to the output port @var{port}. @var{stack} is the stack to take the backtrace from, @var{first} specifies @@ -236,7 +236,7 @@ which means that default values will be used. @end deffn backtrace -@c snarfed from backtrace.c:640 +@c snarfed from backtrace.c:642 @deffn primitive backtrace Display a backtrace of the stack saved by the last error to the current output port. @@ -457,7 +457,7 @@ is implicit). @end deffn debug-object? -@c snarfed from debug.c:576 +@c snarfed from debug.c:575 @deffn primitive debug-object? obj Return @code{#t} if @var{obj} is a debug object. @end deffn @@ -483,7 +483,7 @@ only by module bookkeeping operations. @end deffn dynamic-link -@c snarfed from dynl.c:356 +@c snarfed from dynl.c:357 @deffn primitive dynamic-link filename Open the dynamic library called @var{filename}. A library handle representing the opened library is returned; this handle @@ -492,14 +492,14 @@ functions. @end deffn dynamic-object? -@c snarfed from dynl.c:372 +@c snarfed from dynl.c:373 @deffn primitive dynamic-object? obj Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f} otherwise. @end deffn dynamic-unlink -@c snarfed from dynl.c:388 +@c snarfed from dynl.c:386 @deffn primitive dynamic-unlink dobj Unlink the indicated object file from the application. The argument @var{dobj} must have been obtained by a call to @@ -508,7 +508,7 @@ called on @var{dobj}, its content is no longer accessible. @end deffn dynamic-func -@c snarfed from dynl.c:415 +@c snarfed from dynl.c:413 @deffn primitive dynamic-func name dobj Search the dynamic object @var{dobj} for the C function indicated by the string @var{name} and return some Scheme @@ -522,7 +522,7 @@ needed or not and will add it when necessary. @end deffn dynamic-call -@c snarfed from dynl.c:460 +@c snarfed from dynl.c:453 @deffn primitive dynamic-call func dobj Call the C function indicated by @var{func} and @var{dobj}. The function is passed no arguments and its return value is @@ -539,7 +539,7 @@ Interrupts are deferred while the C function is executing (with @end deffn dynamic-args-call -@c snarfed from dynl.c:494 +@c snarfed from dynl.c:481 @deffn primitive dynamic-args-call func dobj args Call the C function indicated by @var{func} and @var{dobj}, just like @code{dynamic-call}, but pass it some arguments and @@ -557,7 +557,7 @@ converted to a Scheme number and returned from the call to @end deffn dynamic-wind -@c snarfed from dynwind.c:115 +@c snarfed from dynwind.c:121 @deffn primitive dynamic-wind in_guard thunk out_guard All three arguments must be 0-argument procedures. @var{in_guard} is called, then @var{thunk}, then @@ -981,7 +981,7 @@ terminate if its arguments are circular data structures. @end deffn scm-error -@c snarfed from error.c:112 +@c snarfed from error.c:114 @deffn primitive scm-error key subr message args data Raise an error with key @var{key}. @var{subr} can be a string naming the procedure associated with the error, or @code{#f}. @@ -999,14 +999,14 @@ it will usually be @code{#f}. @end deffn strerror -@c snarfed from error.c:153 +@c snarfed from error.c:156 @deffn primitive strerror err Return the Unix error message corresponding to @var{err}, which must be an integer value. @end deffn apply:nconc2last -@c snarfed from eval.c:3221 +@c snarfed from eval.c:3256 @deffn primitive apply:nconc2last lst Given a list (@var{arg1} @dots{} @var{args}), this function conses the @var{arg1} @dots{} arguments onto the front of @@ -1018,7 +1018,7 @@ destroys its argument, so use with care. @end deffn force -@c snarfed from eval.c:3754 +@c snarfed from eval.c:3789 @deffn primitive force x If the promise @var{x} has not been computed yet, compute and return @var{x}, otherwise just return the previously computed @@ -1026,14 +1026,14 @@ value. @end deffn promise? -@c snarfed from eval.c:3777 +@c snarfed from eval.c:3812 @deffn primitive promise? obj Return true if @var{obj} is a promise, i.e. a delayed computation (@pxref{Delayed evaluation,,,r4rs.info,The Revised^4 Report on Scheme}). @end deffn cons-source -@c snarfed from eval.c:3789 +@c snarfed from eval.c:3824 @deffn primitive cons-source xorig x y Create and return a new pair whose car and cdr are @var{x} and @var{y}. Any source properties associated with @var{xorig} are also associated @@ -1041,7 +1041,7 @@ with the new pair. @end deffn copy-tree -@c snarfed from eval.c:3811 +@c snarfed from eval.c:3846 @deffn primitive copy-tree obj Recursively copy the data tree that is bound to @var{obj}, and return a pointer to the new data structure. @code{copy-tree} recurses down the @@ -1051,14 +1051,14 @@ any other object. @end deffn primitive-eval -@c snarfed from eval.c:3912 +@c snarfed from eval.c:3940 @deffn primitive primitive-eval exp Evaluate @var{exp} in the top-level environment specified by the current module. @end deffn eval -@c snarfed from eval.c:3977 +@c snarfed from eval.c:4009 @deffn primitive eval exp module Evaluate @var{exp}, a list representing a Scheme expression, in the top-level environment specified by @var{module}. @@ -1068,7 +1068,7 @@ is reset to its previous value when @var{eval} returns. @end deffn eval2 -@c snarfed from eval.c:4020 +@c snarfed from eval.c:4052 @deffn primitive eval2 obj env_thunk Evaluate @var{exp}, a Scheme expression, in the environment designated by @var{lookup}, a symbol-lookup function." @@ -1078,7 +1078,7 @@ with the module system. Use @code{eval} or @end deffn eval-options-interface -@c snarfed from eval.c:1685 +@c snarfed from eval.c:1697 @deffn primitive eval-options-interface [setting] Option interface for the evaluation options. Instead of using this procedure directly, use the procedures @code{eval-enable}, @@ -1086,7 +1086,7 @@ this procedure directly, use the procedures @code{eval-enable}, @end deffn evaluator-traps-interface -@c snarfed from eval.c:1702 +@c snarfed from eval.c:1714 @deffn primitive evaluator-traps-interface [setting] Option interface for the evaluator trap options. @end deffn @@ -1212,7 +1212,7 @@ The return value is unspecified. @end deffn stat -@c snarfed from filesys.c:518 +@c snarfed from filesys.c:524 @deffn primitive stat object Return an object containing various information about the file determined by @var{obj}. @var{obj} can be a string containing @@ -1269,7 +1269,7 @@ An integer representing the access permission bits. @end deffn link -@c snarfed from filesys.c:564 +@c snarfed from filesys.c:570 @deffn primitive link oldpath newpath Creates a new name @var{newpath} in the file system for the file named by @var{oldpath}. If @var{oldpath} is a symbolic @@ -1278,20 +1278,20 @@ system. @end deffn rename-file -@c snarfed from filesys.c:586 +@c snarfed from filesys.c:592 @deffn primitive rename-file oldname newname Renames the file specified by @var{oldname} to @var{newname}. The return value is unspecified. @end deffn delete-file -@c snarfed from filesys.c:615 +@c snarfed from filesys.c:621 @deffn primitive delete-file str Deletes (or "unlinks") the file specified by @var{path}. @end deffn mkdir -@c snarfed from filesys.c:634 +@c snarfed from filesys.c:640 @deffn primitive mkdir path [mode] Create a new directory named by @var{path}. If @var{mode} is omitted then the permissions of the directory file are set using the current @@ -1300,28 +1300,28 @@ umask. Otherwise they are set to the decimal value specified with @end deffn rmdir -@c snarfed from filesys.c:663 +@c snarfed from filesys.c:669 @deffn primitive rmdir path Remove the existing directory named by @var{path}. The directory must be empty for this to succeed. The return value is unspecified. @end deffn directory-stream? -@c snarfed from filesys.c:689 +@c snarfed from filesys.c:695 @deffn primitive directory-stream? obj Return a boolean indicating whether @var{object} is a directory stream as returned by @code{opendir}. @end deffn opendir -@c snarfed from filesys.c:700 +@c snarfed from filesys.c:706 @deffn primitive opendir dirname Open the directory specified by @var{path} and return a directory stream. @end deffn readdir -@c snarfed from filesys.c:718 +@c snarfed from filesys.c:724 @deffn primitive readdir port Return (as a string) the next directory entry from the directory stream @var{stream}. If there is no remaining entry to be read then the @@ -1329,34 +1329,34 @@ end of file object is returned. @end deffn rewinddir -@c snarfed from filesys.c:741 +@c snarfed from filesys.c:747 @deffn primitive rewinddir port Reset the directory port @var{stream} so that the next call to @code{readdir} will return the first directory entry. @end deffn closedir -@c snarfed from filesys.c:758 +@c snarfed from filesys.c:764 @deffn primitive closedir port Close the directory stream @var{stream}. The return value is unspecified. @end deffn chdir -@c snarfed from filesys.c:808 +@c snarfed from filesys.c:814 @deffn primitive chdir str Change the current working directory to @var{path}. The return value is unspecified. @end deffn getcwd -@c snarfed from filesys.c:825 +@c snarfed from filesys.c:831 @deffn primitive getcwd Return the name of the current working directory. @end deffn select -@c snarfed from filesys.c:1022 +@c snarfed from filesys.c:1028 @deffn primitive select reads writes excepts [secs [usecs]] This procedure has a variety of uses: waiting for the ability to provide input, accept output, or the existance of @@ -1390,7 +1390,7 @@ An additional @code{select!} interface is provided. @end deffn fcntl -@c snarfed from filesys.c:1167 +@c snarfed from filesys.c:1173 @deffn primitive fcntl object cmd [value] Apply @var{command} to the specified file descriptor or the underlying file descriptor of the specified port. @var{value} is an optional @@ -1420,7 +1420,7 @@ The value used to indicate the "close on exec" flag with @code{F_GETFL} or @end deffn fsync -@c snarfed from filesys.c:1203 +@c snarfed from filesys.c:1209 @deffn primitive fsync object Copies any unwritten data for the specified output file descriptor to disk. If @var{port/fd} is a port, its buffer is flushed before the underlying @@ -1429,21 +1429,21 @@ The return value is unspecified. @end deffn symlink -@c snarfed from filesys.c:1230 +@c snarfed from filesys.c:1236 @deffn primitive symlink oldpath newpath Create a symbolic link named @var{path-to} with the value (i.e., pointing to) @var{path-from}. The return value is unspecified. @end deffn readlink -@c snarfed from filesys.c:1252 +@c snarfed from filesys.c:1257 @deffn primitive readlink path Return the value of the symbolic link named by @var{path} (a string), i.e., the file that the link points to. @end deffn lstat -@c snarfed from filesys.c:1282 +@c snarfed from filesys.c:1287 @deffn primitive lstat str Similar to @code{stat}, but does not follow symbolic links, i.e., it will return information about a symbolic link itself, not the @@ -1451,14 +1451,14 @@ file it points to. @var{path} must be a string. @end deffn copy-file -@c snarfed from filesys.c:1307 +@c snarfed from filesys.c:1312 @deffn primitive copy-file oldfile newfile Copy the file specified by @var{path-from} to @var{path-to}. The return value is unspecified. @end deffn dirname -@c snarfed from filesys.c:1354 +@c snarfed from filesys.c:1359 @deffn primitive dirname filename Return the directory name component of the file name @var{filename}. If @var{filename} does not contain a directory @@ -1466,7 +1466,7 @@ component, @code{.} is returned. @end deffn basename -@c snarfed from filesys.c:1387 +@c snarfed from filesys.c:1392 @deffn primitive basename filename [suffix] Return the base name of the file name @var{filename}. The base name is the file name without any directory components. @@ -1487,14 +1487,14 @@ in its own dynamic root, you can use fluids for thread local storage. @end deffn fluid? -@c snarfed from fluids.c:141 +@c snarfed from fluids.c:142 @deffn primitive fluid? obj Return @code{#t} iff @var{obj} is a fluid; otherwise, return @code{#f}. @end deffn fluid-ref -@c snarfed from fluids.c:151 +@c snarfed from fluids.c:153 @deffn primitive fluid-ref fluid Return the value associated with @var{fluid} in the current dynamic root. If @var{fluid} has not been set, then return @@ -1502,13 +1502,13 @@ dynamic root. If @var{fluid} has not been set, then return @end deffn fluid-set! -@c snarfed from fluids.c:168 +@c snarfed from fluids.c:170 @deffn primitive fluid-set! fluid value Set the value associated with @var{fluid} in the current dynamic root. @end deffn with-fluids* -@c snarfed from fluids.c:227 +@c snarfed from fluids.c:229 @deffn primitive with-fluids* fluids values thunk Set @var{fluids} to @var{values} temporary, and call @var{thunk}. @var{fluids} must be a list of fluids and @var{values} must be the same @@ -1538,7 +1538,7 @@ Determine whether @var{obj} is a port that is related to a file. @end deffn open-file -@c snarfed from fports.c:282 +@c snarfed from fports.c:283 @deffn primitive open-file filename mode Open the file whose name is @var{filename}, and return a port representing that file. The attributes of the port are @@ -1580,28 +1580,28 @@ requested, @code{open-file} throws an exception. @end deffn gc-stats -@c snarfed from gc.c:742 +@c snarfed from gc.c:749 @deffn primitive gc-stats Return an association list of statistics about Guile's current use of storage. @end deffn object-address -@c snarfed from gc.c:839 +@c snarfed from gc.c:846 @deffn primitive object-address obj Return an integer that for the lifetime of @var{obj} is uniquely returned by this function for @var{obj} @end deffn gc -@c snarfed from gc.c:850 +@c snarfed from gc.c:857 @deffn primitive gc Scans all of SCM objects and reclaims for further use those that are no longer accessible. @end deffn unhash-name -@c snarfed from gc.c:2291 +@c snarfed from gc.c:2303 @deffn primitive unhash-name name Flushes the glocs for @var{name}, or all glocs if @var{name} is @code{#t}. @@ -1985,7 +1985,7 @@ integer in the range 0 to @var{size} - 1. @end deffn hashq-get-handle -@c snarfed from hashtab.c:174 +@c snarfed from hashtab.c:173 @deffn primitive hashq-get-handle table key This procedure returns the @code{(key . value)} pair from the hash table @var{table}. If @var{table} does not hold an @@ -1994,7 +1994,7 @@ Uses @code{eq?} for equality testing. @end deffn hashq-create-handle! -@c snarfed from hashtab.c:186 +@c snarfed from hashtab.c:185 @deffn primitive hashq-create-handle! table key init This function looks up @var{key} in @var{table} and returns its handle. If @var{key} is not already present, a new handle is created which @@ -2002,7 +2002,7 @@ associates @var{key} with @var{init}. @end deffn hashq-ref -@c snarfed from hashtab.c:199 +@c snarfed from hashtab.c:198 @deffn primitive hashq-ref table key [dflt] Look up @var{key} in the hash table @var{table}, and return the value (if any) associated with it. If @var{key} is not found, @@ -2011,21 +2011,21 @@ is supplied). Uses @code{eq?} for equality testing. @end deffn hashq-set! -@c snarfed from hashtab.c:213 +@c snarfed from hashtab.c:212 @deffn primitive hashq-set! table key val Find the entry in @var{table} associated with @var{key}, and store @var{value} there. Uses @code{eq?} for equality testing. @end deffn hashq-remove! -@c snarfed from hashtab.c:225 +@c snarfed from hashtab.c:224 @deffn primitive hashq-remove! table key Remove @var{key} (and any value associated with it) from @var{table}. Uses @code{eq?} for equality tests. @end deffn hashv-get-handle -@c snarfed from hashtab.c:242 +@c snarfed from hashtab.c:240 @deffn primitive hashv-get-handle table key This procedure returns the @code{(key . value)} pair from the hash table @var{table}. If @var{table} does not hold an @@ -2034,7 +2034,7 @@ Uses @code{eqv?} for equality testing. @end deffn hashv-create-handle! -@c snarfed from hashtab.c:254 +@c snarfed from hashtab.c:252 @deffn primitive hashv-create-handle! table key init This function looks up @var{key} in @var{table} and returns its handle. If @var{key} is not already present, a new handle is created which @@ -2042,7 +2042,7 @@ associates @var{key} with @var{init}. @end deffn hashv-ref -@c snarfed from hashtab.c:267 +@c snarfed from hashtab.c:266 @deffn primitive hashv-ref table key [dflt] Look up @var{key} in the hash table @var{table}, and return the value (if any) associated with it. If @var{key} is not found, @@ -2051,21 +2051,21 @@ is supplied). Uses @code{eqv?} for equality testing. @end deffn hashv-set! -@c snarfed from hashtab.c:281 +@c snarfed from hashtab.c:280 @deffn primitive hashv-set! table key val Find the entry in @var{table} associated with @var{key}, and store @var{value} there. Uses @code{eqv?} for equality testing. @end deffn hashv-remove! -@c snarfed from hashtab.c:292 +@c snarfed from hashtab.c:291 @deffn primitive hashv-remove! table key Remove @var{key} (and any value associated with it) from @var{table}. Uses @code{eqv?} for equality tests. @end deffn hash-get-handle -@c snarfed from hashtab.c:308 +@c snarfed from hashtab.c:306 @deffn primitive hash-get-handle table key This procedure returns the @code{(key . value)} pair from the hash table @var{table}. If @var{table} does not hold an @@ -2074,7 +2074,7 @@ Uses @code{equal?} for equality testing. @end deffn hash-create-handle! -@c snarfed from hashtab.c:320 +@c snarfed from hashtab.c:318 @deffn primitive hash-create-handle! table key init This function looks up @var{key} in @var{table} and returns its handle. If @var{key} is not already present, a new handle is created which @@ -2082,7 +2082,7 @@ associates @var{key} with @var{init}. @end deffn hash-ref -@c snarfed from hashtab.c:333 +@c snarfed from hashtab.c:331 @deffn primitive hash-ref table key [dflt] Look up @var{key} in the hash table @var{table}, and return the value (if any) associated with it. If @var{key} is not found, @@ -2091,7 +2091,7 @@ is supplied). Uses @code{equal?} for equality testing. @end deffn hash-set! -@c snarfed from hashtab.c:348 +@c snarfed from hashtab.c:346 @deffn primitive hash-set! table key val Find the entry in @var{table} associated with @var{key}, and store @var{value} there. Uses @code{equal?} for equality @@ -2099,14 +2099,14 @@ testing. @end deffn hash-remove! -@c snarfed from hashtab.c:360 +@c snarfed from hashtab.c:358 @deffn primitive hash-remove! table key Remove @var{key} (and any value associated with it) from @var{table}. Uses @code{equal?} for equality tests. @end deffn hashx-get-handle -@c snarfed from hashtab.c:429 +@c snarfed from hashtab.c:428 @deffn primitive hashx-get-handle hash assoc table key This behaves the same way as the corresponding @code{-get-handle} function, but uses @var{hash} as a hash @@ -2128,7 +2128,7 @@ table size. @code{assoc} must be an associator function, like @end deffn hashx-ref -@c snarfed from hashtab.c:468 +@c snarfed from hashtab.c:470 @deffn primitive hashx-ref hash assoc table key [dflt] This behaves the same way as the corresponding @code{ref} function, but uses @var{hash} as a hash function and @@ -2141,7 +2141,7 @@ equivalent to @code{hashx-ref hashq assq table key}. @end deffn hashx-set! -@c snarfed from hashtab.c:492 +@c snarfed from hashtab.c:496 @deffn primitive hashx-set! hash assoc table key val This behaves the same way as the corresponding @code{set!} function, but uses @var{hash} as a hash function and @@ -2154,7 +2154,7 @@ equivalent to @code{hashx-set! hashq assq table key}. @end deffn hash-fold -@c snarfed from hashtab.c:529 +@c snarfed from hashtab.c:534 @deffn primitive hash-fold proc init table An iterator over hash-table elements. Accumulates and returns a result by applying PROC successively. @@ -2167,7 +2167,7 @@ table into an a-list of key-value pairs. @end deffn make-hook-with-name -@c snarfed from hooks.c:216 +@c snarfed from hooks.c:217 @deffn primitive make-hook-with-name name [n_args] Create a named hook with the name @var{name} for storing procedures of arity @var{n_args}. @var{n_args} defaults to @@ -2175,27 +2175,27 @@ zero. @end deffn make-hook -@c snarfed from hooks.c:230 +@c snarfed from hooks.c:232 @deffn primitive make-hook [n_args] Create a hook for storing procedure of arity @var{n_args}. @var{n_args} defaults to zero. @end deffn hook? -@c snarfed from hooks.c:240 +@c snarfed from hooks.c:242 @deffn primitive hook? x Return @code{#t} if @var{x} is a hook, @code{#f} otherwise. @end deffn hook-empty? -@c snarfed from hooks.c:250 +@c snarfed from hooks.c:253 @deffn primitive hook-empty? hook Return @code{#t} if @var{hook} is an empty hook, @code{#f} otherwise. @end deffn add-hook! -@c snarfed from hooks.c:263 +@c snarfed from hooks.c:266 @deffn primitive add-hook! hook proc [append_p] Add the procedure @var{proc} to the hook @var{hook}. The procedure is added to the end if @var{append_p} is true, @@ -2203,19 +2203,19 @@ otherwise it is added to the front. @end deffn remove-hook! -@c snarfed from hooks.c:289 +@c snarfed from hooks.c:292 @deffn primitive remove-hook! hook proc Remove the procedure @var{proc} from the hook @var{hook}. @end deffn reset-hook! -@c snarfed from hooks.c:302 +@c snarfed from hooks.c:305 @deffn primitive reset-hook! hook Remove all procedures from the hook @var{hook}. @end deffn run-hook -@c snarfed from hooks.c:315 +@c snarfed from hooks.c:319 @deffn primitive run-hook hook . args Apply all procedures from the hook @var{hook} to the arguments @var{args}. The order of the procedure application is first to @@ -2223,7 +2223,7 @@ last. @end deffn hook->list -@c snarfed from hooks.c:342 +@c snarfed from hooks.c:346 @deffn primitive hook->list hook Convert the procedure list of @var{hook} to a list. @end deffn @@ -2265,7 +2265,7 @@ end-of-file check @end deffn ftell -@c snarfed from ioext.c:173 +@c snarfed from ioext.c:174 @deffn primitive ftell fd_port Return an integer representing the current position of @var{fd/port}, measured from the beginning. Equivalent to: @@ -2275,14 +2275,14 @@ Return an integer representing the current position of @end deffn fseek -@c snarfed from ioext.c:186 +@c snarfed from ioext.c:187 @deffn primitive fseek fd_port offset whence Obsolete. Almost the same as @code{seek}, but the return value is unspecified. @end deffn redirect-port -@c snarfed from ioext.c:208 +@c snarfed from ioext.c:209 @deffn primitive redirect-port old new This procedure takes two ports and duplicates the underlying file descriptor from @var{old-port} into @var{new-port}. The @@ -2300,7 +2300,7 @@ revealed counts. @end deffn dup->fdes -@c snarfed from ioext.c:245 +@c snarfed from ioext.c:248 @deffn primitive dup->fdes fd_or_port [fd] Return a new integer file descriptor referring to the open file designated by @var{fd_or_port}, which must be either an open @@ -2308,7 +2308,7 @@ file port or a file descriptor. @end deffn dup2 -@c snarfed from ioext.c:292 +@c snarfed from ioext.c:295 @deffn primitive dup2 oldfd newfd A simple wrapper for the @code{dup2} system call. Copies the file descriptor @var{oldfd} to descriptor @@ -2321,21 +2321,21 @@ The return value is unspecified. @end deffn fileno -@c snarfed from ioext.c:311 +@c snarfed from ioext.c:314 @deffn primitive fileno port Return the integer file descriptor underlying @var{port}. Does not change its revealed count. @end deffn isatty? -@c snarfed from ioext.c:327 +@c snarfed from ioext.c:330 @deffn primitive isatty? port Return @code{#t} if @var{port} is using a serial non--file device, otherwise @code{#f}. @end deffn fdopen -@c snarfed from ioext.c:349 +@c snarfed from ioext.c:352 @deffn primitive fdopen fdes modes Return a new port based on the file descriptor @var{fdes}. Modes are given by the string @var{modes}. The revealed count @@ -2344,7 +2344,7 @@ same as that accepted by @ref{File Ports, open-file}. @end deffn primitive-move->fdes -@c snarfed from ioext.c:374 +@c snarfed from ioext.c:377 @deffn primitive primitive-move->fdes port fd Moves the underlying file descriptor for @var{port} to the integer value @var{fdes} without changing the revealed count of @var{port}. @@ -2355,7 +2355,7 @@ required value or @code{#t} if it was moved. @end deffn fdes->ports -@c snarfed from ioext.c:407 +@c snarfed from ioext.c:411 @deffn primitive fdes->ports fd Return a list of existing ports which have @var{fdes} as an underlying file descriptor, without changing their revealed @@ -2369,14 +2369,14 @@ Make a keyword object from a @var{symbol} that starts with a dash. @end deffn keyword? -@c snarfed from keywords.c:112 +@c snarfed from keywords.c:113 @deffn primitive keyword? obj Return @code{#t} if the argument @var{obj} is a keyword, else @code{#f}. @end deffn keyword-dash-symbol -@c snarfed from keywords.c:123 +@c snarfed from keywords.c:124 @deffn primitive keyword-dash-symbol keyword Return the dash symbol for @var{keyword}. This is the inverse of @code{make-keyword-from-dash-symbol}. @@ -2481,7 +2481,7 @@ if the last argument is not a proper list. @end deffn append! -@c snarfed from list.c:242 +@c snarfed from list.c:243 @deffn primitive append! . lists A destructive version of @code{append} (@pxref{Pairs and Lists,,,r4rs, The Revised^4 Report on Scheme}). The cdr field @@ -2491,21 +2491,21 @@ the mutated list. @end deffn last-pair -@c snarfed from list.c:268 +@c snarfed from list.c:269 @deffn primitive last-pair lst Return a pointer to the last pair in @var{lst}, signalling an error if @var{lst} is circular. @end deffn reverse -@c snarfed from list.c:298 +@c snarfed from list.c:299 @deffn primitive reverse lst Return a new list that contains the elements of @var{lst} but in reverse order. @end deffn reverse! -@c snarfed from list.c:332 +@c snarfed from list.c:333 @deffn primitive reverse! lst [new_tail] A destructive version of @code{reverse} (@pxref{Pairs and Lists,,,r4rs, The Revised^4 Report on Scheme}). The cdr of each cell in @var{lst} is @@ -2521,25 +2521,25 @@ of the modified list is not lost, it is wise to save the return value of @end deffn list-ref -@c snarfed from list.c:358 +@c snarfed from list.c:359 @deffn primitive list-ref list k Return the @var{k}th element from @var{list}. @end deffn list-set! -@c snarfed from list.c:382 +@c snarfed from list.c:383 @deffn primitive list-set! list k val Set the @var{k}th element of @var{list} to @var{val}. @end deffn list-cdr-ref -@c snarfed from list.c:405 +@c snarfed from list.c:406 @deffn primitive list-cdr-ref scm_list_tail @end deffn list-tail -@c snarfed from list.c:414 +@c snarfed from list.c:415 @deffn primitive list-tail lst k @deffnx primitive list-cdr-ref lst k Return the "tail" of @var{lst} beginning with its @var{k}th element. @@ -2551,26 +2551,26 @@ or returning the results of cdring @var{k} times down @var{lst}. @end deffn list-cdr-set! -@c snarfed from list.c:430 +@c snarfed from list.c:431 @deffn primitive list-cdr-set! list k val Set the @var{k}th cdr of @var{list} to @var{val}. @end deffn list-head -@c snarfed from list.c:459 +@c snarfed from list.c:460 @deffn primitive list-head lst k Copy the first @var{k} elements from @var{lst} into a new list, and return it. @end deffn list-copy -@c snarfed from list.c:483 +@c snarfed from list.c:484 @deffn primitive list-copy lst Return a (newly-created) copy of @var{lst}. @end deffn sloppy-memq -@c snarfed from list.c:517 +@c snarfed from list.c:518 @deffn primitive sloppy-memq x lst This procedure behaves like @code{memq}, but does no type or error checking. Its use is recommended only in writing Guile internals, @@ -2578,7 +2578,7 @@ not for high-level Scheme programs. @end deffn sloppy-memv -@c snarfed from list.c:534 +@c snarfed from list.c:535 @deffn primitive sloppy-memv x lst This procedure behaves like @code{memv}, but does no type or error checking. Its use is recommended only in writing Guile internals, @@ -2586,7 +2586,7 @@ not for high-level Scheme programs. @end deffn sloppy-member -@c snarfed from list.c:551 +@c snarfed from list.c:552 @deffn primitive sloppy-member x lst This procedure behaves like @code{member}, but does no type or error checking. Its use is recommended only in writing Guile internals, @@ -2594,7 +2594,7 @@ not for high-level Scheme programs. @end deffn memq -@c snarfed from list.c:591 +@c snarfed from list.c:592 @deffn primitive memq x lst Return the first sublist of @var{lst} whose car is @code{eq?} to @var{x} where the sublists of @var{lst} are the non-empty @@ -2605,7 +2605,7 @@ returned. @end deffn memv -@c snarfed from list.c:608 +@c snarfed from list.c:609 @deffn primitive memv x lst Return the first sublist of @var{lst} whose car is @code{eqv?} to @var{x} where the sublists of @var{lst} are the non-empty @@ -2616,7 +2616,7 @@ returned. @end deffn member -@c snarfed from list.c:629 +@c snarfed from list.c:630 @deffn primitive member x lst Return the first sublist of @var{lst} whose car is @code{equal?} to @var{x} where the sublists of @var{lst} are @@ -2627,7 +2627,7 @@ empty list) is returned. @end deffn delq! -@c snarfed from list.c:655 +@c snarfed from list.c:656 @deffn primitive delq! item lst @deffnx primitive delv! item lst @deffnx primitive delete! item lst @@ -2640,21 +2640,21 @@ destructive list functions, these functions cannot modify the binding of @end deffn delv! -@c snarfed from list.c:679 +@c snarfed from list.c:680 @deffn primitive delv! item lst Destructively remove all elements from @var{lst} that are @code{eqv?} to @var{item}. @end deffn delete! -@c snarfed from list.c:704 +@c snarfed from list.c:705 @deffn primitive delete! item lst Destructively remove all elements from @var{lst} that are @code{equal?} to @var{item}. @end deffn delq -@c snarfed from list.c:733 +@c snarfed from list.c:734 @deffn primitive delq item lst Return a newly-created copy of @var{lst} with elements @code{eq?} to @var{item} removed. This procedure mirrors @@ -2663,7 +2663,7 @@ Return a newly-created copy of @var{lst} with elements @end deffn delv -@c snarfed from list.c:746 +@c snarfed from list.c:747 @deffn primitive delv item lst Return a newly-created copy of @var{lst} with elements @code{eqv?} to @var{item} removed. This procedure mirrors @@ -2672,7 +2672,7 @@ Return a newly-created copy of @var{lst} with elements @end deffn delete -@c snarfed from list.c:759 +@c snarfed from list.c:760 @deffn primitive delete item lst Return a newly-created copy of @var{lst} with elements @code{equal?} to @var{item} removed. This procedure mirrors @@ -2681,7 +2681,7 @@ against @var{item} with @code{equal?}. @end deffn delq1! -@c snarfed from list.c:772 +@c snarfed from list.c:773 @deffn primitive delq1! item lst Like @code{delq!}, but only deletes the first occurrence of @var{item} from @var{lst}. Tests for equality using @@ -2689,7 +2689,7 @@ Like @code{delq!}, but only deletes the first occurrence of @end deffn delv1! -@c snarfed from list.c:800 +@c snarfed from list.c:801 @deffn primitive delv1! item lst Like @code{delv!}, but only deletes the first occurrence of @var{item} from @var{lst}. Tests for equality using @@ -2697,7 +2697,7 @@ Like @code{delv!}, but only deletes the first occurrence of @end deffn delete1! -@c snarfed from list.c:828 +@c snarfed from list.c:829 @deffn primitive delete1! item lst Like @code{delete!}, but only deletes the first occurrence of @var{item} from @var{lst}. Tests for equality using @@ -2790,7 +2790,7 @@ signalled. @end deffn procedure->syntax -@c snarfed from macros.c:60 +@c snarfed from macros.c:61 @deffn primitive procedure->syntax code Return a @dfn{macro} which, when a symbol defined to this value appears as the first symbol in an expression, returns the @@ -2799,7 +2799,7 @@ environment. @end deffn procedure->macro -@c snarfed from macros.c:82 +@c snarfed from macros.c:84 @deffn primitive procedure->macro code Return a @dfn{macro} which, when a symbol defined to this value appears as the first symbol in an expression, evaluates the @@ -2817,7 +2817,7 @@ passed to @var{code}. For example: @end deffn procedure->memoizing-macro -@c snarfed from macros.c:104 +@c snarfed from macros.c:107 @deffn primitive procedure->memoizing-macro code Return a @dfn{macro} which, when a symbol defined to this value appears as the first symbol in an expression, evaluates the @@ -2835,14 +2835,14 @@ passed to @var{proc}. For example: @end deffn macro? -@c snarfed from macros.c:116 +@c snarfed from macros.c:119 @deffn primitive macro? obj Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a syntax transformer. @end deffn macro-type -@c snarfed from macros.c:133 +@c snarfed from macros.c:137 @deffn primitive macro-type m Return one of the symbols @code{syntax}, @code{macro} or @code{macro!}, depending on whether @var{m} is a syntax @@ -2852,13 +2852,13 @@ returned. @end deffn macro-name -@c snarfed from macros.c:151 +@c snarfed from macros.c:155 @deffn primitive macro-name m Return the name of the macro @var{m}. @end deffn macro-transformer -@c snarfed from macros.c:162 +@c snarfed from macros.c:166 @deffn primitive macro-transformer m Return the transformer of the macro @var{m}. @end deffn @@ -2900,7 +2900,7 @@ the traditional dotted decimal representation. @end deffn inet-netof -@c snarfed from net_db.c:135 +@c snarfed from net_db.c:136 @deffn primitive inet-netof address Return the network number part of the given integer Internet address. @@ -2910,7 +2910,7 @@ address. @end deffn inet-lnaof -@c snarfed from net_db.c:152 +@c snarfed from net_db.c:153 @deffn primitive inet-lnaof address Return the local-address-with-network part of the given Internet address. @@ -2920,7 +2920,7 @@ Internet address. @end deffn inet-makeaddr -@c snarfed from net_db.c:169 +@c snarfed from net_db.c:171 @deffn primitive inet-makeaddr net lna Makes an Internet host address by combining the network number @var{net} with the local-address-within-network number @@ -2931,7 +2931,7 @@ Makes an Internet host address by combining the network number @end deffn gethost -@c snarfed from net_db.c:254 +@c snarfed from net_db.c:256 @deffn primitive gethost [host] @deffnx procedure gethostbyname hostname @deffnx procedure gethostbyaddr address @@ -2947,7 +2947,7 @@ Unusual conditions may result in errors thrown to the @end deffn getnet -@c snarfed from net_db.c:335 +@c snarfed from net_db.c:337 @deffn primitive getnet [net] @deffnx procedure getnetbyname net-name @deffnx procedure getnetbyaddr net-number @@ -2959,7 +2959,7 @@ given. @end deffn getproto -@c snarfed from net_db.c:385 +@c snarfed from net_db.c:387 @deffn primitive getproto [protocol] @deffnx procedure getprotobyname name @deffnx procedure getprotobynumber number @@ -2970,7 +2970,7 @@ argument. @code{getproto} will accept either type, behaving like @end deffn getserv -@c snarfed from net_db.c:452 +@c snarfed from net_db.c:454 @deffn primitive getserv [name [protocol]] @deffnx procedure getservbyname name protocol @deffnx procedure getservbyport port protocol @@ -2985,28 +2985,28 @@ as its first argument; if given no arguments, it behaves like @end deffn sethost -@c snarfed from net_db.c:491 +@c snarfed from net_db.c:493 @deffn primitive sethost [stayopen] If @var{stayopen} is omitted, this is equivalent to @code{endhostent}. Otherwise it is equivalent to @code{sethostent stayopen}. @end deffn setnet -@c snarfed from net_db.c:507 +@c snarfed from net_db.c:509 @deffn primitive setnet [stayopen] If @var{stayopen} is omitted, this is equivalent to @code{endnetent}. Otherwise it is equivalent to @code{setnetent stayopen}. @end deffn setproto -@c snarfed from net_db.c:523 +@c snarfed from net_db.c:525 @deffn primitive setproto [stayopen] If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}. Otherwise it is equivalent to @code{setprotoent stayopen}. @end deffn setserv -@c snarfed from net_db.c:539 +@c snarfed from net_db.c:541 @deffn primitive setserv [stayopen] If @var{stayopen} is omitted, this is equivalent to @code{endservent}. Otherwise it is equivalent to @code{setservent stayopen}. @@ -3092,7 +3092,7 @@ arguments. @end deffn lognot -@c snarfed from numbers.c:1102 +@c snarfed from numbers.c:1103 @deffn primitive lognot n Return the integer which is the 2s-complement of the integer argument. @@ -3105,7 +3105,7 @@ argument. @end deffn integer-expt -@c snarfed from numbers.c:1118 +@c snarfed from numbers.c:1120 @deffn primitive integer-expt n k Return @var{n} raised to the non-negative integer exponent @var{k}. @@ -3118,7 +3118,7 @@ Return @var{n} raised to the non-negative integer exponent @end deffn ash -@c snarfed from numbers.c:1166 +@c snarfed from numbers.c:1167 @deffn primitive ash n cnt The function ash performs an arithmetic shift left by @var{cnt} bits (or shift right, if @var{cnt} is negative). 'Arithmetic' @@ -3136,7 +3136,7 @@ Formally, the function returns an integer equivalent to @end deffn bit-extract -@c snarfed from numbers.c:1219 +@c snarfed from numbers.c:1220 @deffn primitive bit-extract n start end Return the integer composed of the @var{start} (inclusive) through @var{end} (exclusive) bits of @var{n}. The @@ -3150,7 +3150,7 @@ through @var{end} (exclusive) bits of @var{n}. The @end deffn logcount -@c snarfed from numbers.c:1291 +@c snarfed from numbers.c:1292 @deffn primitive logcount n Return the number of bits in integer @var{n}. If integer is positive, the 1-bits in its binary representation are counted. @@ -3167,7 +3167,7 @@ representation are counted. If 0, 0 is returned. @end deffn integer-length -@c snarfed from numbers.c:1342 +@c snarfed from numbers.c:1343 @deffn primitive integer-length n Return the number of bits neccessary to represent @var{n}. @lisp @@ -3181,7 +3181,7 @@ Return the number of bits neccessary to represent @var{n}. @end deffn number->string -@c snarfed from numbers.c:2288 +@c snarfed from numbers.c:2289 @deffn primitive number->string n [radix] Return a string holding the external representation of the number @var{n} in the given @var{radix}. If @var{n} is @@ -3189,7 +3189,7 @@ inexact, a radix of 10 will be used. @end deffn string->number -@c snarfed from numbers.c:2873 +@c snarfed from numbers.c:2874 @deffn primitive string->number string [radix] Return a number of the maximally precise representation expressed by the given @var{string}. @var{radix} must be an @@ -3202,13 +3202,13 @@ syntactically valid notation for a number, then @end deffn number? -@c snarfed from numbers.c:2940 +@c snarfed from numbers.c:2941 @deffn primitive number? scm_number_p @end deffn complex? -@c snarfed from numbers.c:2952 +@c snarfed from numbers.c:2953 @deffn primitive complex? x Return @code{#t} if @var{x} is a complex number, @code{#f} else. Note that the sets of real, rational and integer @@ -3218,13 +3218,13 @@ rational or integer number. @end deffn real? -@c snarfed from numbers.c:2960 +@c snarfed from numbers.c:2961 @deffn primitive real? scm_real_p @end deffn rational? -@c snarfed from numbers.c:2973 +@c snarfed from numbers.c:2974 @deffn primitive rational? x Return @code{#t} if @var{x} is a rational number, @code{#f} else. Note that the set of integer values forms a subset of @@ -3235,28 +3235,28 @@ precision. @end deffn integer? -@c snarfed from numbers.c:2994 +@c snarfed from numbers.c:2995 @deffn primitive integer? x Return @code{#t} if @var{x} is an integer number, @code{#f} else. @end deffn inexact? -@c snarfed from numbers.c:3019 +@c snarfed from numbers.c:3020 @deffn primitive inexact? x Return @code{#t} if @var{x} is an inexact number, @code{#f} else. @end deffn $expt -@c snarfed from numbers.c:4071 +@c snarfed from numbers.c:4072 @deffn primitive $expt x y Return @var{x} raised to the power of @var{y}. This procedure does not accept complex arguments. @end deffn $atan2 -@c snarfed from numbers.c:4087 +@c snarfed from numbers.c:4088 @deffn primitive $atan2 x y Return the arc tangent of the two arguments @var{x} and @var{y}. This is similar to calculating the arc tangent of @@ -3266,20 +3266,20 @@ procedure does not accept complex arguments. @end deffn make-rectangular -@c snarfed from numbers.c:4100 +@c snarfed from numbers.c:4101 @deffn primitive make-rectangular real imaginary Return a complex number constructed of the given @var{real} and @var{imaginary} parts. @end deffn make-polar -@c snarfed from numbers.c:4113 +@c snarfed from numbers.c:4114 @deffn primitive make-polar x y Return the complex number @var{x} * e^(i * @var{y}). @end deffn inexact->exact -@c snarfed from numbers.c:4231 +@c snarfed from numbers.c:4232 @deffn primitive inexact->exact z Return an exact number that is numerically closest to @var{z}. @end deffn @@ -3361,21 +3361,21 @@ sense of @code{eq?}) from every previously existing object. @end deffn pair? -@c snarfed from pairs.c:93 +@c snarfed from pairs.c:94 @deffn primitive pair? x Return @code{#t} if @var{x} is a pair; otherwise return @code{#f}. @end deffn set-car! -@c snarfed from pairs.c:104 +@c snarfed from pairs.c:105 @deffn primitive set-car! pair value Stores @var{value} in the car field of @var{pair}. The value returned by @code{set-car!} is unspecified. @end deffn set-cdr! -@c snarfed from pairs.c:117 +@c snarfed from pairs.c:118 @deffn primitive set-cdr! pair value Stores @var{value} in the cdr field of @var{pair}. The value returned by @code{set-cdr!} is unspecified. @@ -3561,21 +3561,21 @@ Equivalent to @code{(or (input-port? @var{x}) (output-port? @end deffn port-closed? -@c snarfed from ports.c:828 +@c snarfed from ports.c:829 @deffn primitive port-closed? port Return @code{#t} if @var{port} is closed or @code{#f} if it is open. @end deffn eof-object? -@c snarfed from ports.c:839 +@c snarfed from ports.c:840 @deffn primitive eof-object? x Return @code{#t} if @var{x} is an end-of-file object; otherwise return @code{#f}. @end deffn force-output -@c snarfed from ports.c:853 +@c snarfed from ports.c:854 @deffn primitive force-output [port] Flush the specified output port, or the current output port if @var{port} is omitted. The current output buffer contents are passed to the @@ -3587,14 +3587,14 @@ The return value is unspecified. @end deffn flush-all-ports -@c snarfed from ports.c:871 +@c snarfed from ports.c:872 @deffn primitive flush-all-ports Equivalent to calling @code{force-output} on all open output ports. The return value is unspecified. @end deffn read-char -@c snarfed from ports.c:889 +@c snarfed from ports.c:890 @deffn primitive read-char [port] Return the next character available from @var{port}, updating @var{port} to point to the following character. If no more @@ -3602,7 +3602,7 @@ characters are available, the end-of-file object is returned. @end deffn peek-char -@c snarfed from ports.c:1205 +@c snarfed from ports.c:1207 @deffn primitive peek-char [port] Return the next character available from @var{port}, @emph{without} updating @var{port} to point to the following @@ -3619,7 +3619,7 @@ to @code{read-char} would have hung.} @end deffn unread-char -@c snarfed from ports.c:1226 +@c snarfed from ports.c:1228 @deffn primitive unread-char cobj [port] Place @var{char} in @var{port} so that it will be read by the next read operation. If called multiple times, the unread characters @@ -3628,7 +3628,7 @@ not supplied, the current input port is used. @end deffn unread-string -@c snarfed from ports.c:1249 +@c snarfed from ports.c:1251 @deffn primitive unread-string str port Place the string @var{str} in @var{port} so that its characters will be read in subsequent read operations. If called multiple times, the @@ -3637,7 +3637,7 @@ unread characters will be read again in last-in first-out order. If @end deffn seek -@c snarfed from ports.c:1285 +@c snarfed from ports.c:1290 @deffn primitive seek fd_port offset whence Sets the current position of @var{fd/port} to the integer @var{offset}, which is interpreted according to the value of @@ -3663,7 +3663,7 @@ that the current position of a port can be obtained using: @end deffn truncate-file -@c snarfed from ports.c:1326 +@c snarfed from ports.c:1331 @deffn primitive truncate-file object [length] Truncates the object referred to by @var{object} to at most @var{length} bytes. @var{object} can be a string containing a @@ -3674,19 +3674,19 @@ position. The return value is unspecified. @end deffn port-line -@c snarfed from ports.c:1380 +@c snarfed from ports.c:1385 @deffn primitive port-line port Return the current line number for @var{port}. @end deffn set-port-line! -@c snarfed from ports.c:1391 +@c snarfed from ports.c:1396 @deffn primitive set-port-line! port line Set the current line number for @var{port} to @var{line}. @end deffn port-column -@c snarfed from ports.c:1412 +@c snarfed from ports.c:1417 @deffn primitive port-column port @deffnx primitive port-line port Return the current column number or line number of @var{port}, @@ -3700,7 +3700,7 @@ what non-programmers will find most natural.) @end deffn set-port-column! -@c snarfed from ports.c:1425 +@c snarfed from ports.c:1430 @deffn primitive set-port-column! port column @deffnx primitive set-port-line! port line Set the current column or line number of @var{port}, using the @@ -3708,7 +3708,7 @@ current input port if none is specified. @end deffn port-filename -@c snarfed from ports.c:1440 +@c snarfed from ports.c:1445 @deffn primitive port-filename port Return the filename associated with @var{port}. This function returns the strings "standard input", "standard output" and "standard error" @@ -3716,7 +3716,7 @@ when called on the current input, output and error ports respectively. @end deffn set-port-filename! -@c snarfed from ports.c:1454 +@c snarfed from ports.c:1459 @deffn primitive set-port-filename! port filename Change the filename associated with @var{port}, using the current input port if none is specified. Note that this does not change the port's @@ -3725,7 +3725,7 @@ source of data, but only the value that is returned by @end deffn %make-void-port -@c snarfed from ports.c:1546 +@c snarfed from ports.c:1551 @deffn primitive %make-void-port mode Create and return a new void port. A void port acts like /dev/null. The @var{mode} argument @@ -3751,14 +3751,14 @@ from the input port. @end deffn getgroups -@c snarfed from posix.c:221 +@c snarfed from posix.c:222 @deffn primitive getgroups Return a vector of integers representing the current supplimentary group IDs. @end deffn getpw -@c snarfed from posix.c:254 +@c snarfed from posix.c:255 @deffn primitive getpw [user] Look up an entry in the user database. @var{obj} can be an integer, a string, or omitted, giving the behaviour of getpwuid, getpwnam @@ -3766,7 +3766,7 @@ or getpwent respectively. @end deffn setpw -@c snarfed from posix.c:307 +@c snarfed from posix.c:308 @deffn primitive setpw [arg] If called with a true argument, initialize or reset the password data stream. Otherwise, close the stream. The @code{setpwent} and @@ -3774,7 +3774,7 @@ stream. Otherwise, close the stream. The @code{setpwent} and @end deffn getgr -@c snarfed from posix.c:326 +@c snarfed from posix.c:327 @deffn primitive getgr [name] Look up an entry in the group database. @var{obj} can be an integer, a string, or omitted, giving the behaviour of getgrgid, getgrnam @@ -3782,7 +3782,7 @@ or getgrent respectively. @end deffn setgr -@c snarfed from posix.c:367 +@c snarfed from posix.c:368 @deffn primitive setgr [arg] If called with a true argument, initialize or reset the group data stream. Otherwise, close the stream. The @code{setgrent} and @@ -3790,7 +3790,7 @@ stream. Otherwise, close the stream. The @code{setgrent} and @end deffn kill -@c snarfed from posix.c:403 +@c snarfed from posix.c:404 @deffn primitive kill pid sig Sends a signal to the specified process or group of processes. @@ -3822,7 +3822,7 @@ Interrupt signal. @end deffn waitpid -@c snarfed from posix.c:451 +@c snarfed from posix.c:452 @deffn primitive waitpid pid [options] This procedure collects status information from a child process which has terminated or (optionally) stopped. Normally it will @@ -3868,7 +3868,7 @@ The integer status value. @end deffn status:exit-val -@c snarfed from posix.c:478 +@c snarfed from posix.c:479 @deffn primitive status:exit-val status Return the exit status value, as would be set if a process ended normally through a call to @code{exit} or @code{_exit}, @@ -3876,40 +3876,40 @@ if any, otherwise @code{#f}. @end deffn status:term-sig -@c snarfed from posix.c:498 +@c snarfed from posix.c:499 @deffn primitive status:term-sig status Return the signal number which terminated the process, if any, otherwise @code{#f}. @end deffn status:stop-sig -@c snarfed from posix.c:516 +@c snarfed from posix.c:517 @deffn primitive status:stop-sig status Return the signal number which stopped the process, if any, otherwise @code{#f}. @end deffn getppid -@c snarfed from posix.c:533 +@c snarfed from posix.c:535 @deffn primitive getppid Return an integer representing the process ID of the parent process. @end deffn getuid -@c snarfed from posix.c:544 +@c snarfed from posix.c:546 @deffn primitive getuid Return an integer representing the current real user ID. @end deffn getgid -@c snarfed from posix.c:555 +@c snarfed from posix.c:557 @deffn primitive getgid Return an integer representing the current real group ID. @end deffn geteuid -@c snarfed from posix.c:569 +@c snarfed from posix.c:571 @deffn primitive geteuid Return an integer representing the current effective user ID. If the system does not support effective IDs, then the real ID @@ -3918,7 +3918,7 @@ system supports effective IDs. @end deffn getegid -@c snarfed from posix.c:587 +@c snarfed from posix.c:589 @deffn primitive getegid Return an integer representing the current effective group ID. If the system does not support effective IDs, then the real ID @@ -3927,7 +3927,7 @@ system supports effective IDs. @end deffn setuid -@c snarfed from posix.c:603 +@c snarfed from posix.c:605 @deffn primitive setuid id Sets both the real and effective user IDs to the integer @var{id}, provided the process has appropriate privileges. @@ -3935,7 +3935,7 @@ The return value is unspecified. @end deffn setgid -@c snarfed from posix.c:617 +@c snarfed from posix.c:619 @deffn primitive setgid id Sets both the real and effective group IDs to the integer @var{id}, provided the process has appropriate privileges. @@ -3943,7 +3943,7 @@ The return value is unspecified. @end deffn seteuid -@c snarfed from posix.c:633 +@c snarfed from posix.c:635 @deffn primitive seteuid id Sets the effective user ID to the integer @var{id}, provided the process has appropriate privileges. If effective IDs are not supported, the @@ -3953,7 +3953,7 @@ The return value is unspecified. @end deffn setegid -@c snarfed from posix.c:657 +@c snarfed from posix.c:659 @deffn primitive setegid id Sets the effective group ID to the integer @var{id}, provided the process has appropriate privileges. If effective IDs are not supported, the @@ -3963,14 +3963,14 @@ The return value is unspecified. @end deffn getpgrp -@c snarfed from posix.c:679 +@c snarfed from posix.c:681 @deffn primitive getpgrp Return an integer representing the current process group ID. This is the POSIX definition, not BSD. @end deffn setpgid -@c snarfed from posix.c:695 +@c snarfed from posix.c:697 @deffn primitive setpgid pid pgid Move the process @var{pid} into the process group @var{pgid}. @var{pid} or @var{pgid} must be integers: they can be zero to indicate the ID of the @@ -3980,7 +3980,7 @@ The return value is unspecified. @end deffn setsid -@c snarfed from posix.c:714 +@c snarfed from posix.c:716 @deffn primitive setsid Creates a new session. The current process becomes the session leader and is put in a new process group. The process will be detached @@ -3989,21 +3989,21 @@ The return value is an integer representing the new process group ID. @end deffn ttyname -@c snarfed from posix.c:728 +@c snarfed from posix.c:730 @deffn primitive ttyname port Return a string with the name of the serial terminal device underlying @var{port}. @end deffn ctermid -@c snarfed from posix.c:751 +@c snarfed from posix.c:753 @deffn primitive ctermid Return a string containing the file name of the controlling terminal for the current process. @end deffn tcgetpgrp -@c snarfed from posix.c:773 +@c snarfed from posix.c:776 @deffn primitive tcgetpgrp port Return the process group ID of the foreground process group associated with the terminal open on the file descriptor @@ -4017,7 +4017,7 @@ foreground. @end deffn tcsetpgrp -@c snarfed from posix.c:797 +@c snarfed from posix.c:800 @deffn primitive tcsetpgrp port pgid Set the foreground process group ID for the terminal used by the file descriptor underlying @var{port} to the integer @var{pgid}. @@ -4027,7 +4027,7 @@ controlling terminal. The return value is unspecified. @end deffn execl -@c snarfed from posix.c:857 +@c snarfed from posix.c:860 @deffn primitive execl filename . args Executes the file named by @var{path} as a new process image. The remaining arguments are supplied to the process; from a C program @@ -4043,7 +4043,7 @@ call, but we call it @code{execl} because of its Scheme calling interface. @end deffn execlp -@c snarfed from posix.c:878 +@c snarfed from posix.c:881 @deffn primitive execlp filename . args Similar to @code{execl}, however if @var{filename} does not contain a slash @@ -4055,7 +4055,7 @@ call, but we call it @code{execlp} because of its Scheme calling interface. @end deffn execle -@c snarfed from posix.c:929 +@c snarfed from posix.c:932 @deffn primitive execle filename env . args Similar to @code{execl}, but the environment of the new process is specified by @var{env}, which must be a list of strings as returned by the @@ -4066,7 +4066,7 @@ call, but we call it @code{execle} because of its Scheme calling interface. @end deffn primitive-fork -@c snarfed from posix.c:953 +@c snarfed from posix.c:956 @deffn primitive primitive-fork Creates a new "child" process by duplicating the current "parent" process. In the child the return value is 0. In the parent the return value is @@ -4077,14 +4077,14 @@ with the scsh fork. @end deffn uname -@c snarfed from posix.c:968 +@c snarfed from posix.c:971 @deffn primitive uname Return an object with some information about the computer system the program is running on. @end deffn environ -@c snarfed from posix.c:997 +@c snarfed from posix.c:1001 @deffn primitive environ [env] If @var{env} is omitted, return the current environment (in the Unix sense) as a list of strings. Otherwise set the current @@ -4096,7 +4096,7 @@ then the return value is unspecified. @end deffn tmpnam -@c snarfed from posix.c:1035 +@c snarfed from posix.c:1039 @deffn primitive tmpnam Return a name in the file system that does not match any existing file. However there is no guarantee that another @@ -4106,7 +4106,7 @@ Care should be taken if opening the file, e.g., use the @end deffn mkstemp! -@c snarfed from posix.c:1058 +@c snarfed from posix.c:1061 @deffn primitive mkstemp! tmpl Create a new unique file in the file system and returns a new buffered port open for reading and writing to the file. @@ -4116,7 +4116,7 @@ place to return the name of the temporary file. @end deffn utime -@c snarfed from posix.c:1086 +@c snarfed from posix.c:1087 @deffn primitive utime pathname [actime [modtime]] @code{utime} sets the access and modification times for the file named by @var{path}. If @var{actime} or @var{modtime} is @@ -4131,7 +4131,7 @@ modification time to the current time. @end deffn access? -@c snarfed from posix.c:1135 +@c snarfed from posix.c:1136 @deffn primitive access? path how Return @code{#t} if @var{path} corresponds to an existing file and the current process has the type of access specified by @@ -4157,13 +4157,13 @@ test for existence of the file. @end deffn getpid -@c snarfed from posix.c:1150 +@c snarfed from posix.c:1151 @deffn primitive getpid Return an integer representing the current process ID. @end deffn putenv -@c snarfed from posix.c:1167 +@c snarfed from posix.c:1168 @deffn primitive putenv str Modifies the environment of the current process, which is also the default environment inherited by child processes. @@ -4179,7 +4179,7 @@ The return value is unspecified. @end deffn setlocale -@c snarfed from posix.c:1198 +@c snarfed from posix.c:1199 @deffn primitive setlocale category [locale] If @var{locale} is omitted, return the current value of the specified locale category as a system-dependent string. @@ -4192,7 +4192,7 @@ the locale will be set using envirionment variables. @end deffn mknod -@c snarfed from posix.c:1239 +@c snarfed from posix.c:1240 @deffn primitive mknod path type perms dev Creates a new special file, such as a file corresponding to a device. @var{path} specifies the name of the file. @var{type} should @@ -4212,7 +4212,7 @@ The return value is unspecified. @end deffn nice -@c snarfed from posix.c:1286 +@c snarfed from posix.c:1287 @deffn primitive nice incr Increment the priority of the current process by @var{incr}. A higher priority value means that the process runs less often. @@ -4220,21 +4220,21 @@ The return value is unspecified. @end deffn sync -@c snarfed from posix.c:1301 +@c snarfed from posix.c:1302 @deffn primitive sync Flush the operating system disk buffers. The return value is unspecified. @end deffn crypt -@c snarfed from posix.c:1314 +@c snarfed from posix.c:1315 @deffn primitive crypt key salt Encrypt @var{key} using @var{salt} as the salt value to the crypt(3) library call @end deffn chroot -@c snarfed from posix.c:1337 +@c snarfed from posix.c:1338 @deffn primitive chroot path Change the root directory to that specified in @var{path}. This directory will be used for path names beginning with @@ -4244,7 +4244,7 @@ root directory. @end deffn getlogin -@c snarfed from posix.c:1355 +@c snarfed from posix.c:1356 @deffn primitive getlogin Return a string containing the name of the user logged in on the controlling terminal of the process, or @code{#f} if this @@ -4252,7 +4252,7 @@ information cannot be obtained. @end deffn cuserid -@c snarfed from posix.c:1373 +@c snarfed from posix.c:1374 @deffn primitive cuserid Return a string containing a user name associated with the effective user id of the process. Return @code{#f} if this @@ -4260,7 +4260,7 @@ information cannot be obtained. @end deffn getpriority -@c snarfed from posix.c:1398 +@c snarfed from posix.c:1399 @deffn primitive getpriority which who Return the scheduling priority of the process, process group or user, as indicated by @var{which} and @var{who}. @var{which} @@ -4275,7 +4275,7 @@ specified processes. @end deffn setpriority -@c snarfed from posix.c:1432 +@c snarfed from posix.c:1433 @deffn primitive setpriority which who prio Set the scheduling priority of the process, process group or user, as indicated by @var{which} and @var{who}. @var{which} @@ -4293,7 +4293,7 @@ The return value is not specified. @end deffn getpass -@c snarfed from posix.c:1457 +@c snarfed from posix.c:1458 @deffn primitive getpass prompt Display @var{prompt} to the standard error output and read a password from @file{/dev/tty}. If this file is not @@ -4305,7 +4305,7 @@ characters is disabled. @end deffn flock -@c snarfed from posix.c:1496 +@c snarfed from posix.c:1497 @deffn primitive flock file operation Apply or remove an advisory lock on an open file. @var{operation} specifies the action to be done: @@ -4327,7 +4327,7 @@ file descriptor or an open file descriptior port. @end deffn sethostname -@c snarfed from posix.c:1522 +@c snarfed from posix.c:1523 @deffn primitive sethostname name Set the host name of the current processor to @var{name}. May only be used by the superuser. The return value is not @@ -4335,7 +4335,7 @@ specified. @end deffn gethostname -@c snarfed from posix.c:1538 +@c snarfed from posix.c:1539 @deffn primitive gethostname Return the host name of the current processor. @end deffn @@ -4350,7 +4350,7 @@ and @code{print-options}. @end deffn simple-format -@c snarfed from print.c:980 +@c snarfed from print.c:976 @deffn primitive simple-format destination message . args Write @var{message} to @var{destination}, defaulting to the current output port. @@ -4366,26 +4366,26 @@ containing the formatted text. Does not add a trailing newline. @end deffn newline -@c snarfed from print.c:1045 +@c snarfed from print.c:1041 @deffn primitive newline [port] Send a newline to @var{port}. @end deffn write-char -@c snarfed from print.c:1060 +@c snarfed from print.c:1056 @deffn primitive write-char chr [port] Send character @var{chr} to @var{port}. @end deffn port-with-print-state -@c snarfed from print.c:1114 +@c snarfed from print.c:1110 @deffn primitive port-with-print-state port pstate Create a new port which behaves like @var{port}, but with an included print state @var{pstate}. @end deffn get-print-state -@c snarfed from print.c:1129 +@c snarfed from print.c:1125 @deffn primitive get-print-state port Return the print state of the port @var{port}. If @var{port} has no associated print state, @code{#f} is returned. @@ -4474,7 +4474,7 @@ See @code{primitive-property-ref} for the significance of @end deffn primitive-property-ref -@c snarfed from properties.c:83 +@c snarfed from properties.c:84 @deffn primitive primitive-property-ref prop obj Return the property @var{prop} of @var{obj}. When no value has yet been associated with @var{prop} and @var{obj}, call @@ -4486,13 +4486,13 @@ default value of @var{prop}. @end deffn primitive-property-set! -@c snarfed from properties.c:111 +@c snarfed from properties.c:115 @deffn primitive primitive-property-set! prop obj val Associate @var{code} with @var{prop} and @var{obj}. @end deffn primitive-property-del! -@c snarfed from properties.c:131 +@c snarfed from properties.c:136 @deffn primitive primitive-property-del! prop obj Remove any value associated with @var{prop} and @var{obj}. @end deffn @@ -4596,14 +4596,14 @@ Return a new random state using @var{seed}. @end deffn random:uniform -@c snarfed from random.c:418 +@c snarfed from random.c:419 @deffn primitive random:uniform [state] Return a uniformly distributed inexact real random number in [0,1). @end deffn random:normal -@c snarfed from random.c:433 +@c snarfed from random.c:434 @deffn primitive random:normal [state] Return an inexact real in a normal distribution. The distribution used has mean 0 and standard deviation 1. For a @@ -4612,7 +4612,7 @@ normal distribution with mean m and standard deviation d use @end deffn random:solid-sphere! -@c snarfed from random.c:489 +@c snarfed from random.c:490 @deffn primitive random:solid-sphere! v [state] Fills vect with inexact real random numbers the sum of whose squares is less than 1.0. @@ -4623,7 +4623,7 @@ The sum of the squares of the numbers is returned. @end deffn random:hollow-sphere! -@c snarfed from random.c:512 +@c snarfed from random.c:513 @deffn primitive random:hollow-sphere! v [state] Fills vect with inexact real random numbers the sum of whose squares is equal to 1.0. @@ -4634,7 +4634,7 @@ unit n-shere. @end deffn random:normal-vector! -@c snarfed from random.c:530 +@c snarfed from random.c:531 @deffn primitive random:normal-vector! v [state] Fills vect with inexact real random numbers that are independent and standard normally distributed @@ -4642,7 +4642,7 @@ independent and standard normally distributed @end deffn random:exp -@c snarfed from random.c:554 +@c snarfed from random.c:556 @deffn primitive random:exp [state] Return an inexact real in an exponential distribution with mean 1. For an exponential distribution with mean u use (* u @@ -4725,7 +4725,7 @@ or @code{#f} otherwise. @end deffn make-regexp -@c snarfed from regex-posix.c:179 +@c snarfed from regex-posix.c:184 @deffn primitive make-regexp pat . flags Compile the regular expression described by @var{pat}, and return the compiled regexp structure. If @var{pat} does not @@ -4765,7 +4765,7 @@ one which comes last will override the earlier one. @end deffn regexp-exec -@c snarfed from regex-posix.c:226 +@c snarfed from regex-posix.c:232 @deffn primitive regexp-exec rx str [start [flags]] Match the compiled regular expression @var{rx} against @code{str}. If the optional integer @var{start} argument is @@ -4914,7 +4914,7 @@ Sends a specified signal @var{sig} to the current process, where @end deffn system -@c snarfed from simpos.c:76 +@c snarfed from simpos.c:78 @deffn primitive system [cmd] Execute @var{cmd} using the operating system's "command processor". Under Unix this is usually the default shell @@ -4926,7 +4926,7 @@ indicating whether the command processor is available. @end deffn getenv -@c snarfed from simpos.c:104 +@c snarfed from simpos.c:106 @deffn primitive getenv nam Looks up the string @var{name} in the current environment. The return value is @code{#f} unless a string of the form @code{NAME=VALUE} is @@ -4934,7 +4934,7 @@ found, in which case the string @code{VALUE} is returned. @end deffn primitive-exit -@c snarfed from simpos.c:120 +@c snarfed from simpos.c:122 @deffn primitive primitive-exit [status] Terminate the current process without unwinding the Scheme stack. This is would typically be useful after a fork. The exit status @@ -4974,7 +4974,7 @@ a C unsigned long integer. @end deffn socket -@c snarfed from socket.c:158 +@c snarfed from socket.c:161 @deffn primitive socket family style proto Return a new socket port of the type specified by @var{family}, @var{style} and @var{protocol}. All three parameters are @@ -4990,7 +4990,7 @@ has been connected to another socket. @end deffn socketpair -@c snarfed from socket.c:180 +@c snarfed from socket.c:183 @deffn primitive socketpair family style proto Return a pair of connected (but unnamed) socket ports of the type specified by @var{family}, @var{style} and @var{protocol}. @@ -5000,7 +5000,7 @@ family. Zero is likely to be the only meaningful value for @end deffn getsockopt -@c snarfed from socket.c:209 +@c snarfed from socket.c:213 @deffn primitive getsockopt sock level optname Return the value of a particular socket option for the socket port @var{socket}. @var{level} is an integer code for type of @@ -5013,7 +5013,7 @@ returns a pair of integers. @end deffn setsockopt -@c snarfed from socket.c:277 +@c snarfed from socket.c:281 @deffn primitive setsockopt sock level optname value Sets the value of a particular socket option for the socket port @var{socket}. @var{level} is an integer code for type of option @@ -5029,7 +5029,7 @@ The return value is unspecified. @end deffn shutdown -@c snarfed from socket.c:381 +@c snarfed from socket.c:385 @deffn primitive shutdown sock how Sockets can be closed simply by using @code{close-port}. The @code{shutdown} procedure allows reception or tranmission on a @@ -5051,7 +5051,7 @@ The return value is unspecified. @end deffn connect -@c snarfed from socket.c:474 +@c snarfed from socket.c:478 @deffn primitive connect sock fam address . args Initiates a connection from @var{socket} to the address specified by @var{address} and possibly @var{arg @dots{}}. The format @@ -5070,7 +5070,7 @@ The return value is unspecified. @end deffn bind -@c snarfed from socket.c:528 +@c snarfed from socket.c:532 @deffn primitive bind sock fam address . args Assigns an address to the socket port @var{socket}. Generally this only needs to be done for server sockets, @@ -5111,7 +5111,7 @@ The return value is unspecified. @end deffn listen -@c snarfed from socket.c:561 +@c snarfed from socket.c:565 @deffn primitive listen sock backlog This procedure enables @var{socket} to accept connection requests. @var{backlog} is an integer specifying @@ -5123,7 +5123,7 @@ The return value is unspecified. @end deffn accept -@c snarfed from socket.c:637 +@c snarfed from socket.c:641 @deffn primitive accept sock Accepts a connection on a bound, listening socket @var{socket}. If there are no pending connections in the queue, it waits until @@ -5142,7 +5142,7 @@ connection and will continue to accept new requests. @end deffn getsockname -@c snarfed from socket.c:668 +@c snarfed from socket.c:672 @deffn primitive getsockname sock Return the address of @var{socket}, in the same form as the object returned by @code{accept}. On many systems the address @@ -5150,7 +5150,7 @@ of a socket in the @code{AF_FILE} namespace cannot be read. @end deffn getpeername -@c snarfed from socket.c:695 +@c snarfed from socket.c:699 @deffn primitive getpeername sock Return the address of the socket that the socket @var{socket} is connected to, in the same form as the object returned by @@ -5159,7 +5159,7 @@ is connected to, in the same form as the object returned by @end deffn recv! -@c snarfed from socket.c:730 +@c snarfed from socket.c:734 @deffn primitive recv! sock buf [flags] Receives data from the socket port @var{socket}. @var{socket} must already be bound to the address from which data is to be received. @@ -5179,7 +5179,7 @@ any unread buffered port data is ignored. @end deffn send -@c snarfed from socket.c:759 +@c snarfed from socket.c:763 @deffn primitive send sock message [flags] Transmits the string @var{message} on the socket port @var{socket}. @var{socket} must already be bound to a destination address. The @@ -5193,7 +5193,7 @@ any unflushed buffered port data is ignored. @end deffn recvfrom! -@c snarfed from socket.c:797 +@c snarfed from socket.c:805 @deffn primitive recvfrom! sock str [flags [start [end]]] Return data from the socket port @var{socket} and also information about where the data was received from. @@ -5215,7 +5215,7 @@ descriptor: any unread buffered port data is ignored. @end deffn sendto -@c snarfed from socket.c:848 +@c snarfed from socket.c:856 @deffn primitive sendto sock message fam address . args_and_flags Transmits the string @var{message} on the socket port @var{socket}. The destination address is specified using the @var{family}, @var{address} and @@ -5462,14 +5462,14 @@ Return @code{#t} if @var{frame} is an overflow frame. @end deffn get-internal-real-time -@c snarfed from stime.c:141 +@c snarfed from stime.c:142 @deffn primitive get-internal-real-time Return the number of time units since the interpreter was started. @end deffn times -@c snarfed from stime.c:183 +@c snarfed from stime.c:187 @deffn primitive times Return an object with information about real and processor time. The following procedures accept such an object as an @@ -5494,7 +5494,7 @@ terminated child processes. @end deffn get-internal-run-time -@c snarfed from stime.c:214 +@c snarfed from stime.c:219 @deffn primitive get-internal-run-time Return the number of time units of processor time used by the interpreter. Both @emph{system} and @emph{user} time are @@ -5502,14 +5502,14 @@ included but subprocesses are not. @end deffn current-time -@c snarfed from stime.c:224 +@c snarfed from stime.c:229 @deffn primitive current-time Return the number of seconds since 1970-01-01 00:00:00 UTC, excluding leap seconds. @end deffn gettimeofday -@c snarfed from stime.c:241 +@c snarfed from stime.c:247 @deffn primitive gettimeofday Return a pair containing the number of seconds and microseconds since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note: @@ -5518,7 +5518,7 @@ operating system. @end deffn localtime -@c snarfed from stime.c:341 +@c snarfed from stime.c:347 @deffn primitive localtime time [zone] Return an object representing the broken down components of @var{time}, an integer like the one returned by @@ -5528,7 +5528,7 @@ optionally specified by @var{zone} (a string), otherwise the @end deffn gmtime -@c snarfed from stime.c:413 +@c snarfed from stime.c:419 @deffn primitive gmtime time Return an object representing the broken down components of @var{time}, an integer like the one returned by @@ -5536,7 +5536,7 @@ Return an object representing the broken down components of @end deffn mktime -@c snarfed from stime.c:475 +@c snarfed from stime.c:481 @deffn primitive mktime sbd_time [zone] @var{bd-time} is an object representing broken down time and @code{zone} is an optional time zone specifier (otherwise the TZ environment variable @@ -5549,7 +5549,7 @@ as @var{bd-time} but with normalized values. @end deffn tzset -@c snarfed from stime.c:548 +@c snarfed from stime.c:554 @deffn primitive tzset Initialize the timezone from the TZ environment variable or the system default. It's not usually necessary to call this procedure @@ -5558,7 +5558,7 @@ timezone. @end deffn strftime -@c snarfed from stime.c:565 +@c snarfed from stime.c:571 @deffn primitive strftime format stime Formats a time specification @var{time} using @var{template}. @var{time} is an object with time components in the form returned by @code{localtime} @@ -5570,7 +5570,7 @@ is the formatted string. @end deffn strptime -@c snarfed from stime.c:663 +@c snarfed from stime.c:669 @deffn primitive strptime format string Performs the reverse action to @code{strftime}, parsing @var{string} according to the specification supplied in @@ -5592,30 +5592,20 @@ Return @code{#t} iff @var{obj} is a string, else returns @end deffn read-only-string? -@c snarfed from strings.c:85 +@c snarfed from strings.c:78 @deffn primitive read-only-string? obj -Return true if @var{obj} can be read as a string, - -This illustrates the difference between @code{string?} and -@code{read-only-string?}: - -@lisp -(string? "a string") @result{} #t -(string? 'a-symbol) @result{} #f - -(read-only-string? "a string") @result{} #t -(read-only-string? 'a-symbol) @result{} #t -@end lisp +Return @code{#t} if @var{obj} is either a string or a symbol, +otherwise return @code{#f}. @end deffn list->string -@c snarfed from strings.c:94 +@c snarfed from strings.c:87 @deffn primitive list->string scm_string @end deffn string -@c snarfed from strings.c:100 +@c snarfed from strings.c:93 @deffn primitive string . chrs @deffnx primitive list->string chrs Return a newly allocated string composed of the arguments, @@ -5623,7 +5613,7 @@ Return a newly allocated string composed of the arguments, @end deffn make-string -@c snarfed from strings.c:253 +@c snarfed from strings.c:246 @deffn primitive make-string k [chr] Return a newly allocated string of length @var{k}. If @var{chr} is given, then all elements of @@ -5632,20 +5622,20 @@ of the @var{string} are unspecified. @end deffn string-length -@c snarfed from strings.c:286 +@c snarfed from strings.c:279 @deffn primitive string-length string Return the number of characters in @var{string}. @end deffn string-ref -@c snarfed from strings.c:297 +@c snarfed from strings.c:290 @deffn primitive string-ref str k Return character @var{k} of @var{str} using zero-origin indexing. @var{k} must be a valid index of @var{str}. @end deffn string-set! -@c snarfed from strings.c:314 +@c snarfed from strings.c:307 @deffn primitive string-set! str k chr Store @var{chr} in element @var{k} of @var{str} and return an unspecified value. @var{k} must be a valid index of @@ -5653,7 +5643,7 @@ an unspecified value. @var{k} must be a valid index of @end deffn substring -@c snarfed from strings.c:337 +@c snarfed from strings.c:330 @deffn primitive substring str start [end] Return a newly allocated string formed from the characters of @var{str} beginning with index @var{start} (inclusive) and @@ -5665,14 +5655,14 @@ exact integers satisfying: @end deffn string-append -@c snarfed from strings.c:360 +@c snarfed from strings.c:353 @deffn primitive string-append . args Return a newly allocated string whose characters form the concatenation of the given strings, @var{args}. @end deffn make-shared-substring -@c snarfed from strings.c:400 +@c snarfed from strings.c:393 @deffn primitive make-shared-substring str [start [end]] Return a shared substring of @var{str}. The semantics are the same as for the @code{substring} function: the shared substring @@ -5684,7 +5674,7 @@ occupies the same storage space as @var{str}. @end deffn string-index -@c snarfed from strop.c:121 +@c snarfed from strop.c:116 @deffn primitive string-index str chr [frm [to]] Return the index of the first occurrence of @var{chr} in @var{str}. The optional integer arguments @var{frm} and @@ -5704,7 +5694,7 @@ procedure essentially implements the @code{index} or @end deffn string-rindex -@c snarfed from strop.c:152 +@c snarfed from strop.c:146 @deffn primitive string-rindex str chr [frm [to]] Like @code{string-index}, but search from the right of the string rather than from the left. This procedure essentially @@ -5723,19 +5713,19 @@ the C library. @end deffn substring-move-left! -@c snarfed from strop.c:169 +@c snarfed from strop.c:163 @deffn primitive substring-move-left! scm_substring_move_x @end deffn substring-move-right! -@c snarfed from strop.c:170 +@c snarfed from strop.c:164 @deffn primitive substring-move-right! scm_substring_move_x @end deffn substring-move! -@c snarfed from strop.c:244 +@c snarfed from strop.c:238 @deffn primitive substring-move! str1 start1 end1 str2 start2 @deffnx primitive substring-move-left! str1 start1 end1 str2 start2 @deffnx primitive substring-move-right! str1 start1 end1 str2 start2 @@ -5758,7 +5748,7 @@ are different strings, it does not matter which function you use. @end deffn substring-fill! -@c snarfed from strop.c:280 +@c snarfed from strop.c:274 @deffn primitive substring-fill! str start end fill Change every character in @var{str} between @var{start} and @var{end} to @var{fill}. @@ -5771,7 +5761,7 @@ y @end deffn string-null? -@c snarfed from strop.c:307 +@c snarfed from strop.c:299 @deffn primitive string-null? str Return @code{#t} if @var{str}'s length is nonzero, and @code{#f} otherwise. @@ -5783,7 +5773,7 @@ y @result{} "foo" @end deffn string->list -@c snarfed from strop.c:323 +@c snarfed from strop.c:313 @deffn primitive string->list str Return a newly allocated list of the characters that make up the given string @var{str}. @code{string->list} and @@ -5792,20 +5782,20 @@ concerned. @end deffn string-copy -@c snarfed from strop.c:348 +@c snarfed from strop.c:338 @deffn primitive string-copy str Return a newly allocated copy of the given @var{string}. @end deffn string-fill! -@c snarfed from strop.c:361 +@c snarfed from strop.c:351 @deffn primitive string-fill! str chr Store @var{char} in every element of the given @var{string} and return an unspecified value. @end deffn string-upcase! -@c snarfed from strop.c:397 +@c snarfed from strop.c:386 @deffn primitive string-upcase! str Destructively upcase every character in @var{str} and return @var{str}. @@ -5817,14 +5807,14 @@ y @result{} "ARRDEFG" @end deffn string-upcase -@c snarfed from strop.c:409 +@c snarfed from strop.c:399 @deffn primitive string-upcase str Return a freshly allocated string containing the characters of @var{str} in upper case. @end deffn string-downcase! -@c snarfed from strop.c:444 +@c snarfed from strop.c:431 @deffn primitive string-downcase! str Destructively downcase every character in @var{str} and return @var{str}. @@ -5836,14 +5826,14 @@ y @result{} "arrdefg" @end deffn string-downcase -@c snarfed from strop.c:456 +@c snarfed from strop.c:444 @deffn primitive string-downcase str Return a freshly allocation string containing the characters in @var{str} in lower case. @end deffn string-capitalize! -@c snarfed from strop.c:493 +@c snarfed from strop.c:488 @deffn primitive string-capitalize! str Upcase the first character of every word in @var{str} destructively and return @var{str}. @@ -5855,7 +5845,7 @@ y @result{} "Hello World" @end deffn string-capitalize -@c snarfed from strop.c:505 +@c snarfed from strop.c:502 @deffn primitive string-capitalize str Return a freshly allocated string with the characters in @var{str}, where the first character of every word is @@ -5863,7 +5853,7 @@ capitalized. @end deffn string-ci->symbol -@c snarfed from strop.c:517 +@c snarfed from strop.c:516 @deffn primitive string-ci->symbol str Return the symbol whose name is @var{str}. @var{str} is converted to lowercase before the conversion is done, if Guile @@ -5899,28 +5889,28 @@ is lexicographically less than @var{s2}. @end deffn string<=? -@c snarfed from strorder.c:171 +@c snarfed from strorder.c:170 @deffn primitive string<=? s1 s2 Lexicographic ordering predicate; return @code{#t} if @var{s1} is lexicographically less than or equal to @var{s2}. @end deffn string>? -@c snarfed from strorder.c:185 +@c snarfed from strorder.c:184 @deffn primitive string>? s1 s2 Lexicographic ordering predicate; return @code{#t} if @var{s1} is lexicographically greater than @var{s2}. @end deffn string>=? -@c snarfed from strorder.c:200 +@c snarfed from strorder.c:198 @deffn primitive string>=? s1 s2 Lexicographic ordering predicate; return @code{#t} if @var{s1} is lexicographically greater than or equal to @var{s2}. @end deffn string-ci? -@c snarfed from strorder.c:269 +@c snarfed from strorder.c:267 @deffn primitive string-ci>? s1 s2 Case insensitive lexicographic ordering predicate; return @code{#t} if @var{s1} is lexicographically greater than @@ -5944,7 +5934,7 @@ Case insensitive lexicographic ordering predicate; return @end deffn string-ci>=? -@c snarfed from strorder.c:284 +@c snarfed from strorder.c:282 @deffn primitive string-ci>=? s1 s2 Case insensitive lexicographic ordering predicate; return @code{#t} if @var{s1} is lexicographically greater than or @@ -6182,7 +6172,7 @@ Return @code{#t} if @var{obj} is a symbol, otherwise return @end deffn symbol->string -@c snarfed from symbols.c:451 +@c snarfed from symbols.c:453 @deffn primitive symbol->string s Return the name of @var{symbol} as a string. If the symbol was part of an object returned as the value of a literal expression @@ -6208,7 +6198,7 @@ standard case is lower case: @end deffn string->symbol -@c snarfed from symbols.c:478 +@c snarfed from symbols.c:483 @deffn primitive string->symbol string Return the symbol whose name is @var{string}. This procedure can create symbols with names containing special characters or @@ -6231,7 +6221,7 @@ standard case is lower case: @end deffn string->obarray-symbol -@c snarfed from symbols.c:499 +@c snarfed from symbols.c:505 @deffn primitive string->obarray-symbol o s [softp] Intern a new symbol in @var{obarray}, a symbol table, with name @var{string}. @@ -6249,7 +6239,7 @@ table; instead, simply return @code{#f}. @end deffn intern-symbol -@c snarfed from symbols.c:531 +@c snarfed from symbols.c:537 @deffn primitive intern-symbol o s Add a new symbol to @var{obarray} with name @var{string}, bound to an unspecified initial value. The symbol table is not modified if a symbol @@ -6257,7 +6247,7 @@ with this name is already present. @end deffn unintern-symbol -@c snarfed from symbols.c:568 +@c snarfed from symbols.c:574 @deffn primitive unintern-symbol o s Remove the symbol with name @var{string} from @var{obarray}. This function returns @code{#t} if the symbol was present and @code{#f} @@ -6265,7 +6255,7 @@ otherwise. @end deffn symbol-binding -@c snarfed from symbols.c:609 +@c snarfed from symbols.c:615 @deffn primitive symbol-binding o s Look up in @var{obarray} the symbol whose name is @var{string}, and return the value to which it is bound. If @var{obarray} is @code{#f}, @@ -6274,14 +6264,14 @@ use the global symbol table. If @var{string} is not interned in @end deffn symbol-interned? -@c snarfed from symbols.c:626 +@c snarfed from symbols.c:632 @deffn primitive symbol-interned? o s Return @code{#t} if @var{obarray} contains a symbol with name @var{string}, and @code{#f} otherwise. @end deffn symbol-bound? -@c snarfed from symbols.c:649 +@c snarfed from symbols.c:655 @deffn primitive symbol-bound? o s Return @code{#t} if @var{obarray} contains a symbol with name @var{string} bound to a defined value. This differs from @@ -6292,7 +6282,7 @@ value. @end deffn symbol-set! -@c snarfed from symbols.c:667 +@c snarfed from symbols.c:673 @deffn primitive symbol-set! o s v Find the symbol in @var{obarray} whose name is @var{string}, and rebind it to @var{value}. An error is signalled if @var{string} is not present @@ -6300,44 +6290,44 @@ in @var{obarray}. @end deffn symbol-fref -@c snarfed from symbols.c:684 +@c snarfed from symbols.c:690 @deffn primitive symbol-fref s Return the contents of @var{symbol}'s @dfn{function slot}. @end deffn symbol-pref -@c snarfed from symbols.c:695 +@c snarfed from symbols.c:701 @deffn primitive symbol-pref s Return the @dfn{property list} currently associated with @var{symbol}. @end deffn symbol-fset! -@c snarfed from symbols.c:706 +@c snarfed from symbols.c:712 @deffn primitive symbol-fset! s val Change the binding of @var{symbol}'s function slot. @end deffn symbol-pset! -@c snarfed from symbols.c:718 +@c snarfed from symbols.c:724 @deffn primitive symbol-pset! s val Change the binding of @var{symbol}'s property slot. @end deffn symbol-hash -@c snarfed from symbols.c:732 +@c snarfed from symbols.c:738 @deffn primitive symbol-hash symbol Return a hash value for @var{symbol}. @end deffn builtin-bindings -@c snarfed from symbols.c:769 +@c snarfed from symbols.c:775 @deffn primitive builtin-bindings Create and return a copy of the global symbol table, removing all unbound symbols. @end deffn gensym -@c snarfed from symbols.c:790 +@c snarfed from symbols.c:796 @deffn primitive gensym [prefix] Create a new symbol with a name constructed from a prefix and a counter value. The string @var{prefix} can be specified as @@ -6347,7 +6337,7 @@ resetting the counter. @end deffn gentemp -@c snarfed from symbols.c:829 +@c snarfed from symbols.c:835 @deffn primitive gentemp [prefix [obarray]] Create a new symbol with a name unique in an obarray. The name is constructed from an optional string @var{prefix} @@ -6365,7 +6355,7 @@ Return an integer corresponding to the type of X. Deprecated. @end deffn catch -@c snarfed from throw.c:529 +@c snarfed from throw.c:535 @deffn primitive catch key thunk handler Invoke @var{thunk} in the dynamic context of @var{handler} for exceptions matching @var{key}. If thunk throws to the symbol @@ -6384,7 +6374,7 @@ match this call to @code{catch}. @end deffn lazy-catch -@c snarfed from throw.c:556 +@c snarfed from throw.c:562 @deffn primitive lazy-catch key thunk handler This behaves exactly like @code{catch}, except that it does not unwind the stack (this is the major difference), and if @@ -6392,7 +6382,7 @@ handler returns, its value is returned from the throw. @end deffn throw -@c snarfed from throw.c:589 +@c snarfed from throw.c:595 @deffn primitive throw key . args Invoke the catch form matching @var{key}, passing @var{args} to the @var{handler}. @@ -6483,7 +6473,7 @@ it can be otherwise arbitrary. A simple example: @end deffn transpose-array -@c snarfed from unif.c:802 +@c snarfed from unif.c:804 @deffn primitive transpose-array ra . args Return an array sharing contents with @var{array}, but with dimensions arranged in a different order. There must be one @@ -6505,7 +6495,7 @@ have smaller rank than @var{array}. @end deffn enclose-array -@c snarfed from unif.c:911 +@c snarfed from unif.c:913 @deffn primitive 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 @@ -6531,20 +6521,20 @@ examples: @end deffn array-in-bounds? -@c snarfed from unif.c:994 +@c snarfed from unif.c:997 @deffn primitive array-in-bounds? v . args Return @code{#t} if its arguments would be acceptable to @code{array-ref}. @end deffn array-ref -@c snarfed from unif.c:1073 +@c snarfed from unif.c:1076 @deffn primitive array-ref scm_uniform_vector_ref @end deffn uniform-vector-ref -@c snarfed from unif.c:1079 +@c snarfed from unif.c:1083 @deffn primitive uniform-vector-ref v args @deffnx primitive array-ref v . args Return the element at the @code{(index1, index2)} element in @@ -6552,13 +6542,13 @@ Return the element at the @code{(index1, index2)} element in @end deffn uniform-array-set1! -@c snarfed from unif.c:1248 +@c snarfed from unif.c:1252 @deffn primitive uniform-array-set1! scm_array_set_x @end deffn array-set! -@c snarfed from unif.c:1257 +@c snarfed from unif.c:1261 @deffn primitive array-set! v obj . args @deffnx primitive uniform-array-set1! v obj args Sets the element at the @code{(index1, index2)} element in @var{array} to @@ -6566,7 +6556,7 @@ Sets the element at the @code{(index1, index2)} element in @var{array} to @end deffn array-contents -@c snarfed from unif.c:1372 +@c snarfed from unif.c:1376 @deffn primitive array-contents ra [strict] @deffnx primitive array-contents array strict If @var{array} may be @dfn{unrolled} into a one dimensional shared array @@ -6582,7 +6572,7 @@ memory. @end deffn uniform-array-read! -@c snarfed from unif.c:1486 +@c snarfed from unif.c:1490 @deffn primitive uniform-array-read! ra [port_or_fd [start [end]]] @deffnx primitive uniform-vector-read! uve [port-or-fdes] [start] [end] Attempts to read all elements of @var{ura}, in lexicographic order, as @@ -6602,7 +6592,7 @@ returned by @code{(current-input-port)}. @end deffn uniform-array-write -@c snarfed from unif.c:1649 +@c snarfed from unif.c:1653 @deffn primitive uniform-array-write v [port_or_fd [start [end]]] @deffnx primitive uniform-vector-write uve [port-or-fdes] [start] [end] Writes all elements of @var{ura} as binary objects to @@ -6619,14 +6609,14 @@ omitted, in which case it defaults to the value returned by @end deffn bit-count -@c snarfed from unif.c:1774 +@c snarfed from unif.c:1778 @deffn primitive bit-count b bitvector Return the number of occurrences of the boolean @var{b} in @var{bitvector}. @end deffn bit-position -@c snarfed from unif.c:1813 +@c snarfed from unif.c:1817 @deffn primitive bit-position item v k Return the minimum index of an occurrence of @var{bool} in @var{bv} which is at least @var{k}. If no @var{bool} occurs @@ -6634,7 +6624,7 @@ within the specified range @code{#f} is returned. @end deffn bit-set*! -@c snarfed from unif.c:1881 +@c snarfed from unif.c:1885 @deffn primitive bit-set*! v kv 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 @@ -6648,7 +6638,7 @@ of @var{bv} corresponding to the indexes in uve are set to @end deffn bit-count* -@c snarfed from unif.c:1935 +@c snarfed from unif.c:1939 @deffn primitive bit-count* v kv obj Return @lisp @@ -6658,20 +6648,20 @@ Return @end deffn bit-invert! -@c snarfed from unif.c:1999 +@c snarfed from unif.c:2003 @deffn primitive bit-invert! v Modifies @var{bv} by replacing each element with its negation. @end deffn array->list -@c snarfed from unif.c:2077 +@c snarfed from unif.c:2082 @deffn primitive array->list v Return a list consisting of all the elements, in order, of @var{array}. @end deffn list->uniform-array -@c snarfed from unif.c:2169 +@c snarfed from unif.c:2175 @deffn primitive list->uniform-array ndim prot lst @deffnx procedure list->uniform-vector prot lst Return a uniform array of the type indicated by prototype @@ -6681,7 +6671,7 @@ done. @end deffn array-prototype -@c snarfed from unif.c:2520 +@c snarfed from unif.c:2526 @deffn primitive array-prototype ra Return an object that would produce an array of the same type as @var{array}, if used as the @var{prototype} for @@ -6689,7 +6679,7 @@ as @var{array}, if used as the @var{prototype} for @end deffn values -@c snarfed from values.c:83 +@c snarfed from values.c:80 @deffn primitive values . args Delivers all of its arguments to its continuation. Except for continuations created by the @code{call-with-values} procedure, @@ -6698,28 +6688,8 @@ passing no value or more than one value to continuations that were not created by @code{call-with-values} is unspecified. @end deffn - call-with-values -@c snarfed from values.c:116 -@deffn primitive call-with-values producer consumer -Calls its @var{producer} argument with no values and a -continuation that, when passed some values, calls the -@var{consumer} procedure with those values as arguments. The -continuation for the call to @var{consumer} is the continuation -of the call to @code{call-with-values}. - -@example -(call-with-values (lambda () (values 4 5)) - (lambda (a b) b)) - ==> 5 - -@end example -@example -(call-with-values * -) ==> -1 -@end example -@end deffn - make-variable -@c snarfed from variable.c:100 +@c snarfed from variable.c:99 @deffn primitive make-variable init [name_hint] Return a variable object initialized to value @var{init}. If given, uses @var{name-hint} as its internal (debugging) @@ -6729,7 +6699,7 @@ variable may exist, so @var{name-hint} is just that---a hint. @end deffn make-undefined-variable -@c snarfed from variable.c:124 +@c snarfed from variable.c:119 @deffn primitive make-undefined-variable [name_hint] Return a variable object initialized to an undefined value. If given, uses @var{name-hint} as its internal (debugging) @@ -6739,14 +6709,14 @@ variable may exist, so @var{name-hint} is just that---a hint. @end deffn variable? -@c snarfed from variable.c:145 +@c snarfed from variable.c:136 @deffn primitive variable? obj Return @code{#t} iff @var{obj} is a variable object, else return @code{#f} @end deffn variable-ref -@c snarfed from variable.c:157 +@c snarfed from variable.c:148 @deffn primitive variable-ref var Dereference @var{var} and return its value. @var{var} must be a variable object; see @code{make-variable} @@ -6754,7 +6724,7 @@ and @code{make-undefined-variable}. @end deffn variable-set! -@c snarfed from variable.c:171 +@c snarfed from variable.c:162 @deffn primitive variable-set! var val Set the value of the variable @var{var} to @var{val}. @var{var} must be a variable object, @var{val} can be any @@ -6762,7 +6732,7 @@ value. Return an unspecified value. @end deffn builtin-variable -@c snarfed from variable.c:185 +@c snarfed from variable.c:176 @deffn primitive builtin-variable name Return the built-in variable with the name @var{name}. @var{name} must be a symbol (not a string). @@ -6770,7 +6740,7 @@ Then use @code{variable-ref} to access its value. @end deffn variable-bound? -@c snarfed from variable.c:213 +@c snarfed from variable.c:204 @deffn primitive variable-bound? var Return @code{#t} iff @var{var} is bound to a value. Throws an error if @var{var} is not a variable object. @@ -6790,7 +6760,7 @@ scm_vector @end deffn vector -@c snarfed from vectors.c:177 +@c snarfed from vectors.c:178 @deffn primitive vector . l @deffnx primitive list->vector l Return a newly allocated vector whose elements contain the @@ -6801,7 +6771,7 @@ given arguments. Analogous to @code{list}. @end deffn make-vector -@c snarfed from vectors.c:255 +@c snarfed from vectors.c:264 @deffn primitive make-vector k [fill] Return a newly allocated vector of @var{k} elements. If a second argument is given, then each element is initialized to @@ -6810,7 +6780,7 @@ unspecified. @end deffn vector->list -@c snarfed from vectors.c:311 +@c snarfed from vectors.c:321 @deffn primitive vector->list v Return a newly allocated list of the objects contained in the elements of @var{vector}. @@ -6821,20 +6791,20 @@ elements of @var{vector}. @end deffn vector-fill! -@c snarfed from vectors.c:328 +@c snarfed from vectors.c:338 @deffn primitive vector-fill! v fill Store @var{fill} in every element of @var{vector}. The value returned by @code{vector-fill!} is unspecified. @end deffn vector-move-left! -@c snarfed from vectors.c:355 +@c snarfed from vectors.c:365 @deffn primitive vector-move-left! vec1 start1 end1 vec2 start2 Vector version of @code{substring-move-left!}. @end deffn vector-move-right! -@c snarfed from vectors.c:378 +@c snarfed from vectors.c:388 @deffn primitive vector-move-right! vec1 start1 end1 vec2 start2 Vector version of @code{substring-move-right!}. @end deffn @@ -6869,7 +6839,7 @@ version numbers, respectively. @end deffn make-soft-port -@c snarfed from vports.c:184 +@c snarfed from vports.c:190 @deffn primitive make-soft-port pv modes Return a port capable of receiving or delivering characters as specified by the @var{modes} string (@pxref{File Ports, @@ -6910,7 +6880,7 @@ For example: @end deffn make-weak-vector -@c snarfed from weaks.c:62 +@c snarfed from weaks.c:63 @deffn primitive make-weak-vector size [fill] Return a weak vector with @var{size} elements. If the optional argument @var{fill} is given, all entries in the vector will be @@ -6919,13 +6889,13 @@ empty list. @end deffn list->weak-vector -@c snarfed from weaks.c:79 +@c snarfed from weaks.c:80 @deffn primitive list->weak-vector scm_weak_vector @end deffn weak-vector -@c snarfed from weaks.c:87 +@c snarfed from weaks.c:88 @deffn primitive weak-vector . l @deffnx primitive list->weak-vector l Construct a weak vector from a list: @code{weak-vector} uses @@ -6935,14 +6905,14 @@ the same way @code{list->vector} would. @end deffn weak-vector? -@c snarfed from weaks.c:110 +@c snarfed from weaks.c:116 @deffn primitive weak-vector? obj Return @code{#t} if @var{obj} is a weak vector. Note that all weak hashes are also weak vectors. @end deffn make-weak-key-hash-table -@c snarfed from weaks.c:130 +@c snarfed from weaks.c:138 @deffn primitive make-weak-key-hash-table size @deffnx primitive make-weak-value-hash-table size @deffnx primitive make-doubly-weak-hash-table size @@ -6954,21 +6924,21 @@ would modify regular hash tables. (@pxref{Hash Tables}) @end deffn make-weak-value-hash-table -@c snarfed from weaks.c:147 -@deffn primitive make-weak-value-hash-table k +@c snarfed from weaks.c:155 +@deffn primitive make-weak-value-hash-table size Return a hash table with weak values with @var{size} buckets. (@pxref{Hash Tables}) @end deffn make-doubly-weak-hash-table -@c snarfed from weaks.c:165 -@deffn primitive make-doubly-weak-hash-table k +@c snarfed from weaks.c:173 +@deffn primitive make-doubly-weak-hash-table size Return a hash table with weak keys and values with @var{size} buckets. (@pxref{Hash Tables}) @end deffn weak-key-hash-table? -@c snarfed from weaks.c:184 +@c snarfed from weaks.c:192 @deffn primitive weak-key-hash-table? obj @deffnx primitive weak-value-hash-table? obj @deffnx primitive doubly-weak-hash-table? obj @@ -6978,13 +6948,13 @@ nor a weak value hash table. @end deffn weak-value-hash-table? -@c snarfed from weaks.c:194 -@deffn primitive weak-value-hash-table? x -Return @code{#t} if @var{x} is a weak value hash table. +@c snarfed from weaks.c:202 +@deffn primitive weak-value-hash-table? obj +Return @code{#t} if @var{obj} is a weak value hash table. @end deffn doubly-weak-hash-table? -@c snarfed from weaks.c:204 -@deffn primitive doubly-weak-hash-table? x -Return @code{#t} if @var{x} is a doubly weak hash table. +@c snarfed from weaks.c:212 +@deffn primitive doubly-weak-hash-table? obj +Return @code{#t} if @var{obj} is a doubly weak hash table. @end deffn diff --git a/doc/scheme-data.texi b/doc/scheme-data.texi index d317ba5a7..cd982ab34 100755 --- a/doc/scheme-data.texi +++ b/doc/scheme-data.texi @@ -1346,8 +1346,6 @@ called with string containing unusal characters. * Alphabetic Case Mapping:: Convert the alphabetic case of strings. * Appending Strings:: Appending strings to form a new string. * String Miscellanea:: Miscellaneous string procedures. -* Shared Substrings:: Strings which share memory with each other. -* Read Only Strings:: Treating certain non-strings as strings. @end menu @node String Syntax @@ -1772,122 +1770,6 @@ is currently reading symbols case--insensitively. @end deffn -@node Shared Substrings -@subsection Shared Substrings - -[FIXME: this is pasted in from Tom Lord's original guile.texi and should -be reviewed] - -@c FIXME::martin: Shared substrings are gone, so this section should die. - -Whenever you extract a substring using @code{substring}, the Scheme -interpreter allocates a new string and copies data from the old string. -This is expensive, but @code{substring} is so convenient for -manipulating text that programmers use it often. - -Guile Scheme provides the concept of the @dfn{shared substring} to -improve performance of many substring-related operations. A shared -substring is an object that mostly behaves just like an ordinary -substring, except that it actually shares storage space with its parent -string. - -@deffn primitive make-shared-substring str [start [end]] -Return a shared substring of @var{str}. The semantics are the -same as for the @code{substring} function: the shared substring -returned includes all of the text from @var{str} between -indexes @var{start} (inclusive) and @var{end} (exclusive). If -@var{end} is omitted, it defaults to the end of @var{str}. The -shared substring returned by @code{make-shared-substring} -occupies the same storage space as @var{str}. -@end deffn - -Example: - -@example -(define foo "the quick brown fox") -(define bar (make-shared-substring some-string 4 9)) - -foo => "t h e q u i c k b r o w n f o x" -bar =========> |---------| -@end example - -The shared substring @var{bar} is not given its own storage space. -Instead, the Guile interpreter notes internally that @var{bar} points to -a portion of the memory allocated to @var{foo}. However, @var{bar} -behaves like an ordinary string in most respects: it may be used with -string primitives like @code{string-length}, @code{string-ref}, -@code{string=?}. Guile makes the necessary translation between indices -of @var{bar} and indices of @var{foo} automatically. - -@example -(string-length? bar) @result{} 5 ; bar only extends from indices 4 to 9 -(string-ref bar 3) @result{} #\c ; same as (string-ref foo 7) -(make-shared-substring bar 2) - @result{} "ick" ; can even make a shared substring! -@end example - -Because creating a shared substring does not require allocating new -storage from the heap, it is a very fast operation. However, because it -shares memory with its parent string, a change to the contents of the -parent string will implicitly change the contents of its shared -substrings. - -@example -(string-set! foo 7 #\r) -bar @result{} "quirk" -@end example - -Guile considers shared substrings to be immutable. This is because -programmers might not always be aware that a given string is really a -shared substring, and might innocently try to mutate it without -realizing that the change would affect its parent string. (We are -currently considering a "copy-on-write" strategy that would permit -modifying shared substrings without affecting the parent string.) - -In general, shared substrings are useful in circumstances where it is -important to divide a string into smaller portions, but you do not -expect to change the contents of any of the strings involved. - -@node Read Only Strings -@subsection Read Only Strings - -@c FIXME::martin: Read-only strings are gone, too, so this section should -@c also die. - -Type-checking in Guile primitives distinguishes between mutable strings -and read only strings. Mutable strings answer @code{#t} to -@code{string?} while read only strings may or may not. All kinds of -strings, whether or not they are mutable return #t to this: - -@deffn primitive read-only-string? obj -Return true if @var{obj} can be read as a string, - -This illustrates the difference between @code{string?} and -@code{read-only-string?}: - -@lisp -(string? "a string") @result{} #t -(string? 'a-symbol) @result{} #f - -(read-only-string? "a string") @result{} #t -(read-only-string? 'a-symbol) @result{} #t -@end lisp -@end deffn - -"Read-only" refers to how the string will be used, not how the string is -permitted to be used. In particular, all strings are "read-only -strings" even if they are mutable, because a function that only reads -from a string can certainly operate on even a mutable string. - -Symbols are an example of read-only strings. Many string functions, -such as @code{string-append} are happy to operate on symbols. Many -functions that expect a string argument, such as @code{open-file}, will -accept a symbol as well. - -Shared substrings, discussed in the previous chapter, also happen to be -read-only strings. - - @node Regular Expressions @section Regular Expressions diff --git a/libguile/ChangeLog b/libguile/ChangeLog index 28dcdc262..cdcae34d7 100644 --- a/libguile/ChangeLog +++ b/libguile/ChangeLog @@ -1,3 +1,8 @@ +2001-04-09 Neil Jerram + + * strings.c (scm_read_only_string_p): Update docstring to reflect + current (non-)usage of "read only" strings. + 2001-04-06 Martin Grabmueller * hooks.c (scm_make_hook, scm_make_hook_with_name), diff --git a/libguile/strings.c b/libguile/strings.c index 70d831907..476493eef 100644 --- a/libguile/strings.c +++ b/libguile/strings.c @@ -74,15 +74,8 @@ SCM_DEFINE (scm_string_p, "string?", 1, 0, 0, SCM_DEFINE (scm_read_only_string_p, "read-only-string?", 1, 0, 0, (SCM obj), - "Return true if @var{obj} can be read as a string,\n\n" - "This illustrates the difference between @code{string?} and\n" - "@code{read-only-string?}:\n\n" - "@lisp\n" - "(string? \"a string\") @result{} #t\n" - "(string? 'a-symbol) @result{} #f\n\n" - "(read-only-string? \"a string\") @result{} #t\n" - "(read-only-string? 'a-symbol) @result{} #t\n" - "@end lisp") + "Return @code{#t} if @var{obj} is either a string or a symbol,\n" + "otherwise return @code{#f}.") #define FUNC_NAME s_scm_read_only_string_p { return SCM_BOOL(SCM_ROSTRINGP (obj));