bufio+x86_64 +linux

bufio provides an io::stream implementation which provides buffered I/O support, utility functions which pair well with buffered streams, and a scanner type which allocates and maintains its own read buffer.

A buffered stream is used to batch read and write operations against an underlying io::handle. bufio provides several utilities for reading from handles, namely read_tok et al. These functions require small, frequent reads, or take advantage of look-ahead, and thus are most efficient when paired with a buffered stream.

bufio also provides a "scanning" interface, with functions like scan_string which take in a scanner. Strings returned from scanning functions are borrowed from the scanner's read buffer, so allocated memory can be reused for future scans.

Index

Types

// Undocumented types:
type scanner = struct {
	stream: io::stream,
	src: io::handle,
	buffer: []u8,
	// Index of start of pending bytes in buffer
	start: size,
	// Sub-slice with pending bytes in buffer
	pending: []u8,
	// User-confirmed maximum size of read buffer
	maxread: size,
};
type stream = struct {
	stream: io::stream,
	source: io::handle,
	rbuffer: []u8,
	wbuffer: []u8,
	rpos: size,
	ravail: size,
	wavail: size,
	flush: []u8,
};

Functions

fn finish(scan: *scanner) void;
fn flush(s: io::handle) (void | io::error);
fn init(src: io::handle, rbuf: []u8, wbuf: []u8) stream;
fn isbuffered(in: io::handle) bool;
fn newscanner(src: io::handle, maxread: size = types::SIZE_MAX) scanner;
fn newscanner_static(src: io::handle, buffer: []u8) scanner;
fn read_byte(h: io::handle) (u8 | io::EOF | io::error);
fn read_line(h: io::handle) ([]u8 | io::EOF | io::error);
fn read_rune(h: io::handle) (rune | utf8::invalid | io::EOF | io::error);
fn read_tok(h: io::handle, delim: u8...) ([]u8 | io::EOF | io::error);
fn scan_buffer(scan: *scanner) []u8;
fn scan_byte(scan: *scanner) (u8 | io::EOF | io::error);
fn scan_bytes(scan: *scanner, delim: (u8 | []u8)) ([]u8 | io::EOF | io::error);
fn scan_line(scan: *scanner) (const str | io::EOF | io::error | utf8::invalid);
fn scan_rune(scan: *scanner) (rune | io::EOF | io::error | utf8::invalid);
fn scan_string(scan: *scanner, delim: str) (const str | io::EOF | io::error | utf8::invalid);
fn setflush(s: io::handle, b: []u8) void;
fn unread(s: io::handle, buf: []u8) void;
fn unreadrune(s: io::handle, rn: rune) void;

Types

type scanner[link]

Show undocumented member
type scanner = struct {
	stream: io::stream,
	src: io::handle,
	buffer: []u8,
	// Index of start of pending bytes in buffer
	start: size,
	// Sub-slice with pending bytes in buffer
	pending: []u8,
	// User-confirmed maximum size of read buffer
	maxread: size,
};

type stream[link]

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

Functions

fn finish[link]

fn finish(scan: *scanner) void;

Frees resources associated with a scanner. Does not close the underlying I/O handle.

fn flush[link]

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

Flushes pending writes to the underlying stream.

fn init[link]

fn init(src: io::handle, rbuf: []u8, wbuf: []u8) stream;

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::BUFSZ]u8 = [0...];
let wbuf: [os::BUFSZ]u8 = [0...];
let buffered = bufio::init(source, rbuf, wbuf);

fn isbuffered[link]

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

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

fn newscanner[link]

fn newscanner(src: io::handle, maxread: size = types::SIZE_MAX) scanner;

Creates a new scanner which will allocate and maintain a read buffer for efficient reading of a handle. The scanner will read ahead only up to maxread bytes, which defaults to types::SIZE_MAX if no limit is required. The user must free resources associated with the scanner using finish after use.

Reads from the scanner will return errors::overflow if maxread is reached.

fn newscanner_static[link]

fn newscanner_static(src: io::handle, buffer: []u8) scanner;

Creates a new scanner using a user-provided buffer. The scanner will return errors::overflow if the buffer length is reached, but will not perform any allocations. The user should not call finish after use unless they wish to free the underlying buffer through bufio.

fn read_byte[link]

fn read_byte(h: io::handle) (u8 | io::EOF | io::error);

Reads a single byte from an io::handle.

fn read_line[link]

fn read_line(h: io::handle) ([]u8 | io::EOF | io::error);

Reads a slice of bytes until a newline character (\n, 0x0A). Newline itself is not included but it is read from the handle. The return value must be freed by the caller.

fn read_rune[link]

fn read_rune(h: io::handle) (rune | utf8::invalid | io::EOF | io::error);

Reads a rune from a UTF-8 stream.

fn read_tok[link]

fn read_tok(h: io::handle, delim: u8...) ([]u8 | io::EOF | io::error);

Reads a slice of bytes until the delimiter. Delimiter is not included but it is read from the handle. The return value must be freed by the caller.

fn scan_buffer[link]

fn scan_buffer(scan: *scanner) []u8;

Returns the internal scanner buffer, which contains all bytes read ahead by the scanner up to this point.

fn scan_byte[link]

fn scan_byte(scan: *scanner) (u8 | io::EOF | io::error);

Reads one byte from a scanner.

fn scan_bytes[link]

fn scan_bytes(scan: *scanner, delim: (u8 | []u8)) ([]u8 | io::EOF | io::error);

Reads the next token from a scanner, delimited by delim. The delimiter is read from the source handle but not included in the returned slice. The return value is borrowed from the internal scanner buffer, which is invalidated during subsequent operations which use this scanner.

fn scan_line[link]

fn scan_line(scan: *scanner) (const str | io::EOF | io::error | utf8::invalid);

Scans the next line of text from a scanner. The return value is borrowed from the internal scanner buffer, which is invalidated during subsequent operations which use this scanner.

fn scan_rune[link]

fn scan_rune(scan: *scanner) (rune | io::EOF | io::error | utf8::invalid);

Reads one rune from a scanner.

fn scan_string[link]

fn scan_string(scan: *scanner, delim: str) (const str | io::EOF | io::error | utf8::invalid);

Scans a string of text from a scanner up to some delimiter. The delimiter is read from the source handle but not included in the returned string. The return value is borrowed from the internal scanner buffer, which is invalidated during subsequent operations which use this scanner.

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 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.