Buffered

Buffers reads and writes over another Io.

Reads fetch ahead, and writes are held back until the buffer fills, a read or seek needs the handle, or the buffer is flushed or closed. A buffer is not closed when it is garbage collected, so close it to keep its pending writes, or use it from a block that closes it.

A buffer reads lines and text as well as bytes. Text must be UTF-8, and line endings are not translated. Iterating it yields lines.

A function that accepts an Io reads and writes through the buffer, so the buffer stays consistent and open afterward.

Errors

Exception	Condition
StateError	The buffer is closed, or its source does not read, write, or seek as the method needs
DataError	Text read is not valid UTF-8

A failure of the source raises its own error, such as a sys.Error from a file, or the exception a Do stream raised.

Example

fs.open data.txt buffer: false do |raw|
  let file = Buffered $raw
  let header = file.read_line()
  for line = file.chomp()
    echo $line

Inherits from: Iter[Str], Io

Constructor

Buffered source

Buffers source, which stays open when the buffer closes.

Parameters

Name	Type	Description
source	Io	Byte source to buffer.

Methods

(iter)() -> Buffered

Returns the buffer as its own iterator.

(next)() -> Str

Reads the next line, as read_line does.

(put) value

Writes a value.

A Str or Bin contributes its own bytes, and anything else is converted to a string first. No line ending is appended.

Parameters

Name	Type	Description
value	Value	Value to write.

(sink)() -> Buffered

Returns the buffer as its own sink.

close()

Flushes and closes the buffer, leaving its source open.

The buffer is closed even if flushing fails. Closing a closed buffer does nothing.

flush()

Writes out pending writes.

lines() -> Buffered

Returns the buffer as an iterator over its lines.

read … -> Bin

Reads bytes.

A result shorter than size means the end of the stream was reached, and an empty one means it already had been.

Parameters

Name	Type	Description
size?	Int	Number of bytes to read. Without it, reads to the end of the stream.

read_line() -> Str

Reads the next line, including its terminator.

Returns

The line, or "" at the end of the stream. Only the last line can lack a terminator.

read_str … -> Str

Reads text.

A character that size would split is left for the next read, unless it is the first, which is read whole.

Parameters

Name	Type	Description
size?	Int	Number of bytes to read. Without it, reads to the end of the stream.

seek … -> Int

Moves the position, writing out pending writes and discarding read-ahead.

Parameters

Name	Type	Description
offset?	Int	Byte offset relative to the current position.
:start?	Int	Absolute byte offset from the start of the stream.
:end?	Int	Byte offset relative to the end of the stream.

Returns

The new absolute byte position.

Example

file.seek start: 10   # absolute
file.seek 10          # relative to the position
file.seek end: (0 - 1)  # relative to the end

tell() -> Int

Returns the logical position: where the next read or write happens.

write *data -> Int

Writes data, given in pieces.

The pieces are buffered together, so a flush writes them in one write of the source when they fit in the buffer.

Parameters

Name	Type	Description
*data	(Str | Bin)	Data to write.

Returns

The number of bytes written, which is all of them.