Crate buffertk

buffertk

Buffertk provides tooling for serializing and deserializing data.

Status

Maintenance track. The library is considered stable and will be put into maintenance mode if unchanged for one year.

Scope

This library is about serialization and deserialization patterns that are common. It is chiefly intended to provide the primitives used by the prototk crate.

Example

To pack, implement the Packable trait and use stack_pack.

use buffertk::{v64, stack_pack};

let x = v64::from(42);
let buf: &[u8] = &stack_pack(x).to_vec();
assert_eq!(&[42u8], buf);

Unpacking uses the Unpackable trait or the Unpacker.

use buffertk::{v64, Unpacker};

let mut up = Unpacker::new(&[42u8]);
let x: v64 = up.unpack().expect("[42] is a valid varint; something's wrong");
assert_eq!(42u64, x.into());

Warts

• Some patterns are used frequently and could be abstracted better. Given that most of this library is used with code generation this is not a concern.

Documentation

The latest documentation is always available at docs.rs.

Structs

LengthFree

A type that packs a slice of objects by concatenating their packed representations. Does not prepend a length.

LengthPrefixer

A type that packs a slice of objects by concatenating their packed representations. Prepends a length.

StackPacker

StackPacker is the type returned by StackPack. It’s a pointer to something packable (usually another StackPacker) and some type that we can directly pack. Both are packable, but it’s usually the case that the former is another StackPacker while the latter is the type being serialized in a call to pack.

Unpacker

Unpacker parses a buffer start to finish.

v64

v64 is the type of a variable integer encoding. It can represent any value of 64-bits or fewer. The encoding follows the protocol buffer spec, which means that negative numbers will always serialize to ten bytes.

Enums

Error

All Error conditions within buffertk.

Traits

Packable

Packable objects can be serialized into an &mut [u8].

Unpackable

Unpackable objects can be deserialized from an &[u8].

Functions

length_free

Pack a byte slice without a length prefix. The resulting format is equivalent to concatenating the individual packings.

pack_helper

pack_helper takes a Packable object and an &mut [u8] and does the work to serialize the packable into a prefix of the buffer. The return value is the portion of the buffer that remains unfilled after this operation.

stack_pack

stack_pack begins a tree of packable data on the stack.