iostream.stream.seek

Method of stream, from module "iostream"

instance.seek(offset: int, [origin: int]): int

Seeks to the given offset; origin is 'b' (begin), 'c' (current) or 'e' (end)

examples/iostream/stream/seek-basic.nut

from "iostream" import blob

let cargo = blob(4)
cargo.seek(2)
println("cargo.tell() =", cargo.tell())

Output:

cargo.tell() = 2

Parameters

`offset`	int	how far to move, in bytes
`origin`	int	`'b'` (begin), `'c'` (current) or `'e'` (end); defaults to `'b'` optional

Return value

0 when the target position is within [0, len()], and the cursor is now there. -1 when it falls outside that range; the cursor is left where it was, so a failed seek never leaves the stream half-moved.

Errors

Throws invalid origin when origin is not 'b', 'c' or 'e'.

Notes

The same method works on a file: 'b', 'c' and 'e' mean the same three origins, and the same 0/-1 convention reports success or an out-of-range target.

Example

examples/iostream/stream/seek.nut

from "iostream" import blob

let b = blob(4)
println("b.seek(2) =", b.seek(2))      // default origin 'b': absolute position
println("b.tell() after seek(2) =", b.tell())
println("b.seek(1, 'c') =", b.seek(1, 'c')) // relative to the current position
println("b.tell() after seek(1, 'c') =", b.tell())
println("b.seek(0, 'e') =", b.seek(0, 'e')) // relative to the end
println("b.tell() after seek(0, 'e') =", b.tell())

println("b.seek(5) =", b.seek(5))      // past len: out of range
println("b.tell() after seek(5) =", b.tell())       // cursor did not move

try { b.seek(0, 'z') } catch (e) { println("b.seek(0, 'z') throws:", e) }