iostream.blob.seek

Method of blob, 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/blob/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
`origin`	int	`'b'` (begin), `'c'` (current) or `'e'` (end); defaults to `'b'` optional

Return value

See iostream.stream.seek for the generic contract.

Errors

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

Notes

'e' and the bounds of the seek are relative to len, not to any allocated capacity. Unlike readn and writen, a seek outside the blob does not throw: it just returns -1 and leaves the cursor where it was.

Example

examples/iostream/blob/seek.nut

from "iostream" import blob

let b = blob(4)
println("b.seek(2, 'b') =", b.seek(2, 'b'))   // ok: returns 0, cursor now 2
println("b.tell() after seek(2, 'b') =", 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 len
println("b.tell() after seek(0, 'e') =", b.tell())

println("b.seek(100, 'b') =", b.seek(100, 'b')) // out of range: returns -1, does not throw
println("b.tell() after seek(100, 'b') =", b.tell())         // cursor is unchanged

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