bufio
bufio provides io::stream implementations which provide buffered I/O
support, as well as scanner utility functions which pair well with buffered
streams for optimal efficiency.
Two streams are provided which can read from or write to byte slices. fixed
uses a caller-supplied statically-allocated buffer for storage, producing an
io::stream which reads from or writes to this buffer. In effect, this allows
the caller to statically allocate a byte array, then produce an io::stream
which writes to or reads from it. dynamic is similar, but it uses a
bufio-managed dynamically allocated buffer. This creates an io::stream which
efficiently soaks up writes into a dynamically allocated byte slice.
Both fixed and dynamic provide access to the underlying buffer via
buffer. The user may also call reset, which empties the buffer but does
not free the underlying storage, allowing the user to re-use the same buffer
for many operations.
A third stream implementation, buffered, is used to batch read and write
operations against an underlying stream. The caller may use small, frequent read
and write operations, which bufio will batch into larger, less frequent reads
and writes. The caller must supply either one or two temporary buffers for
reading and/or writing, which bufio will use to store future reads, or pending
writes, as necessary. This improves performance when many small reads or writes
would be inefficient, such as when I/O operations require syscalls or network
transmissions. Buffered streams also support an "unread" operation, which
allows you to "look-ahead" at future data without consuming it from the stream.
Finally, bufio provides several utilities for "scanning" streams, namely
scantok et al, which require small, frequent reads, or take advantage of
look-ahead, and thus are most efficient when paired with a buffered stream.
Index
Types
type bufstream;
type memstream;
Functions
fn buffer(*memstream) []u8;
fn buffered(io::handle, []u8, []u8) bufstream;
fn dynamic(io::mode) memstream;
fn dynamic_from([]u8, io::mode) memstream;
fn fixed([]u8, io::mode) memstream;
fn flush(io::handle) (io::error | void);
fn isbuffered(io::handle) bool;
fn reset(*memstream) void;
fn scanbyte(io::handle) (u8 | io::EOF | io::error);
fn scanline(io::handle) ([]u8 | io::EOF | io::error);
fn scanrune(io::handle) (rune | utf8::invalid | io::EOF | io::error);
fn scantok(io::handle, u8...) ([]u8 | io::EOF | io::error);
fn setflush(io::handle, []u8) void;
fn truncate(*memstream) (void | errors::unsupported);
fn unread(io::handle, []u8) void;
fn unreadrune(io::handle, rune) void;
Types
type bufstream
Show undocumented member
type bufstream = struct {
stream: io::stream,
source: io::handle,
rbuffer: []u8,
wbuffer: []u8,
ravail: size,
wavail: size,
flush: []u8,
};
type memstream
Show undocumented member
type memstream = struct {
stream: io::stream,
buf: []u8,
pos: size,
};
Functions
fn buffer
fn buffer(in: *memstream) []u8;
Returns the current buffer of a fixed or dynamic stream.
fn buffered
fn buffered(src: io::handle, rbuf: []u8, wbuf: []u8) bufstream;
Creates a stream which buffers reads and writes for the underlying stream.
This is generally used to improve performance of small reads/writes for
sources where I/O operations are costly, such as if they invoke a syscall or
take place over the network.
The caller should supply one or both of a read and write buffer as a slice of
the desired buffer, or empty slices if read or write functionality is
disabled. The same buffer may not be used for both reads and writes.
The caller is responsible for closing the underlying stream, and freeing the
provided buffers if necessary, after the buffered stream is closed.
let rbuf: [os::BUFSIZ]u8 = [0...];
let wbuf: [os::BUFSIZ]u8 = [0...];
let buffered = bufio::buffered(source, rbuf, wbuf);
fn dynamic
fn dynamic(mode: io::mode) memstream;
Creates an io::stream which dynamically allocates a buffer to store
writes 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. If a stream's data
is transferred via buffer, the stream shouldn't be closed as long as the
data is freed.
fn dynamic_from
fn dynamic_from(in: []u8, mode: io::mode) memstream;
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.
fn fixed
fn fixed(in: []u8, mode: io::mode) memstream;
Creates a stream for a fixed, caller-supplied buffer. All fixed streams are
seekable; seeking a write stream will cause subsequent writes to overwrite
existing contents of the buffer. The program aborts if writes would exceed
the buffer's capacity. The stream doesn't have to be closed.
fn flush
fn flush(s: io::handle) (io::error | void);
Flushes pending writes to the underlying stream.
fn isbuffered
fn isbuffered(in: io::handle) bool;
Returns true if an io::handle is a buffered stream.
fn reset
fn reset(in: *memstream) void;
Resets the dynamic buffer's length to zero, but keeps the allocated memory
around for future writes.
fn scanbyte
fn scanbyte(file: io::handle) (u8 | io::EOF | io::error);
Reads a single byte from an io::handle.
fn scanline
fn scanline(file: io::handle) ([]u8 | io::EOF | io::error);
Reads a slice of bytes until a newline character (\n, 0x0A). Newline itself
is not included. The return value must be freed by the caller.
fn scanrune
fn scanrune(file: io::handle) (rune | utf8::invalid | io::EOF | io::error);
Reads a rune from a UTF-8 stream.
fn scantok
fn scantok(file: io::handle, delim: u8...) ([]u8 | io::EOF | io::error);
Reads a slice of bytes until the delimiter. Delimiter is not included. The
return value must be freed by the caller.
fn setflush
fn setflush(s: io::handle, b: []u8) void;
Sets the list of bytes which will cause the stream to flush when written. By
default, the stream will flush when a newline (\n) is written.
fn truncate
fn truncate(in: *memstream) (void | errors::unsupported);
Truncates the dynamic buffer, freeing memory associated with it and setting
its length to zero.
fn unread
fn unread(s: io::handle, buf: []u8) void;
"Unreads" a slice of bytes, such that the next call to "read" will return
these bytes before reading any new data from the underlying source. The
unread data must fit into the read buffer's available space. The amount of
data which can be unread before the user makes any reads from a buffered
stream is equal to the length of the read buffer, and otherwise it is equal
to the length of the return value of the last call to io::read using this
buffered stream. Attempting to unread more data than can fit into the read
buffer will abort the program.
fn unreadrune
fn unreadrune(s: io::handle, rn: rune) void;
Unreads a rune; see unread.