type scan_options[link]

type scan_options = enum uint {
	DEFAULT = EOF_DISCARD,
	// Upon encountering EOF, all bytes or characters between the
	// final token and EOF are discarded and EOF is returned
	// immediately.
	//
	// This option is recommended for use-cases where the user is
	// scanning over a file or buffer which may contain partial
	// content, and the user wishes to consume as many tokens as
	// possible and assume that additional data may follow EOF
	// before a new delimiter is written.
	//
	// This is the default behavior. Note that on Unix, text files
	// are always terminated with a new line, and [[scan_line]] will
	// enumerate all well-formed lines in a file with this flag --
	// however, when scanning ill-formed text files which include
	// text following the final line feed, this additional text will
	// be discarded.
	EOF_DISCARD = 0,
	// Upon encountering EOF, all bytes or characters between the
	// final token and EOF are treated as a token and returned to
	// the caller before returning EOF.
	//
	// This is recommended for use-cases where EOF is effectively
	// considered an additional delimiter between tokens, or where
	// the remainder of the file following the final delimiter is
	// meaningful.
	EOF_GREEDY = 1 << 0,
};

Options which fine-tune the behavior of a scanner.

type scanner[link]

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,
	// Change some scanning behaviors
	opts: scan_options,
};

type stream[link]

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

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, opts: scan_options = scan_options::DEFAULT) 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, opts: scan_options = scan_options::DEFAULT) 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.