Module packet 

Binary links notation: a self-delimiting packet of links.

A packet stores links, each a tuple of one or more references, at implicit consecutive addresses. It knows nothing about LiNo; the LiNo protocol (crate::protocol::encode_document) and the store archive (crate::protocol::archive) are two uses of it.

byte 0     0x10 | flags      high nibble 1 = format version 1
                             bit 0     external references (Hybrid encoding)
                             bit 1     explicit layout
                             bits 2-3  log2 of the width (compact layout only)

compact layout (bit 1 clear): one section of doublets right after the markers
LEB128     N                 number of links, each `source target`

explicit layout (bit 1 set):
LEB128     S                 number of sections, then S section headers:
LEB128     shape             bits 0-1  log2 of the reference width in bytes
                             bit 2     a gap follows
                             bit 3     variable arity (else every link
                                       holds exactly min_arity references)
                             bits 4+   min_arity, at least 1
LEB128     gap               addresses skipped before the section (if bit 2)
LEB128     extra_arity       0 = no maximum, else max - min (if bit 3)
LEB128     count             number of links in the section

links, section by section; a link in a variable-arity section starts
with LEB128 (length - min_arity); every reference is `width` bytes,
little-endian

Address 0 is null. The first section starts at 1 + gap and every other section at previous end + gap, so gaps leave holes. The compact layout is exactly one section with gap 5 (the LiNo marker points 1..=5), arity 2 and the header width.

Each section has its own width: the narrowest of 1, 2, 4 and 8 bytes that holds every reference in it, so links that only refer to small addresses stay small wherever they live. LinksPacket::pack chooses the sections.

With external references enabled the top bit of a reference marks it as external, exactly like Platform.Data.Hybrid<T>: value v ≥ 1 is stored as the two’s-complement negation 2^bits - v and value 0 as 2^(bits-1). That halves the internal range of every width (0..128 for 8-bit, …).

Structs

ArityRange

How many references the links of a section hold: min..=max, where max = None means no upper bound.

DecodeLimits

Safety limits applied while decoding untrusted input.

LinksPacket

A decoded binary links packet.

Section

A run of links at consecutive addresses sharing an arity range and a reference width.

Enums

Reference

One reference inside a packet.

Constants

BINARY_VERSION_1

The high nibble of the header byte. Text messages never start with a byte in 0x10..=0x1F, so the header doubles as a protocol detector.

FIRST_LINK_ADDRESS

Address of the first link after the marker points.

IDENTIFIED

Marker point 5: (Identified id values…) is a link with an id.

LIST

Marker point 4: (List elements…) is a list of links.

NULL

Null link address.

NUMBER

Marker point 2: (Number unary) is a non-negative integer.

ONE

Marker point 1: the unary one; powers of two are 2^k = (2^(k-1) 2^(k-1)).

STRING

Marker point 3: (String code points…) is a Unicode string.

WIDTHS

The reference widths, in bytes, that a packet may use.

Functions

address_tier

The narrowest width able to hold the internal address address.

decode_external

Decodes a raw width-byte value, returning Some(value) for externals.

encode_external

Encodes an external value at width the way Platform.Data.Hybrid<T> does.

external_capacity

Largest external value that fits in width bytes.

internal_capacity

Largest internal address that fits in width bytes.

read_leb128

Reads an unsigned LEB128 value of at most 64 bits.

reference_width

The narrowest width able to hold reference.

write_leb128

Appends value as unsigned LEB128.