msgpacker 0.7.1

#![cfg_attr(not(feature = "std"), no_std)]
#![warn(missing_docs)]
#![doc = include_str!("../README.md")]

extern crate alloc;

use alloc::vec::Vec;

pub use crate::{
    encoder::{Encoder, EncoderSlice},
    error::Error,
    extension::Extension,
    pack::binary::{pack_bytes, pack_bytes_option},
    pack::collections::{pack_array, pack_array_slice, pack_map},
    unpack::binary::{
        unpack_bytes, unpack_bytes_iter, unpack_bytes_option, unpack_bytes_option_iter,
        unpack_bytes_option_ref,
    },
    unpack::collections::{
        unpack_array, unpack_array_borrowed, unpack_array_iter, unpack_map, unpack_map_iter,
    },
};
pub use bytes::BufMut;

#[cfg(feature = "derive")]
pub use msgpacker_derive::{MsgPacker, MsgPackerBorrowed, MsgUnpackerBorrowed};

mod borrowed;
mod encoder;
mod error;
mod extension;
mod format;
mod helpers;
mod pack;
mod unpack;

#[cfg(feature = "serde")]
pub mod serde;

/// A packable type.
pub trait Packable {
    /// Pack a value into the extendable buffer, returning the amount of written bytes.
    fn pack<T>(&self, buf: &mut T) -> usize
    where
        T: BufMut;

    /// Packs the value into a vector of bytes.
    fn pack_to_vec(&self) -> Vec<u8> {
        let mut bytes = Encoder::new();

        self.pack(&mut bytes);

        bytes.into_inner()
    }
}

/// An unpackable type.
///
/// It provides two methods of deserialization: via slices of bytes and iterators.
///
/// Slices of bytes are more performant than iterators, but they require the bytes to be eagerly
/// loaded. If a lazy load deserialization is needed, then use `unpack_iter`.
pub trait Unpackable: Sized {
    /// Concrete error implementation for the serialization.
    ///
    /// Must interop with [Error].
    type Error: From<Error>;

    /// Unpacks a value from the buffer, returning the deserialized value and the amount of read
    /// bytes.
    fn unpack_with_ofs(buf: &[u8]) -> Result<(usize, Self), Self::Error>;

    /// Unpacks a value from the buffer.
    fn unpack(buf: &[u8]) -> Result<Self, Self::Error> {
        Self::unpack_with_ofs(buf).map(|t| t.1)
    }

    /// Unpacks a value from an iterator of bytes, returning the deserialized value and the amount
    /// of read bytes.
    ///
    /// This should be used only if lazy load is required. [Unpackable::unpack] outperforms
    /// iterators with a large margin.
    fn unpack_iter<I>(bytes: I) -> Result<(usize, Self), Self::Error>
    where
        I: IntoIterator<Item = u8>;
}

/// A borrowed unpackable type.
pub trait UnpackableBorrowed<'a>: Sized {
    /// Concrete error implementation for the serialization.
    ///
    /// Must interop with [Error].
    type Error: From<Error>;

    /// Unpacks a value from the buffer into a borrowed reference, returning the amount of consumed
    /// bytes.
    fn unpack_with_ofs(buf: &'a [u8]) -> Result<(usize, Self), Self::Error>;

    /// Unpacks a value from the buffer into a borrowed reference.
    fn unpack(buf: &'a [u8]) -> Result<Self, Self::Error> {
        Self::unpack_with_ofs(buf).map(|t| t.1)
    }
}

/// Packs the provided packable value into a vector.
pub fn pack_to_vec<T>(value: &T) -> Vec<u8>
where
    T: Packable,
{
    value.pack_to_vec()
}

impl<X: ?Sized> Packable for &X
where
    X: Packable,
{
    fn pack<T>(&self, buf: &mut T) -> usize
    where
        T: BufMut,
    {
        X::pack(self, buf)
    }
}

impl<X: ?Sized> Packable for &mut X
where
    X: Packable,
{
    fn pack<T>(&self, buf: &mut T) -> usize
    where
        T: BufMut,
    {
        X::pack(self, buf)
    }
}