xxai_msgpacker/
lib.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
#![cfg_attr(not(feature = "std"), no_std)]
#![feature(
    iter_array_chunks,
    maybe_uninit_array_assume_init,
    maybe_uninit_uninit_array
)]
#![warn(missing_docs)]
#![doc = include_str!("../README.md")]

#[cfg(feature = "alloc")]
extern crate alloc;

#[cfg(feature = "alloc")]
mod extension;

mod error;
mod format;
mod helpers;
mod pack;
mod unpack;

pub use error::Error;
use format::Format;
pub use pack::{pack_array, pack_map};
pub use unpack::{unpack_array, unpack_array_iter, unpack_map, unpack_map_iter};

#[cfg(feature = "alloc")]
pub use extension::Extension;

#[cfg(feature = "derive")]
pub use msgpacker_derive::MsgPacker;

/// 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: Extend<u8>;
}

impl<'a, X> Packable for &'a X
where
    X: Packable,
{
    fn pack<T>(&self, buf: &mut T) -> usize
    where
        T: Extend<u8>,
    {
        X::pack(self, buf)
    }
}

impl<'a, X> Packable for &'a mut X
where
    X: Packable,
{
    fn pack<T>(&self, buf: &mut T) -> usize
    where
        T: Extend<u8>,
    {
        X::pack(self, buf)
    }
}

/// 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(buf: &[u8]) -> Result<(usize, Self), Self::Error>;

    /// 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>;
}

/// Required types for the library.
pub mod prelude {
    pub use super::{Error, Packable, Unpackable};

    #[cfg(feature = "derive")]
    pub use super::MsgPacker;

    #[cfg(feature = "alloc")]
    pub use super::Extension;
}