guile/guile-core/libguile ChangeLog ports.c

[Gary Houston]

CVSROOT:        /cvs
Module name:    guile
Branch:         branch_release-1-6
Changes by:     Gary Houston <address@hidden>   01/09/25 18:59:16

Modified files:
        guile-core/libguile: ChangeLog ports.c 

Log message:
        * ports.c (scm_drain_input): extended the docstring.  thanks to
        Alex Schroeder and Thien-Thi Nguyen.

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/libguile/ChangeLog.diff?cvsroot=OldCVS&only_with_tag=branch_release-1-6&tr1=1.1465.2.30&tr2=1.1465.2.31&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/libguile/ports.c.diff?cvsroot=OldCVS&only_with_tag=branch_release-1-6&tr1=1.153.2.2&tr2=1.153.2.3&r1=text&r2=text

Patches:
Index: guile/guile-core/libguile/ChangeLog
diff -u guile/guile-core/libguile/ChangeLog:1.1516 
guile/guile-core/libguile/ChangeLog:1.1517
--- guile/guile-core/libguile/ChangeLog:1.1516  Sun Sep 23 17:25:26 2001
+++ guile/guile-core/libguile/ChangeLog Tue Sep 25 18:46:13 2001
@@ -1,3 +1,8 @@
+2001-09-25  Gary Houston  <address@hidden>
+
+       * ports.c (scm_drain_input): extended the docstring.  thanks to
+       Alex Schroeder and Thien-Thi Nguyen.
+
 2001-09-23  Mikael Djurfeldt  <address@hidden>
 
        * validate.h (SCM_NUM2FLOAT, SCM_NUM2DOUBLE,
Index: guile/guile-core/libguile/ports.c
diff -u guile/guile-core/libguile/ports.c:1.156 
guile/guile-core/libguile/ports.c:1.157
--- guile/guile-core/libguile/ports.c:1.156     Fri Aug 31 10:42:31 2001
+++ guile/guile-core/libguile/ports.c   Tue Sep 25 18:46:13 2001
@@ -311,8 +311,19 @@
 /* Clear a port's read buffers, returning the contents.  */
 SCM_DEFINE (scm_drain_input, "drain-input", 1, 0, 0, 
             (SCM port),
-           "Drain @var{port}'s read buffers (including any pushed-back\n"
-           "characters) and return the content as a single string.")
+           "This procedure clears a port's input buffers, similar\n"
+           "to the way that force-output clears the output buffer.  The\n"
+           "contents of the buffers are returned as a single string, e.g.,\n"
+           "\n"
+           "@lisp\n"
+           "(define p (open-input-file ...))\n"
+           "(drain-input p) => empty string, nothing buffered yet.\n"
+           "(unread-char (read-char p) p)\n"
+           "(drain-input p) => initial chars from p, up to the buffer size.\n"
+           "@end lisp\n\n"
+           "Draining the buffers may be useful for cleanly finishing\n"
+           "buffered I/O so that the file descriptor can be used directly\n"
+           "for further input.")
 #define FUNC_NAME s_scm_drain_input
 {
   SCM result;