iostream.stream.readblob

Method of stream, from module "iostream"

Reads up to size bytes and returns them as a blob

examples/iostream/stream/readblob-basic.nut

from "iostream" import blob

let cargo = blob(0)
cargo.writestring("gold")
cargo.seek(0)
println("cargo.readblob(4).as_string() =", cargo.readblob(4).as_string())

Output:

cargo.readblob(4).as_string() = gold

Parameters

size int the largest number of bytes to read

Return value

A new blob holding the bytes read. size is capped against len() first, so asking for more than the stream holds is not an error by itself; the result can be smaller still, capped again by how many bytes remain after the cursor. Only when that second cap leaves nothing, including when size itself was 0, does readblob throw instead of returning an empty blob.

Errors

Throws invalid size when size is negative.

Throws no data left to read when zero bytes could be read: the cursor is already at len(), or size capped down to 0.

Notes

The same method works on a file: it reads at the file's current position, capped the same way against the file's size.

Example

examples/iostream/stream/readblob.nut

from "iostream" import blob

let b = blob(4)
b.writen(0x01020304, 'i')
b.seek(2)
let r = b.readblob(10) // size is capped against len (4), not what remains (2)
println("r.len() =", r.len())         // only the 2 bytes actually available come back
println("b.tell() =", b.tell())

try { b.readblob(-1) } catch (e) { println("b.readblob(-1) throws:", e) }

b.seek(0, 'e')
try { b.readblob(1) } catch (e) { println("b.readblob(1) at eos throws:", e) } // cursor already at len