bufio
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
type scanner = struct {
stream: io::stream,
src: io::handle,
buffer: []u8,
start: size,
pending: []u8,
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
Show undocumented member
type scanner = struct {
stream: io::stream,
src: io::handle,
buffer: []u8,
start: size,
pending: []u8,
maxread: size,
};
type stream
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
fn finish(scan: *scanner) void;
Frees resources associated with a scanner. Does not close the underlying I/O handle.
fn flush
fn flush(s: io::handle) (void | io::error);
Flushes pending writes to the underlying stream.
fn init
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
fn isbuffered(in: io::handle) bool;
Returns true if an io::handle is a stream.
fn newscanner
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
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
fn read_byte(h: io::handle) (u8 | io::EOF | io::error);
Reads a single byte from an io::handle.
fn read_line
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
fn read_rune(h: io::handle) (rune | utf8::invalid | io::EOF | io::error);
Reads a rune from a UTF-8 stream.
fn read_tok
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
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
fn scan_byte(scan: *scanner) (u8 | io::EOF | io::error);
Reads one byte from a scanner.
fn scan_bytes
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
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
fn scan_rune(scan: *scanner) (rune | io::EOF | io::error | utf8::invalid);
Reads one rune from a scanner.
fn scan_string
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
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
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.