`std/binary/writer`

std/binary/src/writer.trb

ByteWriter: typed writes into a growable buffer, and Mark for a length that is written after what it counts.

type Mark

type Mark<Width>

Where a ByteWriter left room for a number of Width - a UInt16 or a UInt32 - that is written later with ByteWriter.patch: a length that is known only after what it counts.

fn position

fn position(): Int

The first byte of the room, counted from the start of the writer's bytes.

fn end

fn end(): Int

The first byte after the room: where what the number counts starts.

type ByteWriter

type ByteWriter

A growable buffer that numbers, bytes and text are written into, in the writer's byte order - big endian unless it was made with another - or in the one a write names. Nothing here fails: a value that does not fit a field is refused where it becomes the field's width type, with tryInto() at the caller, because the signatures take width types.

var writer = ByteWriter()
writer.uint16 0x1234
writer.uint32(7, order: Some(.LittleEndian))
print writer.bytes()

A length that comes before what it counts is left open with ByteWriter.reserve16 or ByteWriter.reserve32 and filled in with ByteWriter.patch once the rest is written.

field order

order: ByteOrder = ByteOrder.BigEndian

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

fn length

fn length(): Int

How many bytes have been written.

fn bytes

fn bytes(): Bytes

Everything written so far. A list is a value, so writing on afterwards does not change what this answered.

fn uint8

var fn uint8(value: UInt8)

One byte.

fn uint16

var fn uint16(value: UInt16, order: ByteOrder? = None)

A UInt16 as two bytes, in order or the writer's.

fn uint32

var fn uint32(value: UInt32, order: ByteOrder? = None)

A UInt32 as four bytes, in order or the writer's.

fn uint64

var fn uint64(value: UInt64, order: ByteOrder? = None)

A UInt64 as eight bytes, in order or the writer's.

fn int8

var fn int8(value: Int8)

An Int8 as one byte, in two's complement.

fn int16

var fn int16(value: Int16, order: ByteOrder? = None)

An Int16 as two bytes, in two's complement and in order or the writer's.

fn int32

var fn int32(value: Int32, order: ByteOrder? = None)

An Int32 as four bytes, in two's complement and in order or the writer's.

fn int64

var fn int64(value: Int64, order: ByteOrder? = None)

An Int64 as eight bytes, in two's complement and in order or the writer's.

fn float32

var fn float32(value: Float64, order: ByteOrder? = None)

The IEEE 754 binary32 nearest to value, rounded to even, as four bytes in order or the writer's. A value too large for one is an infinity; a nan is the quiet 7fc00000.

fn float64

var fn float64(value: Float64, order: ByteOrder? = None)

value as an IEEE 754 binary64, eight bytes in order or the writer's. A nan is the quiet 7ff8000000000000.

fn varUInt

var fn varUInt(value: UInt64)

value as an unsigned LEB128, in as few bytes as it needs: protobuf's varint, WebAssembly's u64.

fn varInt

var fn varInt(value: Int64, encoding: SignedEncoding = SignedEncoding.SignExtended)

value as a signed LEB128 in encoding, in as few bytes as it needs: sign-extended by default, as WebAssembly writes it, or zigzag, as protobuf's sint64 does.

fn append

var fn append(bytes: Bytes)

bytes as they are.

fn text

var fn text(value: String)

The UTF-8 bytes of value, with nothing around them: a length, where the format has one, is written first.

fn terminatedText

var fn terminatedText(value: String)

The UTF-8 bytes of value and a NUL byte after them. A NUL inside value ends the text for whoever reads it.

fn reserve16

var fn reserve16(order: ByteOrder? = None): Mark<UInt16>

Room for a UInt16 that ByteWriter.patch fills in later, in order or the writer's; it holds zeros until then.

fn reserve32

var fn reserve32(order: ByteOrder? = None): Mark<UInt32>

Room for a UInt32 that ByteWriter.patch fills in later, in order or the writer's; it holds zeros until then.

fn lengthAfter

fn lengthAfter<Width>(mark: Mark<Width>): Int

How many bytes were written after the room mark stands for: the length a length field usually holds.

fn patch

var fn patch<Width: Into<Int>>(mark: Mark<Width>, value: Width)

Writes value into the room mark stands for, in the order the room was made with.