Crate packtool 

packtool is a packing library. Useful to define how serializing and deserializing data from a type level definition.

Example

Unit types

unit types can be packed. What this means is that the object is known to have the same constant value. That way it is possible to define values that are expected to be found and to be the same.

All Packed unit structures must have a #[packed(value = ...)] attribute. The value can be set to any literal except: bool, float.

use packtool::{Packed, View};

/// a unit that is always the utf8 string `"my protocol"`
/// and takes 11 bytes in the packed structure
#[derive(Packed)]
#[packed(value = "my protocol")]
pub struct ProtocolPrefix;

/// a unit that is always `4` and takes 1 byte long
#[derive(Packed)]
#[packed(value = 0b0000_0100u8)]
pub struct OtherUnit();

/// a unit that is always `0xcafe` and takes 4 bytes
/// in the packed structure
#[derive(Packed)]
#[packed(value = 0xcafeu32)]
pub struct LastButNotLeast {}

const SLICE: &[u8] = b"my protocol";
let view: View<'_, ProtocolPrefix> = View::try_from_slice(SLICE)?;

Here we are expecting the ProtocolPrefix to always have the same value in the packed representation. When serializing the ProtocolPrefix, the value will be set with these 11 characters.

Enumeration

Only enumerations without fields are allowed for now.

use packtool::{Packed, View};

#[derive(Packed)]
#[repr(u8)]
pub enum Version {
    V1 = 1,
    V2 = 2,
}

let view: View<'_, Version> = View::try_from_slice(SLICE)?;

assert!(matches!(view.unpack(), Version::V1));

the repr(...) is necessary in order to set a size to the enum.

use packtool::Packed;

#[derive(Packed)]
pub enum Color {
    Red = 1,
    Green = 2,
    Blue = -1
}

Enumerations with data-carrying variants are not supported yet and are rejected at compile time:

use packtool::Packed;

#[derive(Packed)]
pub enum ThisOrThat {
    This,
    That(u32),
}

A single catch-all #[packed(fallback)] variant is the one supported data-carrying shape: an unknown discriminant decodes into it instead of erroring, making the packed enum forward-compatible. The fallback is a single-field tuple variant with no discriminant whose field type is the #[repr(...)] integer, and it carries exactly the repr width on the wire:

use packtool::{Packed, View};

#[derive(Packed, Debug, PartialEq, Eq)]
#[repr(u16)]
pub enum Selector {
    AdminRoot = 0x0001,
    #[packed(fallback)]
    Other(u16),
}

let view: View<'_, Selector> = View::try_from_slice(&[0x99, 0x99])?;
assert_eq!(view.unpack(), Selector::Other(0x9999));

The fallback exists for decode of genuinely-unknown values only. Because a known variant and Fallback(known_value) encode to the same wire bytes, hand-constructing the fallback with a value that equals a known discriminant does not round-trip: decoding those bytes always yields the known unit variant. For the Selector above, Packet::pack(&Selector::Other(0x0001)).unpack() decodes back to Selector::AdminRoot, not Selector::Other(0x0001). This never arises from decoding — decode only ever produces the fallback for genuinely-unknown values, which always round-trip — so it is a misuse caveat, not a correctness issue:

use packtool::{Packed, Packet};

#[derive(Packed, Debug, PartialEq, Eq)]
#[repr(u16)]
pub enum Selector {
    AdminRoot = 0x0001,
    #[packed(fallback)]
    Other(u16),
}

// a genuinely-unknown value round-trips through the fallback:
assert_eq!(
    Packet::pack(&Selector::Other(0x9999)).unpack(),
    Selector::Other(0x9999),
);
// but a fallback holding a known discriminant canonicalises on decode:
assert_eq!(
    Packet::pack(&Selector::Other(0x0001)).unpack(),
    Selector::AdminRoot,
);

A fallback whose field type does not match the #[repr(...)] is rejected:

use packtool::Packed;

#[derive(Packed)]
#[repr(u16)]
pub enum Selector {
    AdminRoot = 0x0001,
    #[packed(fallback)]
    Other(u32),
}

More than one #[packed(fallback)] variant is rejected:

use packtool::Packed;

#[derive(Packed)]
#[repr(u16)]
pub enum Selector {
    AdminRoot = 0x0001,
    #[packed(fallback)]
    Other(u16),
    #[packed(fallback)]
    Another(u16),
}

A fallback variant carrying more than one field is rejected:

use packtool::Packed;

#[derive(Packed)]
#[repr(u16)]
pub enum Selector {
    AdminRoot = 0x0001,
    #[packed(fallback)]
    Other(u16, u16),
}

A fallback variant that declares a discriminant is rejected:

use packtool::Packed;

#[derive(Packed)]
#[repr(u16)]
pub enum Selector {
    AdminRoot = 0x0001,
    #[packed(fallback)]
    Other(u16) = 5,
}

#[packed(fallback)] is only valid on an enum variant; on any other scope it is rejected rather than silently ignored — on the enum container itself:

use packtool::Packed;

#[derive(Packed)]
#[repr(u16)]
#[packed(fallback)]
pub enum Selector {
    AdminRoot = 0x0001,
}

on a struct:

use packtool::Packed;

#[derive(Packed)]
#[packed(fallback)]
pub struct NotAnEnum {
    a: u32,
}

or on a field:

use packtool::Packed;

#[derive(Packed)]
pub struct NotAnEnum {
    #[packed(fallback)]
    a: u32,
}

Unions cannot be packed and are rejected at compile time:

use packtool::Packed;

#[derive(Packed)]
pub union Choice {
    a: u32,
    b: f32,
}

Type-parameter generics are supported on named structs. The packed layout and SIZE are computed through <T as Packed>::SIZE, and a T: Packed bound is injected for every type parameter (composing with any where clause you write):

use packtool::Packed;

#[derive(Packed)]
pub struct Log<T> {
    parent_id: [u8; 64],
    content: T,
    signature: [u8; 64],
}

Generics on enums and on tuple structs are still rejected at compile time:

use packtool::Packed;

#[derive(Packed)]
pub struct Wrapper<T>(T);

use packtool::Packed;

#[derive(Packed)]
pub enum Either<L, R> {
    Left(L),
    Right(R),
}

A generic struct with no fields is rejected too: its type parameters could not appear in the (empty) packed layout.

use packtool::Packed;

#[derive(Packed)]
pub struct Empty<T> {}

combining packed objects

It is possible to compose packed objects in named or tuple structures.

use packtool::Packed;

#[derive(Packed)]
#[packed(value = "packcoin")]
pub struct Tag;

/// 1 byte that will be used to store a version number
#[derive(Packed)]
#[repr(u8)]
pub enum Version {
    V1 = 1,
    V2 = 2,
}

/// 8 bytes that will be used to store a block number
#[derive(Packed)]
pub struct BlockNumber(u32, u32);

/// 9 bytes packed header
#[derive(Packed)]
pub struct Header {
    tag: Tag,
    version: Version,
    block_number: BlockNumber
}

Each of the packed objects have a view accessor for each fields:

• for named fields, the name of the accessor is the name of the field
• for tuples, the name of the accessor is the index of the field preceded by an underscore (_): _0, _1 etc.

let tag: View<'_, Tag> = Header::tag(header);
let block_number: View<'_, BlockNumber> = Header::block_number(header);

let epoch: View<'_, u32> = BlockNumber::_0(block_number);
let slot: u32  = BlockNumber::_1(block_number).unpack();

You can rename the accessor with the attribute accessor:

#[derive(Packed)]
pub struct BlockNumber(
    #[packed(accessor = "epoch")]
    u32,
    #[packed(accessor = "slot")]
    u32
);
let epoch = BlockNumber::epoch(block_number); // instead of _0
let slot = BlockNumber::slot(block_number).unpack(); // instead of _1

It is also possible to prevent the accessor to be created. You can set the accessor with a literal boolean to say if you want the accessor or not. true will simply means the default case (use the index of the field or use the name for the name of the accessor):

#[derive(Packed)]
pub struct Hash(
    #[packed(accessor = true)]
    [u8; 32]
);
let bytes = Hash::_0(hash);

However if you set it to false there will be no accessor created for you:

#[derive(Packed)]
pub struct Hash(
    #[packed(accessor = false)]
    [u8; 32]
);
let bytes = Hash::_0(hash);

Macros

ensure

helper method to create an [Error] is the assumption fails.

Structs

Packet

a owned slice of memory containing the Packed

View

view of a slice in memory as a packed structure of type T

Enums

Error

error associated to unpacking or creating [View] of [Packed] types.

Traits

Context

Packed

trait to define how a fixed size Packed object is serialized into a byte slice representation.

Derive Macros

Packed