Convenience functions

Convenience functions for serde usage

Cargo.toml

@@ -56,6 +56,9 @@ optional = true
 version = "3.0.1"
 optional = true
 
+[dependencies.paste]
+version = "1.0.12"
+
 [features]
 default = ["heapless-cas"]
 

src/de/flavors.rs

@@ -174,17 +174,22 @@ impl<'de> Flavor<'de> for Slice<'de> {
 ///
 /// The `crc` feature requires enabling to use this module.
 ///
-/// More on CRCs: https://en.wikipedia.org/wiki/Cyclic_redundancy_check.
-#[cfg(feature = "crc")]
+/// More on CRCs: <https://en.wikipedia.org/wiki/Cyclic_redundancy_check>.
+#[cfg(feature = "use-crc")]
 pub mod crc {
     use core::convert::TryInto;
 
     use crc::Digest;
     use crc::Width;
+    use serde::Deserialize;
 
     use super::Flavor;
+    use super::Slice;
+
+    use crate::Deserializer;
     use crate::Error;
     use crate::Result;
+    use paste::paste;
 
     /// Manages CRC modifications as a flavor.
     pub struct CrcModifier<'de, B, W>
@@ -210,56 +215,83 @@ pub mod crc {
     macro_rules! impl_flavor {
         ($( $int:ty ),*) => {
             $(
-                impl<'de, B> Flavor<'de> for CrcModifier<'de, B, $int>
-                where
-                    B: Flavor<'de>,
-                {
-                    type Remainder = B::Remainder;
+                paste! {
+                    impl<'de, B> Flavor<'de> for CrcModifier<'de, B, $int>
+                    where
+                        B: Flavor<'de>,
+                    {
+                        type Remainder = B::Remainder;
 
-                    type Source = B::Source;
+                        type Source = B::Source;
 
-                    #[inline]
-                    fn pop(&mut self) -> Result<u8> {
-                        match self.flav.pop() {
-                            Ok(byte) => {
-                                self.digest.update(&[byte]);
-                                Ok(byte)
+                        #[inline]
+                        fn pop(&mut self) -> Result<u8> {
+                            match self.flav.pop() {
+                                Ok(byte) => {
+                                    self.digest.update(&[byte]);
+                                    Ok(byte)
+                                }
+                                e @ Err(_) => e,
                             }
-                            e @ Err(_) => e,
                         }
-                    }
 
-                    #[inline]
-                    fn try_take_n(&mut self, ct: usize) -> Result<&'de [u8]> {
-                        match self.flav.try_take_n(ct) {
-                            Ok(bytes) => {
-                                self.digest.update(bytes);
-                                Ok(bytes)
+                        #[inline]
+                        fn try_take_n(&mut self, ct: usize) -> Result<&'de [u8]> {
+                            match self.flav.try_take_n(ct) {
+                                Ok(bytes) => {
+                                    self.digest.update(bytes);
+                                    Ok(bytes)
+                                }
+                                e @ Err(_) => e,
                             }
-                            e @ Err(_) => e,
                         }
-                    }
 
-                    fn finalize(mut self) -> Result<Self::Remainder> {
-                        match self.flav.try_take_n(core::mem::size_of::<$int>()) {
-                            Ok(prev_crc_bytes) => match self.flav.finalize() {
-                                Ok(remainder) => {
-                                    let crc = self.digest.finalize();
-                                    let le_bytes = prev_crc_bytes
-                                        .try_into()
-                                        .map_err(|_| Error::DeserializeBadEncoding)?;
-                                    let prev_crc = <$int>::from_le_bytes(le_bytes);
-                                    if crc == prev_crc {
-                                        Ok(remainder)
-                                    } else {
-                                        Err(Error::DeserializeBadEncoding)
+                        fn finalize(mut self) -> Result<Self::Remainder> {
+                            match self.flav.try_take_n(core::mem::size_of::<$int>()) {
+                                Ok(prev_crc_bytes) => match self.flav.finalize() {
+                                    Ok(remainder) => {
+                                        let crc = self.digest.finalize();
+                                        let le_bytes = prev_crc_bytes
+                                            .try_into()
+                                            .map_err(|_| Error::DeserializeBadEncoding)?;
+                                        let prev_crc = <$int>::from_le_bytes(le_bytes);
+                                        if crc == prev_crc {
+                                            Ok(remainder)
+                                        } else {
+                                            Err(Error::DeserializeBadEncoding)
+                                        }
                                     }
-                                }
-                                e @ Err(_) => e,
-                            },
-                            Err(e) => Err(e),
+                                    e @ Err(_) => e,
+                                },
+                                Err(e) => Err(e),
+                            }
                         }
                     }
+
+                    /// Deserialize a message of type `T` from a byte slice with a Crc. The unused portion (if any)
+                    /// of the byte slice is not returned.
+                    pub fn [<from_bytes_ $int>]<'a, T>(s: &'a [u8], digest: Digest<'a, u32>) -> Result<T>
+                    where
+                        T: Deserialize<'a>,
+                    {
+                        let flav = CrcModifier::new(Slice::new(s), digest);
+                        let mut deserializer = Deserializer::from_flavor(flav);
+                        let r = T::deserialize(&mut deserializer)?;
+                        let _ = deserializer.finalize()?;
+                        Ok(r)
+                    }
+
+                    /// Deserialize a message of type `T` from a byte slice with a Crc. The unused portion (if any)
+                    /// of the byte slice is returned for further usage
+                    pub fn [<take_from_bytes_ $int>]<'a, T>(s: &'a [u8], digest: Digest<'a, u32>) -> Result<(T, &'a [u8])>
+                    where
+                        T: Deserialize<'a>,
+                    {
+                        let flav = CrcModifier::new(Slice::new(s), digest);
+                        let mut deserializer = Deserializer::from_flavor(flav);
+                        let t = T::deserialize(&mut deserializer)?;
+                        Ok((t, deserializer.finalize()?))
+                    }
                 }
             )*
         };

src/de/mod.rs

@@ -20,7 +20,7 @@ where
 
 /// Deserialize a message of type `T` from a cobs-encoded byte slice. The
 /// unused portion (if any) of the byte slice is not returned.
-/// The used portion of the input slice is modified during deserialization (even if an error is returned). 
+/// The used portion of the input slice is modified during deserialization (even if an error is returned).
 /// Therefore, if this is not desired, pass a clone of the original slice.
 pub fn from_bytes_cobs<'a, T>(s: &'a mut [u8]) -> Result<T>
 where
@@ -32,7 +32,7 @@ where
 
 /// Deserialize a message of type `T` from a cobs-encoded byte slice. The
 /// unused portion (if any) of the byte slice is returned for further usage.
-/// The used portion of the input slice is modified during deserialization (even if an error is returned). 
+/// The used portion of the input slice is modified during deserialization (even if an error is returned).
 /// Therefore, if this is not desired, pass a clone of the original slice.
 pub fn take_from_bytes_cobs<'a, T>(s: &'a mut [u8]) -> Result<(T, &'a mut [u8])>
 where
@@ -67,6 +67,22 @@ where
     Ok((t, deserializer.finalize()?))
 }
 
+/// Conveniently deserialize a message of type `T` from a byte slice with a Crc. The unused portion (if any)
+/// of the byte slice is not returned.
+///
+/// See the `de_flavors::crc` module for the complete set of functions.
+/// 
+#[cfg(feature = "use-crc")]
+pub use flavors::crc::from_bytes_u32 as from_bytes_crc32;
+
+/// Conveniently deserialize a message of type `T` from a byte slice with a Crc. The unused portion (if any)
+/// of the byte slice is returned for further usage
+///
+/// See the `de_flavors::crc` module for the complete set of functions.
+/// 
+#[cfg(feature = "use-crc")]
+pub use flavors::crc::take_from_bytes_u32 as take_from_bytes_crc32;
+
 ////////////////////////////////////////////////////////////////////////////////
 
 #[cfg(feature = "heapless")]

src/lib.rs

@@ -91,6 +91,21 @@ pub use ser::{to_stdvec, to_stdvec_cobs};
 #[cfg(feature = "alloc")]
 pub use ser::{to_allocvec, to_allocvec_cobs};
 
+#[cfg(feature = "use-crc")]
+pub use {
+    de::{from_bytes_crc32, take_from_bytes_crc32},
+    ser::to_slice_crc32,
+};
+
+#[cfg(all(feature = "use-crc", feature = "heapless"))]
+pub use ser::to_vec_crc32;
+
+#[cfg(all(feature = "use-crc", feature = "use-std"))]
+pub use ser::to_stdvec_crc32;
+
+#[cfg(all(feature = "use-crc", feature = "alloc"))]
+pub use ser::to_allocvec_crc32;
+
 #[cfg(test)]
 mod test {
     #[test]

src/ser/flavors.rs

@@ -101,6 +101,9 @@ pub use std_vec::*;
 #[cfg(feature = "alloc")]
 pub use alloc_vec::*;
 
+#[cfg(feature = "alloc")]
+extern crate alloc;
+
 /// The serialization Flavor trait
 ///
 /// This is used as the primary way to encode serialized data into some kind of buffer,
@@ -422,14 +425,21 @@ where
 ///
 /// The `crc` feature requires enabling to use this module.
 ///
-/// More on CRCs: https://en.wikipedia.org/wiki/Cyclic_redundancy_check.
-#[cfg(feature = "crc")]
+/// More on CRCs: <https://en.wikipedia.org/wiki/Cyclic_redundancy_check>.
+#[cfg(feature = "use-crc")]
 pub mod crc {
     use crc::Digest;
     use crc::Width;
+    use serde::Serialize;
 
+    #[cfg(feature = "alloc")]
+    use super::alloc;
     use super::Flavor;
+    use super::Slice;
+
+    use crate::serialize_with_flavor;
     use crate::Result;
+    use paste::paste;
 
     /// Manages CRC modifications as a flavor.
     pub struct CrcModifier<'a, B, W>
@@ -455,24 +465,70 @@ pub mod crc {
     macro_rules! impl_flavor {
         ($( $int:ty ),*) => {
             $(
-                impl<'a, B> Flavor for CrcModifier<'a, B, $int>
-                where
-                    B: Flavor,
-                {
-                    type Output = <B as Flavor>::Output;
-
-                    #[inline(always)]
-                    fn try_push(&mut self, data: u8) -> Result<()> {
-                        self.digest.update(&[data]);
-                        self.flav.try_push(data)
-                    }
+                paste! {
+                    impl<'a, B> Flavor for CrcModifier<'a, B, $int>
+                    where
+                        B: Flavor,
+                    {
+                        type Output = <B as Flavor>::Output;
+
+                        #[inline(always)]
+                        fn try_push(&mut self, data: u8) -> Result<()> {
+                            self.digest.update(&[data]);
+                            self.flav.try_push(data)
+                        }
 
-                    fn finalize(mut self) -> Result<Self::Output> {
-                        let crc = self.digest.finalize();
-                        for byte in crc.to_le_bytes() {
-                            self.flav.try_push(byte)?;
+                        fn finalize(mut self) -> Result<Self::Output> {
+                            let crc = self.digest.finalize();
+                            for byte in crc.to_le_bytes() {
+                                self.flav.try_push(byte)?;
+                            }
+                            self.flav.finalize()
                         }
-                        self.flav.finalize()
+                    }
+
+                    /// Serialize a `T` to the given slice, with the resulting slice containing
+                    /// data followed by a CRC. The CRC bytes are included in the output buffer.
+                    ///
+                    /// When successful, this function returns the slice containing the
+                    /// serialized and encoded message.
+                    pub fn [<to_slice_ $int>]<'a, 'b, T>(
+                        value: &'b T,
+                        buf: &'a mut [u8],
+                        digest: Digest<'a, u32>,
+                    ) -> Result<&'a mut [u8]>
+                    where
+                        T: Serialize + ?Sized,
+                    {
+                        serialize_with_flavor(value, CrcModifier::new(Slice::new(buf), digest))
+                    }
+
+                    /// Serialize a `T` to a `heapless::Vec<u8>`, with the `Vec` containing
+                    /// data followed by a CRC. The CRC bytes are included in the output `Vec`.
+                    /// Requires the (default) `heapless` feature.
+                    #[cfg(feature = "heapless")]
+                    pub fn [<to_vec_ $int>]<'a, T, const B: usize>(
+                        value: &T,
+                        digest: Digest<'a, u32>,
+                    ) -> Result<heapless::Vec<u8, B>>
+                    where
+                        T: Serialize + ?Sized,
+                    {
+                        use super::HVec;
+
+                        serialize_with_flavor(value, CrcModifier::new(HVec::default(), digest))
+                    }
+
+                    /// Serialize a `T` to a `heapless::Vec<u8>`, with the `Vec` containing
+                    /// data followed by a CRC. The CRC bytes are included in the output `Vec`.
+                    #[cfg(feature = "alloc")]
+                    pub fn [<to_allocvec_ $int>]<'a, T>(value: &T, digest: Digest<'a, u32>) -> Result<alloc::vec::Vec<u8>>
+                    where
+                        T: Serialize + ?Sized,
+                    {
+                        use super::AllocVec;
+
+                        serialize_with_flavor(value, CrcModifier::new(AllocVec::new(), digest))
                     }
                 }
             )*