postcard/
lib.rs

Help
1#![cfg_attr(not(any(test, feature = "use-std")), no_std)]
2#![warn(missing_docs)]
3#![cfg_attr(not(doctest), doc = include_str!("../README.md"))]
4#![cfg_attr(docsrs, feature(doc_cfg))]
5
6pub mod accumulator;
7mod de;
8
9mod eio;
10
11mod error;
12pub mod fixint;
13mod ser;
14mod varint;
15
16// Still experimental! Don't make pub pub.
17pub(crate) mod max_size;
18
19/// # Experimental Postcard Features
20///
21/// Items inside this module require various feature flags, and are not
22/// subject to SemVer stability. Items may be removed or deprecated at
23/// any point.
24///
25/// ## Derive
26///
27/// The `experimental-derive` feature enables one experimental feature:
28///
29/// * Max size calculation
30///
31/// ### Max Size Calculation
32///
33/// This features enables calculation of the Max serialized size of a message as
34/// an associated `usize` constant called `POSTCARD_MAX_SIZE`. It also provides a
35/// `#[derive(MaxSize)]` macro that can be used for calculating user types.
36///
37/// This is useful for determining the maximum buffer size needed when recieving
38/// or sending a message that has been serialized.
39///
40/// NOTE: This only covers the size of "plain" flavored messages, e.g. not with COBS
41/// or any other Flavors applied. The overhead for these flavors must be calculated
42/// separately.
43///
44/// Please report any missing types, or any incorrectly calculated values.
45///
46/// ### Message Schema Generation
47///
48/// This now lives in the `postcard-schema` crate.
49pub mod experimental {
50    /// Compile time max-serialization size calculation
51    #[cfg(feature = "experimental-derive")]
52    #[cfg_attr(docsrs, doc(cfg(feature = "experimental-derive")))]
53    pub mod max_size {
54        // NOTE: This is the trait...
55        pub use crate::max_size::MaxSize;
56        // NOTE: ...and this is the derive macro
57        pub use postcard_derive::MaxSize;
58    }
59
60    pub use crate::ser::serialized_size;
61}
62
63pub use de::deserializer::Deserializer;
64pub use de::flavors as de_flavors;
65pub use de::{from_bytes, from_bytes_cobs, take_from_bytes, take_from_bytes_cobs};
66pub use error::{Error, Result};
67pub use ser::flavors as ser_flavors;
68pub use ser::{serialize_with_flavor, serializer::Serializer, to_extend, to_slice, to_slice_cobs};
69
70#[cfg(feature = "heapless")]
71pub use ser::{to_vec, to_vec_cobs};
72
73#[cfg(any(feature = "embedded-io-04", feature = "embedded-io-06"))]
74pub use ser::to_eio;
75
76#[cfg(any(feature = "embedded-io-04", feature = "embedded-io-06"))]
77pub use de::from_eio;
78
79#[cfg(feature = "use-std")]
80pub use ser::{to_io, to_stdvec, to_stdvec_cobs};
81
82#[cfg(feature = "use-std")]
83pub use de::from_io;
84
85#[cfg(feature = "alloc")]
86pub use ser::{to_allocvec, to_allocvec_cobs};
87
88#[cfg(feature = "use-crc")]
89pub use {
90    de::{from_bytes_crc32, take_from_bytes_crc32},
91    ser::to_slice_crc32,
92};
93
94#[cfg(all(feature = "use-crc", feature = "heapless"))]
95pub use ser::to_vec_crc32;
96
97#[cfg(all(feature = "use-crc", feature = "use-std"))]
98pub use ser::to_stdvec_crc32;
99
100#[cfg(all(feature = "use-crc", feature = "alloc"))]
101pub use ser::to_allocvec_crc32;
102
103#[cfg(test)]
104mod test {
105    #[test]
106    fn varint_boundary_canon() {
107        let x = u32::MAX;
108        let mut buf = [0u8; 5];
109        let used = crate::to_slice(&x, &mut buf).unwrap();
110        let deser: u32 = crate::from_bytes(used).unwrap();
111        assert_eq!(deser, u32::MAX);
112        assert_eq!(used, &mut [0xFF, 0xFF, 0xFF, 0xFF, 0x0F]);
113        let deser: Result<u32, crate::Error> = crate::from_bytes(&[0xFF, 0xFF, 0xFF, 0xFF, 0x1F]);
114        assert_eq!(deser, Err(crate::Error::DeserializeBadVarint));
115    }
116
117    #[test]
118    fn signed_int128() {
119        let x = -19490127978232325886905073712831_i128;
120        let mut buf = [0u8; 32];
121        let used = crate::to_slice(&x, &mut buf).unwrap();
122        let deser: i128 = crate::from_bytes(used).unwrap();
123        assert_eq!(deser, x);
124    }
125}
postcard/lib.rs

postcard/
lib.rs
