Module buf 

Typed buffers, octets being a Buf<u8, 1>, which is what a backend receives a message into.

A Buf is a typed, N-dimensional array of values, whose dimensions are fixed once it is built. It has no lifetime: it holds a reference to a counted storage that every clone and every slice shares, so that the buffer a message is received into can be handed out in pieces, cast to the types of the values it holds, all the way up to the user, without copying any of it.

A BufMut is a buffer that is statically the only reference to its storage, which is what allows writing to it, and growing it along one dimension, like a Vec, without ever checking whether its storage is shared. A Buf turns into one with copy-on-write, see Buf::make_mut and Buf::into_mut, copying only its own values when its storage is shared, or without, see Buf::get_mut and Buf::try_into_mut, and a BufMut turns back into a Buf to be shared, see BufMut::freeze.

Alignment

Storages are currently aligned on 8 octets, so that a buffer starting where its storage starts, such as one that was just allocated, is aligned for every PackedElement and casts to any of them without copying. This is an implementation detail, which is not guaranteed to stay the same across versions: what depends on the alignment of some values checks it, like Buf::cast, which copies the values when they are not aligned for their new type.

Structs

Buf

A shared, typed, N-dimensional array of values, in column-major order, a scalar for DIM == 0. Its dimensions are fixed once it is built. Octets are a Buf<u8, 1>, cast to other packed types with Self::cast, and turned into strings with Buf::from_spans.

BufMut

A buffer of packed values that is statically the only reference to its storage, like a Vec: it is written without ever checking whether its storage is shared, it grows along one dimension, and it turns into a Buf to be shared, see Self::freeze. A Buf turns into one with copy-on-write, see Buf::make_mut and Buf::into_mut.

PackedSpans

The spans of values packed one after the other, each as many octets as their type: nothing is stored, the range of a value is computed from its index.

TableSpans

The spans of values anywhere in the storage, each given by a table of ranges of octets, relative to where the buffer starts: the table is a side allocation of the storage, so it lives as long as the storage without being counted, and slicing the values only moves the pointer to their ranges.

Traits

Element

A type of the values a Buf holds: where they are in its storage, see Spans, and what octets are one of them.

PackedElement

An element whose values are packed as their octets, one after the other, which is what allows a Buf of them to be seen as a slice, see Buf::as_slice, and written, see BufMut.

Spans

Where the values of a Buf are in its storage: the range of octets of each of them, either computed, see PackedSpans, or given by a table, see TableSpans.