musli_storage/
lib.rs

1//! [<img alt="github" src="https://img.shields.io/badge/github-udoprog/musli-8da0cb?style=for-the-badge&logo=github" height="20">](https://github.com/udoprog/musli)
2//! [<img alt="crates.io" src="https://img.shields.io/crates/v/musli-storage.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/musli-storage)
3//! [<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-musli--storage-66c2a5?style=for-the-badge&logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K" height="20">](https://docs.rs/musli-storage)
4//!
5//! Super simple storage encoding for [Müsli]
6//!
7//! The storage encoding is partially upgrade safe:
8//!
9//! * ✔ Can tolerate missing fields if they are annotated with
10//!   `#[musli(default)]`.
11//! * ✗ Cannot skip over extra unrecognized fields.
12//!
13//! This means that it's suitable as a storage format, since the data model only
14//! evolves in one place. But unsuitable as a wire format since it cannot allow
15//! clients to upgrade independent of each other.
16//!
17//! See [musli-wire] for a fully upgrade safe format.
18//!
19//! ```
20//! use musli::{Encode, Decode};
21//!
22//! #[derive(Debug, PartialEq, Encode, Decode)]
23//! struct Version1 {
24//!     name: String,
25//! }
26//!
27//! #[derive(Debug, PartialEq, Encode, Decode)]
28//! struct Version2 {
29//!     name: String,
30//!     #[musli(default)]
31//!     age: Option<u32>,
32//! }
33//!
34//! let version2 = musli_storage::to_vec(&Version2 {
35//!     name: String::from("Aristotle"),
36//!     age: Some(62),
37//! })?;
38//!
39//! assert!(musli_storage::decode::<_, Version1>(version2.as_slice()).is_err());
40//!
41//! let version1 = musli_storage::to_vec(&Version1 {
42//!     name: String::from("Aristotle"),
43//! })?;
44//!
45//! let version2: Version2 = musli_storage::decode(version1.as_slice())?;
46//!
47//! assert_eq!(version2, Version2 {
48//!     name: String::from("Aristotle"),
49//!     age: None,
50//! });
51//! # Ok::<_, musli_storage::Error>(())
52//! ```
53//!
54//! <br>
55//!
56//! ## Configuring
57//!
58//! To tweak the behavior of the storage format you can use the [`Encoding`]
59//! type:
60//!
61//! ```
62//! use musli::mode::Binary;
63//! use musli::{Encode, Decode};
64//! use musli_utils::options::{self, Options, Integer};
65//! use musli_storage::Encoding;
66//!
67//! const OPTIONS: Options = options::new().with_integer(Integer::Fixed).build();
68//! const CONFIG: Encoding<OPTIONS> = Encoding::new().with_options();
69//!
70//! #[derive(Debug, PartialEq, Encode, Decode)]
71//! struct Struct<'a> {
72//!     name: &'a str,
73//!     age: u32,
74//! }
75//!
76//! let mut out = Vec::new();
77//!
78//! let expected = Struct {
79//!     name: "Aristotle",
80//!     age: 61,
81//! };
82//!
83//! CONFIG.encode(&mut out, &expected)?;
84//! let actual = CONFIG.decode(&out[..])?;
85//!
86//! assert_eq!(expected, actual);
87//! # Ok::<_, musli_storage::Error>(())
88//! ```
89//!
90//! [default encoding format]: https://docs.rs/musli-storage/latest/musli-storage/struct.Encoding.html
91//! [musli-wire]: https://docs.rs/musli-wire
92//! [Müsli]: https://docs.rs/musli
93//! [`Encoding`]:
94//!     https://docs.rs/musli-storage/latest/musli-storage/struct.Encoding.html
95
96#![deny(missing_docs)]
97#![no_std]
98#![cfg_attr(doc_cfg, feature(doc_cfg))]
99
100#[cfg(feature = "std")]
101extern crate std;
102
103#[cfg(feature = "alloc")]
104extern crate alloc;
105
106#[doc(hidden)]
107pub mod de;
108#[doc(hidden)]
109pub mod en;
110pub mod encoding;
111mod error;
112#[cfg(feature = "test")]
113#[cfg_attr(doc_cfg, doc(cfg(feature = "test")))]
114#[doc(hidden)]
115pub mod test;
116
117/// Convenient result alias for use with `musli_storage`.
118pub type Result<T, E = Error> = core::result::Result<T, E>;
119
120#[cfg(feature = "alloc")]
121#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))]
122#[doc(inline)]
123pub use self::encoding::to_vec;
124#[cfg(feature = "std")]
125#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
126#[doc(inline)]
127pub use self::encoding::to_writer;
128#[doc(inline)]
129pub use self::encoding::{decode, encode, from_slice, to_fixed_bytes, Encoding, OPTIONS};
130#[doc(inline)]
131pub use self::error::Error;
132#[cfg(feature = "test")]
133#[cfg_attr(doc_cfg, doc(cfg(feature = "test")))]
134#[doc(hidden)]
135pub use self::test::transcode;
136
137musli_utils::simdutf8!();
musli_storage/lib.rs

musli_storage/
lib.rs
