summaryrefslogtreecommitdiff
path: root/doc/ref/api-io.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2013-01-22 10:12:59 +0100
committerAndy Wingo <wingo@pobox.com>2013-01-22 15:15:43 +0100
commit5a35d42aa5be26f1048fceea9acfa21bc9f6bc3e (patch)
tree783725e40a20fed1bf932eb020878047a62dc547 /doc/ref/api-io.texi
parent84f5a8251710c7d2a01590aa083d9dd409a56279 (diff)
downloadguile-5a35d42aa5be26f1048fceea9acfa21bc9f6bc3e.tar.gz
add read-string and read-string! to (ice-9 rdelim)
* module/ice-9/rdelim.scm (read-string!, read-string): New functions. * test-suite/tests/rdelim.test: Add tests. * doc/ref/api-io.texi: Add docs. * module/ice-9/iconv.scm: * module/rnrs/io/ports.scm: * module/web/uri.scm: Use the new functions.
Diffstat (limited to 'doc/ref/api-io.texi')
-rw-r--r--doc/ref/api-io.texi27
1 files changed, 27 insertions, 0 deletions
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index de3684c31..11ae5803a 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -577,6 +577,33 @@ used. This function is equivalent to:
@end lisp
@end deffn
+In the past, Guile did not have a procedure that would just read out all
+of the characters from a port. As a workaround, many people just called
+@code{read-delimited} with no delimiters, knowing that would produce the
+behavior they wanted. This prompted Guile developers to add some
+routines that would read all characters from a port. So it is that
+@code{(ice-9 rdelim)} is also the home for procedures that can reading
+undelimited text:
+
+@deffn {Scheme Procedure} read-string [port] [count]
+Read all of the characters out of @var{port} and return them as a
+string. If the @var{count} is present, treat it as a limit to the
+number of characters to read.
+
+By default, read from the current input port, with no size limit on the
+result. This procedure always returns a string, even if no characters
+were read.
+@end deffn
+
+@deffn {Scheme Procedure} read-string! buf [port] [start] [end]
+Fill @var{buf} with characters read from @var{port}, defaulting to the
+current input port. Return the number of characters read.
+
+If @var{start} or @var{end} are specified, store data only into the
+substring of @var{str} bounded by @var{start} and @var{end} (which
+default to the beginning and end of the string, respectively).
+@end deffn
+
Some of the aforementioned I/O functions rely on the following C
primitives. These will mainly be of interest to people hacking Guile
internals.