Reference

std/binary/reader

std/binary/src/reader.trb

ByteReader: typed reads from a cursor over bytes, each of which answers a ReadError where the bytes end.

type SignedEncoding

type SignedEncoding with Show, Equals, Hash

How a variable-length integer with a sign is written. Both are LEB128 underneath: seven bits to a byte, the lowest first, the highest bit of a byte set where another follows.

case SignExtended

case SignExtended

Two's complement, the sign bit of the last byte repeated upwards: signed LEB128 of WebAssembly and DWARF. -1 is the one byte 7f.

case Zigzag

case Zigzag

0, -1, 1, -2, ... mapped to 0, 1, 2, 3, ... and then written unsigned: protobuf's sint32 and sint64. -1 is the one byte 01.

type ByteReader

type ByteReader

A cursor over bytes that reads numbers, runs of bytes and text from them, and answers a ReadError instead of reading past the end: bytes from a file or the network cannot make it panic.

Every read moves the cursor past what it read, and a read that fails moves nothing. The byte order is the reader's, big endian unless it was made with another, and every read of a number can name its own:

var reader = ByteReader([0x12, 0x34, 0x78, 0x56])
print reader.uint16()
print reader.uint16(order: Some(.LittleEndian))

A reader is a value: a copy reads on from where the original stood without moving it, which is how a format looks ahead. ByteReader.limited answers a reader over the next bytes only, for a record whose length comes first.

field input

input: Bytes

The bytes the reader was made from. A limited reader holds the same ones and reads a window of them, so limiting copies nothing.

field order

order: ByteOrder = ByteOrder.BigEndian

The byte order of every read of a number that does not name one.

fn position

fn position(): Int

The next byte to read, counted from the start of this reader's bytes: 0 for a reader that has read nothing.

fn offset

fn offset(): Int

The next byte to read, counted from the start of input - the offset a ReadError names. It is ByteReader.position for a reader that is not limited.

fn remaining

fn remaining(): Int

How many bytes are left to read.

fn seek

var fn seek(position: Int): Result<Void, ReadError>

Moves the cursor to position, counted from the start of this reader's bytes; the end itself is a position too.

Errors

fn skip

var fn skip(count: Int): Result<Void, ReadError>

Moves the cursor past the next count bytes without reading them.

Errors

fn uint8

var fn uint8(): Result<UInt8, ReadError>

The next byte.

fn uint16

var fn uint16(order: ByteOrder? = None): Result<UInt16, ReadError>

The next two bytes as a UInt16, in order or the reader's.

fn uint32

var fn uint32(order: ByteOrder? = None): Result<UInt32, ReadError>

The next four bytes as a UInt32, in order or the reader's.

fn uint64

var fn uint64(order: ByteOrder? = None): Result<UInt64, ReadError>

The next eight bytes as a UInt64, in order or the reader's.

fn int8

var fn int8(): Result<Int8, ReadError>

The next byte as an Int8, in two's complement.

fn int16

var fn int16(order: ByteOrder? = None): Result<Int16, ReadError>

The next two bytes as an Int16, in two's complement and in order or the reader's.

fn int32

var fn int32(order: ByteOrder? = None): Result<Int32, ReadError>

The next four bytes as an Int32, in two's complement and in order or the reader's.

fn int64

var fn int64(order: ByteOrder? = None): Result<Int64, ReadError>

The next eight bytes as an Int64, in two's complement and in order or the reader's.

fn float32

var fn float32(order: ByteOrder? = None): Result<Float64, ReadError>

The next four bytes as an IEEE 754 binary32, in order or the reader's, widened to the Float64 that holds it exactly. A nan reads as Float64.nan, without its payload.

fn float64

var fn float64(order: ByteOrder? = None): Result<Float64, ReadError>

The next eight bytes as an IEEE 754 binary64, in order or the reader's. A nan reads without its payload.

fn varUInt

var fn varUInt(): Result<UInt64, ReadError>

An unsigned LEB128 of at most 10 bytes: protobuf's varint, WebAssembly's u32 and u64. A longer encoding of a small value (80 00 for 0) is read, as both formats allow.

Errors

fn varInt

var fn varInt(encoding: SignedEncoding = SignedEncoding.SignExtended): Result<Int64, ReadError>

A signed LEB128 of at most 10 bytes, in encoding: sign-extended by default, as WebAssembly and DWARF write it, or zigzag, as protobuf's sint64 does.

Errors

fn bytes

var fn bytes(count: Int): Result<Bytes, ReadError>

The next count bytes, as a range of input (docs/design/BINARY.md section 4 says what a range of a list costs: today it is a copy of the count bytes). A format that only looks at the bytes reads them with a ByteReader.limited reader instead, which copies nothing.

Errors

fn limited

var fn limited(count: Int): Result<Self, ReadError>

A reader over the next count bytes only, in this reader's order, and this reader moved past them: for a record whose length comes first. It holds the same input and reads a window of it, so nothing is copied; it counts its positions from 0 and its offsets, like every reader, from the start of input.

Errors

fn text

var fn text(count: Int): Result<String, ReadError>

The next count bytes as UTF-8 text.

Errors

fn terminatedText

var fn terminatedText(): Result<String, ReadError>

The UTF-8 text up to the next NUL byte, which is read too and is not part of the text: C's strings, gzip's file name.

Errors