musli_descriptive/
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-descriptive.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/musli-descriptive)
3//! [<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-musli--descriptive-66c2a5?style=for-the-badge&logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K" height="20">](https://docs.rs/musli-descriptive)
4//!
5//! A fully self-descriptive format for [Müsli].
6//!
7//! Descriptive encoding is fully upgrade stable:
8//!
9//! * ✔ Can tolerate missing fields if they are annotated with
10//!   `#[musli(default)]`.
11//! * ✔ Can skip over unknown fields.
12//! * ✔ Can be fully converted back and forth between dynamic containers such as
13//!   the [Value] type.
14//! * ✔ Can handle coercion from different types of primitive types, such as
15//!   signed to unsigned integers. So primitive field types can be assuming they
16//!   only inhabit compatible values.
17//!
18//! This means that it's suitable as a wire and general interchange format. It's
19//! also suitable for dynamically translating to and from different wire formats
20//! such as JSON without having access to the data model.
21//!
22//! ```
23//! use musli::{Encode, Decode};
24//!
25//! #[derive(Debug, PartialEq, Encode, Decode)]
26//! struct Version1 {
27//!     name: String,
28//! }
29//!
30//! #[derive(Debug, PartialEq, Encode, Decode)]
31//! struct Version2 {
32//!     name: String,
33//!     #[musli(default)]
34//!     age: Option<u32>,
35//! }
36//!
37//! let version2 = musli_descriptive::to_vec(&Version2 {
38//!     name: String::from("Aristotle"),
39//!     age: Some(62),
40//! })?;
41//!
42//! let version1: Version1 = musli_descriptive::decode(version2.as_slice())?;
43//!
44//! assert_eq!(version1, Version1 {
45//!     name: String::from("Aristotle"),
46//! });
47//! # Ok::<_, musli_descriptive::Error>(())
48//! ```
49//!
50//! <br>
51//!
52//! ## Configuring
53//!
54//! To configure the behavior of the wire format you can use the [`Encoding`]
55//! type:
56//!
57//! ```
58//! use musli_descriptive::Encoding;
59//! use musli::{Encode, Decode};
60//!
61//! const CONFIG: Encoding = Encoding::new();
62//!
63//! #[derive(Debug, PartialEq, Encode, Decode)]
64//! struct Struct<'a> {
65//!     name: &'a str,
66//!     age: u32,
67//! }
68//!
69//! let mut out = Vec::new();
70//!
71//! let expected = Struct {
72//!     name: "Aristotle",
73//!     age: 61,
74//! };
75//!
76//! CONFIG.encode(&mut out, &expected)?;
77//! let actual = CONFIG.decode(&out[..])?;
78//!
79//! assert_eq!(expected, actual);
80//! # Ok::<_, musli_descriptive::Error>(())
81//! ```
82//!
83//! <br>
84//!
85//! ## Implementation details
86//!
87//! Each field is prefix *typed* with a single byte tag that describes exactly
88//! the type which is contained in the field.
89//!
90//! [default encoding format]: https://docs.rs/musli-wire/latest/musli-wire/struct.Encoding.html
91//! [MAX_INLINE_LEN]: https://docs.rs/musli-wire/latest/musli_descriptive/tag/constant.MAX_INLINE_LEN.html
92//! [Müsli]: https://docs.rs/musli
93//! [`Encoding`]: https://docs.rs/musli-wire/latest/musli-wire/struct.Encoding.html
94//! [Value]: https://docs.rs/musli-value
95
96#![deny(missing_docs)]
97#![no_std]
98#![cfg_attr(doc_cfg, feature(doc_cfg))]
99
100#[cfg(feature = "alloc")]
101extern crate alloc;
102
103#[cfg(feature = "std")]
104extern crate std;
105
106#[cfg(test)]
107mod tests;
108
109mod de;
110mod en;
111pub mod encoding;
112mod error;
113mod integer_encoding;
114pub mod tag;
115#[cfg(feature = "test")]
116#[cfg_attr(doc_cfg, doc(cfg(feature = "test")))]
117#[doc(hidden)]
118#[macro_use]
119pub mod test;
120
121/// Convenient result alias for use with `musli_descriptive`.
122pub type Result<T, E = Error> = core::result::Result<T, E>;
123
124#[cfg(feature = "alloc")]
125#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))]
126#[doc(inline)]
127pub use self::encoding::to_vec;
128#[cfg(feature = "std")]
129#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
130#[doc(inline)]
131pub use self::encoding::to_writer;
132#[doc(inline)]
133pub use self::encoding::{decode, encode, from_slice, to_fixed_bytes, Encoding, OPTIONS};
134#[doc(inline)]
135pub use self::error::Error;
136#[cfg(feature = "test")]
137#[cfg_attr(doc_cfg, doc(cfg(feature = "test")))]
138#[doc(hidden)]
139pub use self::test::transcode;
140
141musli_utils::simdutf8!();
musli_descriptive/lib.rs

musli_descriptive/
lib.rs
