fill-buf-adjust: new function.

* stream.c (fill_buf_adjust): New function.
(stream_init): Register fill-buf-adjust intrinsic.

* stream.h (fill_buf_adjust): Declared.

* txr.1: Documented.

1 files changed, 18 insertions, 1 deletions

diff --git a/txr.1 b/txr.1
index 5207606d..41d1568f 100644
--- a/txr.1
+++ b/txr.1
@@ -58014,9 +58014,10 @@ the length of the buffer.
 If an error occurs before any bytes are written, the function
 throws an error.
 
-.coNP Function @ fill-buf
+.coNP Functions @ fill-buf and @ fill-buf-adjust
 .synb
 .mets (fill-buf < buf >> [ pos <> [ stream ]])
+.mets (fill-buf-adjust < buf >> [ pos <> [ stream ]])
 .syne
 .desc
 The
@@ -58065,6 +58066,22 @@ any bytes are read, then an exception is thrown.
 If an end-of-file condition occurs before any bytes are read, then zero
 is returned.
 
+The
+.code fill-buf-adjust
+differs usefully from
+.code fill-buf
+as follows. Whereas
+.code fill-buf
+doesn't manipulate the length of the buffer at any stage of the operation, the
+.code fill-buf-adjust
+begins by adjusting the length of the buffer to the underlying allocated size.
+Then it performs the fill operation in
+exactly the same manner as
+.codn fill-buf .
+Finally, if the operation succeeds, then
+.code fill-buf-adjust
+adjusts the length of the buffer to match the position that is returned.
+
 .SS* Buffer streams
 A stream type exists which allows
 .code buf