musli/storage/
mod.rs

Help
1//! Efficient binary storage encoding for Müsli.
2//!
3//! The storage encoding is partially upgrade safe:
4//!
5//! * ✔ Can tolerate missing fields if they are annotated with
6//!   `#[musli(default)]`.
7//! * ✗ Cannot skip over extra unrecognized fields.
8//!
9//! This means that it's suitable as a storage format, since the data model only
10//! evolves in one place. But unsuitable as a wire format since it cannot allow
11//! clients to upgrade independent of each other.
12//!
13//! See [`wire`] or [`descriptive`] for formats which are upgrade stable.
14//!
15//! [`descriptive`]: crate::descriptive
16//! [`wire`]: crate::wire
17//!
18//! ```
19//! use musli::{Encode, Decode};
20//!
21//! #[derive(Debug, PartialEq, Encode, Decode)]
22//! struct Version1 {
23//!     name: String,
24//! }
25//!
26//! #[derive(Debug, PartialEq, Encode, Decode)]
27//! struct Version2 {
28//!     name: String,
29//!     #[musli(default)]
30//!     age: Option<u32>,
31//! }
32//!
33//! let version2 = musli::storage::to_vec(&Version2 {
34//!     name: String::from("Aristotle"),
35//!     age: Some(61),
36//! })?;
37//!
38//! assert!(musli::storage::decode::<_, Version1>(version2.as_slice()).is_err());
39//!
40//! let version1 = musli::storage::to_vec(&Version1 {
41//!     name: String::from("Aristotle"),
42//! })?;
43//!
44//! let version2: Version2 = musli::storage::decode(version1.as_slice())?;
45//!
46//! assert_eq!(version2, Version2 {
47//!     name: String::from("Aristotle"),
48//!     age: None,
49//! });
50//! # Ok::<_, musli::storage::Error>(())
51//! ```
52//!
53//! <br>
54//!
55//! ## Configuring
56//!
57//! To tweak the behavior of the storage format you can use the [`Encoding`]
58//! type:
59//!
60//! ```
61//! use musli::{Encode, Decode};
62//! use musli::mode::Binary;
63//! use musli::options::{self, Options, Integer};
64//! use musli::storage::Encoding;
65//!
66//! const OPTIONS: Options = options::new().with_integer(Integer::Fixed).build();
67//! const CONFIG: Encoding<OPTIONS> = Encoding::new().with_options();
68//!
69//! #[derive(Debug, PartialEq, Encode, Decode)]
70//! struct Person<'a> {
71//!     name: &'a str,
72//!     age: u32,
73//! }
74//!
75//! let mut out = Vec::new();
76//!
77//! let expected = Person {
78//!     name: "Aristotle",
79//!     age: 61,
80//! };
81//!
82//! CONFIG.encode(&mut out, &expected)?;
83//! let actual = CONFIG.decode(&out[..])?;
84//!
85//! assert_eq!(expected, actual);
86//! # Ok::<_, musli::storage::Error>(())
87//! ```
88
89#![cfg(any(
90    feature = "storage",
91    feature = "wire",
92    feature = "descriptive",
93    feature = "value"
94))]
95#![cfg_attr(doc_cfg, doc(cfg(feature = "storage")))]
96
97pub(crate) mod de;
98pub(crate) mod en;
99mod encoding;
100mod error;
101
102#[cfg(feature = "test")]
103#[cfg_attr(doc_cfg, doc(cfg(feature = "test")))]
104#[doc(hidden)]
105pub mod test;
106
107/// Convenient result alias for use with `musli::storage`.
108pub type Result<T, E = Error> = core::result::Result<T, E>;
109
110#[cfg(feature = "alloc")]
111#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))]
112#[doc(inline)]
113pub use self::encoding::to_vec;
114#[cfg(feature = "std")]
115#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
116#[doc(inline)]
117pub use self::encoding::to_writer;
118#[doc(inline)]
119pub use self::encoding::{decode, encode, from_slice, to_fixed_bytes, Encoding, DEFAULT, OPTIONS};
120#[doc(inline)]
121pub use self::error::Error;
musli/storage/mod.rs

musli/storage/
mod.rs
