bufio +linux +x86_64

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

// Undocumented 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[link]

Show undocumented member 
type bufstream = struct {
	stream: io::stream,
	source: io::handle,
	rbuffer: []u8,
	wbuffer: []u8,
	ravail: size,
	wavail: size,
	flush: []u8,
};

type memstream[link]

Show undocumented member 
type memstream = struct {
	stream: io::stream,
	buf: []u8,
	pos: size,
};

Functions

fn buffer[link] 

fn buffer(in: *memstream) []u8;

Returns the current buffer of a fixed or dynamic stream.

fn buffered[link] 

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[link] 

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[link] 

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[link] 

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[link] 

fn flush(s: io::handle) (io::error | void);

Flushes pending writes to the underlying stream.

fn isbuffered[link] 

fn isbuffered(in: io::handle) bool;

Returns true if an io::handle is a buffered stream.

fn reset[link] 

fn reset(in: *memstream) void;

Resets the dynamic buffer's length to zero, but keeps the allocated memory around for future writes.

fn scanbyte[link] 

fn scanbyte(file: io::handle) (u8 | io::EOF | io::error);

Reads a single byte from an io::handle.

fn scanline[link] 

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[link] 

fn scanrune(file: io::handle) (rune | utf8::invalid | io::EOF | io::error);

Reads a rune from a UTF-8 stream.

fn scantok[link] 

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[link] 

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[link] 

fn truncate(in: *memstream) (void | errors::unsupported);

Truncates the dynamic buffer, freeing memory associated with it and setting its length to zero.

fn unread[link] 

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[link] 

fn unreadrune(s: io::handle, rn: rune) void;

Unreads a rune; see unread.