Skip to content
This repository was archived by the owner on Aug 15, 2021. It is now read-only.

Commit 3d6d7a2

Browse files
committed
Clarify packed format and provide an example that also uses legacy_enums()
Closes #173
1 parent 16c3c1c commit 3d6d7a2

1 file changed

Lines changed: 60 additions & 2 deletions

File tree

‎src/lib.rs‎

Lines changed: 60 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,11 +66,20 @@
6666
//! # Packed Encoding
6767
//! When serializing structs or enums in CBOR the keys or enum variant names will be serialized
6868
//! 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+
//!
7176
//! To serialize a document in this format use `Serializer::new(writer).packed_format()` or
7277
//! the shorthand `ser::to_vec_packed`. The deserialization works without any changes.
7378
//!
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+
//!
7483
//! # Self describing documents
7584
//! In some contexts different formats are used but there is no way to declare the format used
7685
//! out of band. For this reason CBOR has a magic number that may be added before any document.
@@ -132,6 +141,55 @@
132141
//! # }
133142
//! ```
134143
//!
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+
//!
135193
//! # `no-std` support
136194
//!
137195
//! Serde CBOR supports building in a `no_std` context, use the following lines

0 commit comments

Comments
 (0)