|
66 | 66 | //! # Packed Encoding |
67 | 67 | //! When serializing structs or enums in CBOR the keys or enum variant names will be serialized |
68 | 68 | //! as string keys to a map. Especially in embedded environments this can increase the file |
69 | | -//! size too much. In packed encoding the keys and variants will be serialized as variable sized |
70 | | -//! integers. The first 24 entries in any struct consume only a single byte! |
| 69 | +//! size too much. In packed encoding all struct keys, as well as any enum variant that has no data, |
| 70 | +//! will be serialized as variable sized integers. The first 24 entries in any struct consume only a |
| 71 | +//! single byte! Packed encoding uses serde's preferred [externally tagged enum |
| 72 | +//! format](https://serde.rs/enum-representations.html) and therefore serializes enum variant names |
| 73 | +//! as string keys when that variant contains data. So, in the packed encoding example, `FirstVariant` |
| 74 | +//! encodes to a single byte, but encoding `SecondVariant` requires 16 bytes. |
| 75 | +//! |
71 | 76 | //! To serialize a document in this format use `Serializer::new(writer).packed_format()` or |
72 | 77 | //! the shorthand `ser::to_vec_packed`. The deserialization works without any changes. |
73 | 78 | //! |
| 79 | +//! If you would like to omit the enum variant encoding for all variants, including ones that |
| 80 | +//! contain data, you can add `legacy_enums()` in addition to `packed_format()`, as can seen |
| 81 | +//! in the Serialize using minimal encoding example. |
| 82 | +//! |
74 | 83 | //! # Self describing documents |
75 | 84 | //! In some contexts different formats are used but there is no way to declare the format used |
76 | 85 | //! out of band. For this reason CBOR has a magic number that may be added before any document. |
|
132 | 141 | //! # } |
133 | 142 | //! ``` |
134 | 143 | //! |
| 144 | +//! Serialize using packed encoding |
| 145 | +//! |
| 146 | +//! ```rust |
| 147 | +//! use serde_derive::{Deserialize, Serialize}; |
| 148 | +//! use serde_cbor::ser::to_vec_packed; |
| 149 | +//! use WithTwoVariants::*; |
| 150 | +//! |
| 151 | +//! #[derive(Debug, Serialize, Deserialize)] |
| 152 | +//! enum WithTwoVariants { |
| 153 | +//! FirstVariant, |
| 154 | +//! SecondVariant(u8), |
| 155 | +//! } |
| 156 | +//! |
| 157 | +//! let cbor = to_vec_packed(&FirstVariant).unwrap(); |
| 158 | +//! assert_eq!(cbor.len(), 1); |
| 159 | +//! |
| 160 | +//! let cbor = to_vec_packed(&SecondVariant(0)).unwrap(); |
| 161 | +//! assert_eq!(cbor.len(), 16); // Includes 13 bytes of "SecondVariant" |
| 162 | +//! ``` |
| 163 | +//! |
| 164 | +//! Serialize using minimal encoding |
| 165 | +//! |
| 166 | +//! ```rust |
| 167 | +//! use serde_derive::{Deserialize, Serialize}; |
| 168 | +//! use serde_cbor::{Result, Serializer, ser::{self, IoWrite}}; |
| 169 | +//! use WithTwoVariants::*; |
| 170 | +//! |
| 171 | +//! fn to_vec_minimal<T>(value: &T) -> Result<Vec<u8>> |
| 172 | +//! where |
| 173 | +//! T: serde::Serialize, |
| 174 | +//! { |
| 175 | +//! let mut vec = Vec::new(); |
| 176 | +//! value.serialize(&mut Serializer::new(&mut IoWrite::new(&mut vec)).packed_format().legacy_enums())?; |
| 177 | +//! Ok(vec) |
| 178 | +//! } |
| 179 | +//! |
| 180 | +//! #[derive(Debug, Serialize, Deserialize)] |
| 181 | +//! enum WithTwoVariants { |
| 182 | +//! FirstVariant, |
| 183 | +//! SecondVariant(u8), |
| 184 | +//! } |
| 185 | +//! |
| 186 | +//! let cbor = to_vec_minimal(&FirstVariant).unwrap(); |
| 187 | +//! assert_eq!(cbor.len(), 1); |
| 188 | +//! |
| 189 | +//! let cbor = to_vec_minimal(&SecondVariant(0)).unwrap(); |
| 190 | +//! assert_eq!(cbor.len(), 3); |
| 191 | +//! ``` |
| 192 | +//! |
135 | 193 | //! # `no-std` support |
136 | 194 | //! |
137 | 195 | //! Serde CBOR supports building in a `no_std` context, use the following lines |
|
0 commit comments