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.

SError

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

SExpr

A symbolic expression: the fundamental data structure for representing structured data.

Constants

CODE_BUFFER_TOO_SHORT

A buffer did not contain enough bytes to unpack a value.

CODE_NOT_A_CHAR

A numeric value is not a valid Unicode scalar value.

CODE_SIGNED_OVERFLOW

A signed value did not fit the requested target type.

CODE_STRING_ENCODING

A serialized string was not valid UTF-8 or not a valid S-expression.

CODE_TAG_TOO_LARGE

A tag exceeded the 32-bit protobuf tag representation.

CODE_UNKNOWN_DISCRIMINANT

A discriminant was not recognized.

CODE_UNSIGNED_OVERFLOW

An unsigned value did not fit the requested target type.

CODE_VARINT_OVERFLOW

A varint exceeded the maximum encoded length.

Traits

Packable

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

Unpackable

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

Functions

buffer_too_short

Construct a buffer-too-short error.

error_code

Return the machine-readable code from a buffertk error.

length_free

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

not_a_char

Construct a not-a-char error.

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.

signed_overflow

Construct a signed-overflow error.

stack_pack

stack_pack begins a tree of packable data on the stack.

string_encoding

Construct a string-encoding error.

tag_too_large

Construct a tag-too-large error.

unknown_discriminant

Construct an unknown-discriminant error.

unsigned_overflow

Construct an unsigned-overflow error.

varint_overflow

Construct a varint-overflow error.