Io

A byte stream, such as an open fs.File.

Io is the common type of byte streams. A subclass defines the methods below that it supports, and the capability getters report which those are. One it does not define raises UnsupportedError, and its capabilities are false unless it overrides them.

The helpers, such as read_all, are written in terms of those methods. Reading text by size or by line needs read-ahead, so it is left to Buffered. An Io is a Sink of its bytes, but not iterable: iterate chunks, or iterate a subclass that supports it.

A function may return an Io over a native stream, such as a response body. Its close closes that stream.

A function that accepts an Io, such as zip.open, uses the stream without closing it. Afterward its position reflects what the function read or wrote, though a reader may have read ahead past what it used. Only the stream's own close closes it.

A function can also use a Do subclass's instance, which must report its capabilities. Strands call its read, write and seek as the function needs bytes, never its close. Don't use the stream yourself until the function is done with it.

An exception from one of its methods fails the function. A ValueError or TimedOutError fails it with the same class and message, and any other exception with a RuntimeError carrying its message. An error class from a native module can keep its class, as sys.Error keeps its class and code.

Example

class Memory: Io
  pub field data pos

  def (init) self data
    self.data = data
    self.pos = 0

  #[getter]
  pub def readable _self
    true

  pub def read self size
    let end = (self.pos + size)
    if (end > self.data.len)
      end = self.data.len
    let chunk = (self.data[self.pos..end])
    self.pos = end
    chunk

  pub def close _self
    nil

compress.decompress (Memory $fs.Path("data.gz").read()) do |stream|
  echo (stream.read_all_str())

Inherits from: Sink[Value]

Fields

readable @ Bool ^[get]: Whether the stream reads. A closed stream does not.
seekable @ Bool ^[get]: Whether the stream seeks. A closed stream does not.
writable @ Bool ^[get]: Whether the stream writes. A closed stream does not.

Methods

`(put) value`

Writes a value with write_all.

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)() -> Io`

Returns the stream as its own sink.

`chunks … -> Iter[Bin]`

Returns an iterator over the rest of the stream, one read per item.

Parameters

Name	Type	Description
`size?`	`Int`	Number of bytes to read per item. 65536 by default.

`close()`

Closes the stream.

`copy_to dest -> Int`

Puts the rest of the stream into a sink, in chunks.

Parameters

Name	Type	Description
`dest`	`BaseSinkable[Bin]`	Destination, such as another `Io`.

Returns

The number of bytes copied.

Example

let dest = fs.open copy.bin w
source.copy_to $dest
dest.close()

`read size -> Bin`

Reads bytes.

Parameters

Name	Type	Description
`size`	`Int`	Number of bytes to read.

Returns

At most size bytes. An empty result means the end of the stream.

`read_all() -> Bin`

Reads the rest of the stream.

`read_all_str() -> Str`

Reads the rest of the stream as text.

Errors

Exception	Condition
`DataError`	The text is not valid UTF-8

`seek … -> Int`

Moves the position.

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.

`write *data -> Int`

Writes data, given in pieces.

One call is one write, so a stream that writes in one operation keeps the pieces together. Pass a line and its terminator to one call rather than joining them first. Pieces stay together only as far as the stream does.

Parameters

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

Returns

The number of bytes written, counting through the pieces in order. It can be short, even partway through a piece.

`write_all *data`

Writes all of data, repeating write until it is written.

The first write gets every piece, and later ones get what the earlier ones left. The pieces stay together only when the first write takes them all.

Parameters

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

Errors

Exception	Condition
`RuntimeError`	A `write` reports no bytes written, or more than it was given