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.