Trait packable::Packable

source ·

pub trait Packable: Sized + 'static {
    type UnpackError: Debug + From<Infallible>;
    type UnpackVisitor: Default + Borrow<()>;

    // Required methods
    fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>;
    fn unpack<U: Unpacker, const VERIFY: bool>(
        unpacker: &mut U,
        visitor: &Self::UnpackVisitor
    ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>;
}

Expand description

A type that can be packed and unpacked.

Almost all basic sized types implement this trait. This trait can be derived using the Packable macro. The following example shows how to implement this trait manually.

Example

We will implement Packable for a type that encapsulates optional integer values (like Option<i32>).

We will use an integer prefix as a tag to determine which variant of the enum is being packed.

use core::convert::Infallible;

use packable::{
    error::{UnknownTagError, UnpackError, UnpackErrorExt},
    packer::Packer,
    unpacker::Unpacker,
    Packable,
};

pub enum Maybe {
    Nothing,
    Just(i32),
}

impl Packable for Maybe {
    type UnpackError = UnknownTagError<u8>;
    type UnpackVisitor = ();

    fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error> {
        match self {
            // Pack a `0` byte and nothing else.
            Self::Nothing => 0u8.pack(packer),
            // Pack a `1` byte followed by the internal value.
            Self::Just(value) => {
                1u8.pack(packer)?;
                value.pack(packer)
            }
        }
    }

    fn unpack<U: Unpacker, const VERIFY: bool>(
        unpacker: &mut U,
        visitor: &Self::UnpackVisitor,
    ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>> {
        match u8::unpack::<_, VERIFY>(unpacker, visitor).coerce()? {
            0u8 => Ok(Self::Nothing),
            1u8 => Ok(Self::Just(
                i32::unpack::<_, VERIFY>(unpacker, visitor).coerce()?,
            )),
            tag => Err(UnpackError::Packable(UnknownTagError(tag))),
        }
    }
}

To understand the behavior of infallible and coerce check the UnpackError and UnpackErrorExt documentation.

We can also derive Packable for the Maybe type.

use packable::Packable;

#[derive(Packable)]
#[packable(tag_type = u8)]
pub enum Maybe {
    #[packable(tag = 0)]
    Nothing,
    #[packable(tag = 1)]
    Just(i32),
}

The code produced by this macro is equivalent to the one shown before.

`#[derive(Packable)]` attributes

The derive implementation can be tweaked using #[packable(...)] attributes.

A very common pattern when implementing Packable for enums consists in introducing a prefix value to differentiate each variant of the enumeration when unpacking, this prefix value is known as a tag. The type of the tag is specified with the #[packable(tag_type = ...)] attribute and it can only be one of [u8], [u16], [u32] or [u64]. The tag value used for each variant is specified with the #[packable(tag = ...)] attribute and can only contain integer literal without any type prefixes (e.g. 42 is valid but 42u8 is not).

In the example above, the tag type is [u8], the Nothing variant has a tag value of 0 and the Just variant has a tag value of 1. This means that the packed version of Maybe::Nothing is [0] and the packed version of Maybe::Just(7) is [1, 0, 0, 0, 7].

The tag_type and tag attributes are mandatory for enums unless the enum has a #[repr(...)] attribute identifier, in which case the repr type will be used as the tag_type and each variant discriminant will be used as the tag. The tag_type and tag attributes take precedence over the repr attribute.

The `UnpackError` associated type

The derive macro provides the optional attribute and #[packable(unpack_error = ...)] to specify the UnpackError associated type. The macro also provides sensible defaults for cases when the attribute is not used.

For structs, the default UnpackError type is the UnpackError of any of the fields type or Infallible in case the struct has no fields.

For enums, the default UnpackError type is UnknownTagError<T> where T is the type specified according to the tag_type or repr attributes.

Following the example above, Maybe::UnpackError is UnknownTagError<u8> because no unpack_error attribute was specified.

Error conversion

The unpack_error attribute can also receive an optional additional argument using the with identifier: #[packable(unpack_error = ..., with = ...)]. This with argument must be a Rust expression and it is used to map the UnpackError produced while unpacking each one of the fields of the type.

Sometimes it is required to map the UnpackError for each field individually. The #[packable(unpack_error_with = ...)] attribute can be applied to each field for this purpose. This attribute takes precedence over the with expression specified in the unpack_error attribute.

The error produced when an invalid tag is found while unpacking an enum can also be specified using the with_error optional argument for the tag_type attribute: #[packable(tag_type = ..., with_error = ...)]. This argument must be a valid Rust expression.

Additional semantic verifications

From time to time it is required to do additional semantic verifications over one of more fields of a struct or an enum’s variant. This can be done using the #[packable(verify_with = ...)] attribute which must receive a valid Rust path refering to a function with the signature

fn<const VERIFY: bool>(field: &F) -> Result<(), P::UnpackError>

where F is the type of the field being verified, P is the type of the struct or enum and VERIFY is the same constant parameter used inside Packable::unpack. This verification function will be run immediately after unpacking the field.

Required Associated Types§

source

type UnpackError: Debug + From<Infallible>

The error type that can be returned if some semantic error occurs while unpacking.

It is recommended to use Infallible if this kind of error is impossible or UnknownTagError when implementing this trait for an enum.

source

type UnpackVisitor: Default + Borrow<()>

FIXME: docs

Required Methods§

source

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

Packs this value into the given Packer.

source

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, visitor: &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

Unpacks this value from the given Unpacker. The VERIFY generic parameter can be used to skip additional syntactic checks.

Object Safety§

This trait is not object safe.

Trait packable::Packable

Required Associated Types§

type UnpackError: Debug + From<Infallible>

type UnpackVisitor: Default + Borrow<()>

Required Methods§

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, visitor: &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

Object Safety§

Implementations on Foreign Types§

impl Packable for bool

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, visitor: &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

type UnpackError = Infallible

type UnpackVisitor = ()

impl Packable for f32

type UnpackError = Infallible

type UnpackVisitor = ()

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, (): &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

impl Packable for f64

type UnpackError = Infallible

type UnpackVisitor = ()

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, (): &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

impl Packable for i8

type UnpackError = Infallible

type UnpackVisitor = ()

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, (): &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

impl Packable for i16

type UnpackError = Infallible

type UnpackVisitor = ()

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, (): &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

impl Packable for i32

type UnpackError = Infallible

type UnpackVisitor = ()

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, (): &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

impl Packable for i64

type UnpackError = Infallible

type UnpackVisitor = ()

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, (): &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

impl Packable for i128

type UnpackError = Infallible

type UnpackVisitor = ()

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, (): &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

impl Packable for u8

type UnpackError = Infallible

type UnpackVisitor = ()

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, (): &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

impl Packable for u16

type UnpackError = Infallible

type UnpackVisitor = ()

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, (): &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

impl Packable for u32

type UnpackError = Infallible

type UnpackVisitor = ()

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, (): &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

impl Packable for u64

type UnpackError = Infallible

type UnpackVisitor = ()

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, (): &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

impl Packable for u128

type UnpackError = Infallible

type UnpackVisitor = ()

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, (): &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

impl<A: Packable> Packable for (A,)

type UnpackError = <A as Packable>::UnpackError

type UnpackVisitor = <A as Packable>::UnpackVisitor

fn pack<P: Packer>(&self, packer: &mut P) -> Result<(), P::Error>

fn unpack<U: Unpacker, const VERIFY: bool>( unpacker: &mut U, visitor: &Self::UnpackVisitor ) -> Result<Self, UnpackError<Self::UnpackError, U::Error>>

impl<A: Packable, B: Packable> Packable for (A, B)where B::UnpackError: Into<A::UnpackError>, A::UnpackVisitor: Borrow<B::UnpackVisitor>,