API

enumOrder

Which end of a number goes first (RFC 1700 calls the big end "network byte order").

pub(all) enum Order {

• Big
• Little

letorder

Big-endian, because every protocol in reach of this package writes that way: IP and everything over it, TLS, QUIC, HTTP/2 and HTTP/3. The exceptions are local formats — MySQL's wire protocol, most file headers — and they say so.

pub let order : Order

fnread_f32

The IEEE-754 binary32 at at. The bits are reinterpreted, not converted: a signalling NaN or a negative zero comes back as it was written, which is what a wire format means by a float.

pub fn read_f32(BytesView, at? : Int32, order? : Order) -> Float?

fnread_f64

The IEEE-754 binary64 at at.

pub fn read_f64(BytesView, at? : Int32, order? : Order) -> Double?

fnread_i16

The signed sixteen-bit value at at, two's complement.

pub fn read_i16(BytesView, at? : Int32, order? : Order) -> Int32?

fnread_i32

The signed thirty-two-bit value at at, two's complement.

pub fn read_i32(BytesView, at? : Int32, order? : Order) -> Int32?

fnread_i64

The signed sixty-four-bit value at at, two's complement.

pub fn read_i64(BytesView, at? : Int32, order? : Order) -> Int64?

fnread_i8

The signed octet at at, two's complement.

pub fn read_i8(BytesView, at? : Int32) -> Int32?

fnread_u16

The sixteen-bit value at at.

pub fn read_u16(BytesView, at? : Int32, order? : Order) -> Int32?

fnread_u24

The twenty-four-bit value at at. Three-octet lengths are how TLS writes a handshake message (RFC 8446 §4) and how HTTP/2 writes a frame (RFC 9113 §4.1), which is why a width no language has is here.

pub fn read_u24(BytesView, at? : Int32, order? : Order) -> Int32?

fnread_u32

The thirty-two-bit value at at.

pub fn read_u32(BytesView, at? : Int32, order? : Order) -> UInt32?

fnread_u64

The sixty-four-bit value at at.

pub fn read_u64(BytesView, at? : Int32, order? : Order) -> UInt64?

fnread_u8

The octet at at, or None when the view is shorter than that.

pub fn read_u8(BytesView, at? : Int32) -> Int32?

fnread_uint

The value in size octets at at, for a width the caller only knows at run time. The named widths above are what most callers want and read better where they apply. This is for a protocol that spells its own: MySQL's int<n> and the three-octet lengths of a Kafka or DNS field are the same arithmetic with size carried in a variable, and writing the loop out again per protocol is how the widths drift. None when size is outside one to eight octets, or when the view is shorter than at plus size.

pub fn read_uint(BytesView, at? : Int32, size~ : Int32, order? : Order) -> UInt64?

fnwrite_f32

Append an IEEE-754 binary32, bits as they are.

pub fn write_f32(@buffer.Buffer, Float, order? : Order) -> Unit

fnwrite_f64

Append an IEEE-754 binary64, bits as they are.

pub fn write_f64(@buffer.Buffer, Double, order? : Order) -> Unit

fnwrite_i16

Append a signed sixteen-bit value, two's complement.

pub fn write_i16(@buffer.Buffer, Int32, order? : Order) -> Unit

fnwrite_i32

Append a signed thirty-two-bit value, two's complement.

pub fn write_i32(@buffer.Buffer, Int32, order? : Order) -> Unit

fnwrite_i64

Append a signed sixty-four-bit value, two's complement.

pub fn write_i64(@buffer.Buffer, Int64, order? : Order) -> Unit

fnwrite_i8

Append a signed octet, two's complement.

pub fn write_i8(@buffer.Buffer, Int32) -> Unit

fnwrite_u16

Append a sixteen-bit value.

pub fn write_u16(@buffer.Buffer, Int32, order? : Order) -> Unit

fnwrite_u24

Append a twenty-four-bit value.

pub fn write_u24(@buffer.Buffer, Int32, order? : Order) -> Unit

fnwrite_u32

Append a thirty-two-bit value.

pub fn write_u32(@buffer.Buffer, UInt32, order? : Order) -> Unit

fnwrite_u64

Append a sixty-four-bit value.

pub fn write_u64(@buffer.Buffer, UInt64, order? : Order) -> Unit

fnwrite_u8

Append an octet.

pub fn write_u8(@buffer.Buffer, Int32) -> Unit

fnwrite_uint

Append the low size octets of v, for a width the caller only knows at run time. Octets above size are dropped, which is what a protocol that says int<3> means by it; a caller that needs to know a value did not fit asks size first.

pub fn write_uint(@buffer.Buffer, UInt64, size~ : Int32, order? : Order) -> Unit

fnsize

How many octets v needs, which is one for zero and otherwise as many as its highest set bit occupies.

pub fn size(UInt64) -> Int32

letmax

The largest value the encoding can carry: sixty-two bits (RFC 9000 §16).

pub let max : UInt64

fnencode

Encode v as a QUIC variable-length integer (RFC 9000 §16) in the shortest form that holds it: the two most-significant bits of the first byte select the length (00 → 1 byte / 6-bit value, 01 → 2 / 14-bit, 10 → 4 / 30-bit, 11 → 8 / 62-bit) and the remaining bits carry the value big-endian. v must be below 2^62 (QUIC's varint ceiling).

pub fn encode(UInt64) -> Bytes

fndecode

Decode a QUIC variable-length integer at the start of b, returning its value and the number of bytes it occupied, or None when b is shorter than the length its first byte's prefix declares.

pub fn decode(BytesView) -> (UInt64, Int32)?

fnsize

How many octets v takes, without writing it. A writer that has to put a length before a payload needs this: the length field's own size is part of what it describes, and measuring twice is cheaper than writing twice.

pub fn size(UInt64) -> Int32

letlimit

The largest value this reads, which is what a positive Int holds. §5.1 leaves the ceiling to the implementation and asks for a decoding error past it, so a peer cannot make a reader loop over continuation octets for as long as it likes.

pub let limit : Int64

fnencode

v in the low prefix bits of the first octet, continuing into further octets when it does not fit (RFC 7541 §5.1). flags are the bits above the prefix, which every representation using this encoding puts something in: HPACK's six field representations and QPACK's five each begin with a pattern there. They are OR'd into the first octet and are the caller's to get right. The three worked examples of Appendix C: ten in a five-bit prefix is one octet, 1337 in five bits is three, and forty-two at an octet boundary is one.

pub fn encode(Int32, prefix~ : Int32, flags? : Int32) -> Bytes

fndecode

The value at at and how many octets it took, with the flag bits above the prefix masked off and ignored (RFC 7541 §5.1).

pub fn decode(BytesView, at? : Int32, prefix~ : Int32) -> (Int32, Int32) raise Refused

fnflagged

Whether the octet at at has its high bit set — the H bit of a string literal in both header compressions, which says the octets after the length are Huffman-coded (RFC 7541 §5.2, RFC 9204 §4.1.2).

pub fn flagged(BytesView, at? : Int32, bit? : Int32) -> Bool

fnsize

How many octets v takes in a prefix-bit prefix, without writing it.

pub fn size(Int32, prefix~ : Int32) -> Int32

errorRefused

Why a prefix integer was refused. Truncated is a value that continues past the end of what it was given; Exceeded is one that needs more than a positive Int can hold. RFC 7541 §5.1 makes a value larger than the implementation's limit a decoding error, and an encoding of the same value in more octets than necessary is one too — a receiver that read either would disagree with the sender about what came next.

pub(all) suberror Refused {

• Truncated(String)
• Exceeded(limit~ : Int64, got~ : Int64)

Implements Show.

letlimit

How many octets sixty-four bits can occupy: nine of seven bits and one of the last. A reader that did not stop here would follow continuation bits for as long as a peer cared to send them.

pub let limit : Int32

fnencode

v as base-128 octets: seven bits each, least significant group first, the high bit set on every octet but the last. This is protobuf's "Base 128 Varints" and DWARF's unsigned LEB128, which are the same encoding under two names.

pub fn encode(UInt64) -> Bytes

fndecode

The value at at and how many octets it took.

pub fn decode(BytesView, at? : Int32) -> (UInt64, Int32) raise Refused

fnwrite

The same, appended to a buffer rather than allocated.

pub fn write(@buffer.Buffer, UInt64) -> Unit

fnsize

How many octets v takes, without writing it.

pub fn size(UInt64) -> Int32

fnunzigzag

The inverse: an unsigned value unfolded back onto a signed one.

pub fn unzigzag(UInt64) -> Int64

fnzigzag

A signed value folded onto an unsigned one so that small magnitudes stay short: -1 becomes 1, 1 becomes 2, -2 becomes 3 (protobuf's sint32 and sint64). Without it a negative value would sign-extend to sixty-four bits and take all ten octets, whatever its magnitude.

pub fn zigzag(Int64) -> UInt64

errorRefused

Why a value was refused: it continues past the end of what it was given, or past the ten octets sixty-four bits can occupy.

pub(all) suberror Refused {

• Truncated(String)
• Exceeded(limit~ : Int32, got~ : Int32)

Implements Show.

fnencode

v as a length-encoded integer: one octet under 251, otherwise a marker saying how many little-endian octets follow. The markers are 0xfc for two, 0xfd for three and 0xfe for eight; 251 through 255 are never written as a bare first octet, which is what leaves 0xfb free for NULL and 0xff for an error packet.

pub fn encode(UInt64) -> Bytes

fndecode

The value at at and how many octets it took.

pub fn decode(BytesView, at? : Int32) -> (UInt64, Int32) raise Refused

fnwrite

The same, appended to a buffer rather than allocated.

pub fn write(@buffer.Buffer, UInt64) -> Unit

fnsize

How many octets v takes, without writing it.

pub fn size(UInt64) -> Int32

errorRefused

Why a length-encoded integer was refused: it continues past the end of what it was given, or its first octet is one the protocol reserves for something else. 0xfb is NULL in a row and 0xff begins an error packet; neither is a number, and a reader that took one for a length would be off by however much followed.

pub(all) suberror Refused {

• Truncated(String)
• Reserved(got~ : Int32)

Implements Show.