commit ec8a9995ecfc171720ec8f5e742e1704535712b3
parent fe1ded2711d50fc6a8877c3148823dbe7c8f9e23
Author: Drew DeVault <sir@cmpwn.com>
Date: Wed, 21 Apr 2021 11:45:20 -0400
bufio: docs improvements
Diffstat:
2 files changed, 22 insertions(+), 9 deletions(-)
diff --git a/bufio/README b/bufio/README
@@ -0,0 +1,12 @@
+bufio provides [[io::stream]] implementations which provide buffered I/O
+operations. The [[buffered]] stream will batch reads and writes for an
+underlying stream, using a caller-provided buffer as temporary storage. The
+[[dynamic]] and [[fixed]] streams produce an [[io::stream]] which reads from or
+writes to a data buffer (dynamically and statically allocated, respectively).
+
+Utilities for "scanning" a stream are also provided via [[scantok]] et al. These
+will work with any [[io::stream]], but are only efficient on a [[buffered]]
+stream.
+
+The use of a [[buffered]] stream also allows the caller to utilize the
+[[unread]] family of functions.
diff --git a/bufio/memstream.ha b/bufio/memstream.ha
@@ -9,9 +9,9 @@ type memstream = struct {
pos: size,
};
-// Creates an [[io::stream]] for a fixed, caller-supplied buffer. Supports either
-// read or write, but not both. Readable streams are seekable. The program
-// aborts if writes would exceed the buffer's capacity.
+// Creates an [[io::stream]] for a fixed, caller-supplied buffer. Supports
+// either read or write, but not both. Readable streams are seekable. The
+// program aborts if writes would exceed the buffer's capacity.
export fn fixed(in: []u8, mode: io::mode) *io::stream = {
let s = alloc(memstream {
stream = io::stream {
@@ -52,15 +52,16 @@ fn fixed_close(s: *io::stream) void = free(s);
// into. Subsequent reads will consume the buffered data. Upon failure to
// allocate sufficient memory to store writes, the program aborts.
//
-// Calling [[io::close]] on this stream will free the buffer. Call [[bufio::finish]]
-// instead to free up resources associated with the stream, but transfer
-// ownership of the buffer to the caller.
+// Calling [[io::close]] on this stream will free the buffer. Call
+// [[bufio::finish]] instead to free up resources associated with the stream,
+// but transfer ownership of the buffer to the caller.
export fn dynamic(mode: io::mode) *io::stream = dynamic_from([], mode);
-// Like [[dynamic]], but takes an existing slice as input. Writes are appended to
-// it and reads consume bytes from the initial buffer, plus any additional
+// Like [[dynamic]], but takes an existing slice as input. Writes are appended
+// to it and reads consume bytes from the initial buffer, plus any additional
// writes. Like [[dynamic]], calling [[io::close]] will free the buffer, and
-// [[bufio::finish]] can be used to return ownership of the buffer to the caller.
+// [[bufio::finish]] can be used to return ownership of the buffer to the
+// caller.
export fn dynamic_from(in: []u8, mode: io::mode) *io::stream = {
let s = alloc(memstream {
stream = io::stream {
