magmalake flare_mlake

flare_mlake · API · io

flare.io.buf_reader

Buffered reader for stream I/O.

Wraps any type that implements the Readable trait and provides line-oriented reading (readline, read_until, read_exact). All reads go through an internal buffer so that the underlying stream is called as infrequently as possible.

Example: ```mojo from flare.tcp import TcpStream from flare.io import BufReader

var stream = TcpStream.connect("example.com", 80)
var reader = BufReader(stream^)
var line = reader.readline() # Read one HTTP header line
```

Structs

BufReader

struct BufReader[S: Readable]

A buffered byte reader wrapping any Readable stream.

Reduces the number of syscalls by reading ahead into an internal buffer and serving readline / read_until / read_exact from that buffer.

Fields: _stream: The underlying stream (owned). _buf: Internal ring buffer. _pos: Byte offset of the next unread byte in _buf. _len: Number of valid bytes in _buf starting at _pos.

Example:

from flare.tcp import TcpStream
from flare.io import BufReader

var s = TcpStream.connect("example.com", 80)
var r = BufReader(s^)
s.write_all("GET / HTTP/1.0\r\nHost: example.com\r\n\r\n".as_bytes())
while True:
    var line = r.readline()
    if len(line) == 0:
        break
    print(line)
Parameters
S: Any type implementing the Readable trait (e.g. TcpStream).

Implements Movable

__init__

def __init__(out self, var stream: S, capacity: Int = Int(8192))

Wrap stream with a read buffer of capacity bytes.

Args
stream: The underlying Readable stream (ownership taken).
capacity: Internal buffer size in bytes (default 8192).

readline

def readline(mut self) -> String

Read one line terminated by \n (LF) from the stream.

The newline character is stripped from the returned string. \r\n (CRLF) is also handled — the \r is stripped too.

Example:

var line = reader.readline() # e.g. "HTTP/1.1 200 OK"

Raises NetworkError: On any I/O error.

read_until

def read_until(mut self, delimiter: UInt8) -> String

Read bytes until delimiter is encountered.

The delimiter itself is consumed but not included in the result.

Example:

var field = reader.read_until(ord(","))
Args
delimiter: The byte value to stop at.

Raises NetworkError: On any I/O error.

read_exact

def read_exact(mut self, n: Int) -> List[UInt8]

Read exactly n bytes from the stream.

Loops until n bytes have been accumulated or EOF/error.

Example:

var header = reader.read_exact(4)
Args
n: Number of bytes to read.

Raises NetworkError: If EOF is reached before n bytes are available.

Traits

Readable

A byte stream that can be read into a mutable buffer.

Extends Movable so that streams can be transferred into BufReader. Implementors must provide read — all other helpers (read_exact, etc.) are layered on top by BufReader.

Example: mojo struct MyStream(Readable): def read(mut self, buf: Pointer[UInt8, _], size: Int) raises -> Int: ...

Implements Movable

read

def read(mut self, buf: Pointer[UInt8], size: Int) -> Int

Read up to size bytes into the buffer at buf.

Args
buf: Destination pointer. The caller must own at least size bytes of initialised storage at this address.
size: Maximum number of bytes to read.

Raises NetworkError: On any I/O error.