postcard_core/lib.rs
1//! # Postcard Core
2//!
3//! `postcard-core` contains the minimal logic necessary for encoding data to and decoding data from
4//! the postcard wire format. It is not coupled to any specific serialization or deserialization
5//! framework, and is intended to be usable when writing a custom postcard serializer or deserializer.
6//!
7//! For an example of usage of this crate, see the [`postcard2`] crate, which uses `postcard-core`
8//! to implement a [`serde`] compatible serializer/deserializer.
9//!
10//! ## Primitive items
11//!
12//! The following are all "primitive" data types. They are directly serialized and deserialized.
13//!
14//! | # | Type | Serializer | Deserializer |
15//! | :--- | :--- | :--- | :--- |
16//! | 1 | [bool] | [`ser::try_push_bool()`] | [`de::try_take_bool()`] |
17//! | 2 | [i8] | [`ser::try_push_i8()`] | [`de::try_take_i8()`] |
18//! | 3 | [i16] | [`ser::try_push_i16()`] | [`de::try_take_i16()`] |
19//! | 4 | [i32] | [`ser::try_push_i32()`] | [`de::try_take_i32()`] |
20//! | 5 | [i64] | [`ser::try_push_i64()`] | [`de::try_take_i64()`] |
21//! | 6 | [i128] | [`ser::try_push_i128()`] | [`de::try_take_i128()`] |
22//! | 7 | [u8] | [`ser::try_push_u8()`] | [`de::try_take_u8()`] |
23//! | 8 | [u16] | [`ser::try_push_u16()`] | [`de::try_take_u16()`] |
24//! | 9 | [u32] | [`ser::try_push_u32()`] | [`de::try_take_u32()`] |
25//! | 10 | [u64] | [`ser::try_push_u64()`] | [`de::try_take_u64()`] |
26//! | 11 | [u128] | [`ser::try_push_u128()`] | [`de::try_take_u128()`] |
27//! | 12 | [f32] | [`ser::try_push_f32()`] | [`de::try_take_f32()`] |
28//! | 13 | [f64] | [`ser::try_push_f64()`] | [`de::try_take_f64()`] |
29//! | 14 | [char] | [`ser::try_push_char()`] | [`de::try_take_char()`] |
30//! | 30 | [isize] | [`ser::try_push_isize()`] | [`de::try_take_isize()`] |
31//! | 31 | [usize] | [`ser::try_push_usize()`] | [`de::try_take_usize()`] |
32//!
33//! ## Enum Variants
34//!
35//! The following are all [`Tagged Union`] items. The listed serializer and deserializer allow for pushing or
36//! taking ONLY the discriminant. For serialization, the "body" must then be written if necessary. For
37//! deserialization, the discriminant must be used to determine if and how to take the remainder of the
38//! tagged union item.
39//!
40//! | # | Type | Serializer | Deserializer |
41//! | :--- | :--- | :--- | :--- |
42//! | 17a | [option] - `None` | [`ser::try_push_option_none()`] | [`de::try_take_option_discrim()`] |
43//! | 17b | [option] - `Some` | [`ser::try_push_option_some()`] | [`de::try_take_option_discrim()`] |
44//! | 20 | [unit variant] | [`ser::try_push_discriminant()`] | [`de::try_take_discriminant()`] |
45//! | 22 | [newtype variant] | [`ser::try_push_discriminant()`] | [`de::try_take_discriminant()`] |
46//! | 26 | [tuple variant] | [`ser::try_push_discriminant()`] | [`de::try_take_discriminant()`] |
47//! | 29 | [struct variant] | [`ser::try_push_discriminant()`] | [`de::try_take_discriminant()`] |
48//!
49//! ## Length prefixed items
50//!
51//! The following are all length-prefixed items. They begin with a `varint(usize)`, which determines the number
52//! of items in the item. This many items must then be serialized or deserialized.
53//!
54//! For [string] and [byte array], "temp" variants are provided that yield borrowed items that are not required
55//! to live for the entire lifetime of the Flavor's buffer. This is useful when then yielded item is immediately
56//! going to be converted into an owned item, e.g. a `Vec<u8>` or `String`.
57//!
58//! This is an implementation detail only - there is no functional different in deserialization, but may
59//! influence the Flavor interactions. See [`de::Flavor::try_take_n()`] and [`de::Flavor::try_take_n_temp()`]
60//! for more details.
61//!
62//! [string] and [byte array] are also unique in that the provide *borrowed* views to the deserialized data.
63//!
64//! | # | Type | Serializer | Deserializer |
65//! | :--- | :--- | :--- | :--- |
66//! | 15a | [string] | [`ser::try_push_str()`] | [`de::try_take_str()`] |
67//! | 15b | [string] (temp) | [`ser::try_push_str()`] | [`de::try_take_str_temp()`] |
68//! | 16a | [byte array] | [`ser::try_push_bytes()`] | [`de::try_take_bytes()`] |
69//! | 16b | [byte array] (temp) | [`ser::try_push_bytes()`] | [`de::try_take_bytes_temp()`] |
70//! | 23 | [seq] | [`ser::try_push_length()`] | [`de::try_take_length()`] |
71//! | 27 | [map] | [`ser::try_push_length()`] | [`de::try_take_length()`] |
72//!
73//! ## Omitted items
74//!
75//! The following items are not encoded to the wire, and therefore have no serializer and deserializers.
76//!
77//! | # | Type | Serializer | Deserializer |
78//! | :--- | :--- | :--- | :--- |
79//! | 18 | [unit] | N/A | N/A |
80//! | 19 | [unit struct] | N/A | N/A |
81//!
82//! ## Unheadered Aggregates
83//!
84//! The following items contain any number of subitems, however the "container" item itself does not require
85//! any data to be written to or read from the wire. This means that only their child items, if any, need to
86//! be serialized or deserialized.
87//!
88//! | # | Type | Serializer | Deserializer |
89//! | :--- | :--- | :--- | :--- |
90//! | 21 | [newtype struct] | N/A | N/A |
91//! | 24 | [tuple] | N/A | N/A |
92//! | 25 | [tuple struct] | N/A | N/A |
93//! | 28 | [struct] | N/A | N/A |
94//!
95//! ## Schema
96//!
97//! | # | Type | Serializer | Deserializer |
98//! | :--- | :--- | :--- | :--- |
99//! | 32 | [schema] | TODO: Schema | TODO: Schema |
100//!
101//! [`postcard2`]: https://github.com/jamesmunns/postcard/tree/main/source/postcard2
102//! [`serde`]: https://serde.rs
103//! [bool]: https://postcard.jamesmunns.com/wire-format#1---bool
104//! [i8]: https://postcard.jamesmunns.com/wire-format#2---i8
105//! [i16]: https://postcard.jamesmunns.com/wire-format#3---i16
106//! [i32]: https://postcard.jamesmunns.com/wire-format#4---i32
107//! [i64]: https://postcard.jamesmunns.com/wire-format#5---i64
108//! [i128]: https://postcard.jamesmunns.com/wire-format#6---i128
109//! [isize]: https://postcard.jamesmunns.com/wire-format#isize-and-usize
110//! [u8]: https://postcard.jamesmunns.com/wire-format#7---u8
111//! [u16]: https://postcard.jamesmunns.com/wire-format#8---u16
112//! [u32]: https://postcard.jamesmunns.com/wire-format#9---u32
113//! [u64]: https://postcard.jamesmunns.com/wire-format#10---u64
114//! [u128]: https://postcard.jamesmunns.com/wire-format#11---u128
115//! [usize]: https://postcard.jamesmunns.com/wire-format#isize-and-usize
116//! [f32]: https://postcard.jamesmunns.com/wire-format#12---f32
117//! [f64]: https://postcard.jamesmunns.com/wire-format#13---f64
118//! [char]: https://postcard.jamesmunns.com/wire-format#14---char
119//! [string]: https://postcard.jamesmunns.com/wire-format#15---string
120//! [byte array]: https://postcard.jamesmunns.com/wire-format#16---byte-array
121//! [option]: https://postcard.jamesmunns.com/wire-format#17---option
122//! [unit]: https://postcard.jamesmunns.com/wire-format#18---unit
123//! [unit struct]: https://postcard.jamesmunns.com/wire-format#19---unit_struct
124//! [unit variant]: https://postcard.jamesmunns.com/wire-format#20---unit_variant
125//! [newtype struct]: https://postcard.jamesmunns.com/wire-format#21---newtype_struct
126//! [newtype variant]: https://postcard.jamesmunns.com/wire-format#22---newtype_variant
127//! [seq]: https://postcard.jamesmunns.com/wire-format#23---seq
128//! [tuple]: https://postcard.jamesmunns.com/wire-format#24---tuple
129//! [tuple struct]: https://postcard.jamesmunns.com/wire-format#25---tuple_struct
130//! [tuple variant]: https://postcard.jamesmunns.com/wire-format#26---tuple_variant
131//! [map]: https://postcard.jamesmunns.com/wire-format#27---map
132//! [struct]: https://postcard.jamesmunns.com/wire-format#28---struct
133//! [struct variant]: https://postcard.jamesmunns.com/wire-format#29---struct_variant
134//! [schema]: #
135//! [`Tagged Union`]: https://postcard.jamesmunns.com/wire-format#tagged-unions
136
137#![cfg_attr(not(test), no_std)]
138
139pub mod de;
140pub mod ser;
141pub mod varint;