musli_wire/
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-wire.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/musli-wire)
3//! [<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-musli--wire-66c2a5?style=for-the-badge&logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K" height="20">](https://docs.rs/musli-wire)
4//!
5//! Fully upgrade stable format for [Müsli] suitable for network communication.
6//!
7//! Wire 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//!
13//! This means that it's suitable as a wire format, since the data model can
14//! evolve independently among clients. Once some clients are upgraded they will
15//! start sending unknown fields which non-upgraded clients will be forced to
16//! skip over for the duration of the upgrade.
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//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
34//! let version2 = musli_wire::to_vec(&Version2 {
35//!     name: String::from("Aristotle"),
36//!     age: Some(62),
37//! })?;
38//!
39//! let version1: Version1 = musli_wire::decode(version2.as_slice())?;
40//!
41//! assert_eq!(version1, Version1 {
42//!     name: String::from("Aristotle"),
43//! });
44//! # Ok(()) }
45//! ```
46//!
47//! <br>
48//!
49//! ## Configuring
50//!
51//! To configure the behavior of the wire format you can use the [`Encoding`]
52//! type:
53//!
54//! ```
55//! use musli::{Encode, Decode};
56//! use musli_utils::options::{self, Options, Integer};
57//! use musli_wire::Encoding;
58//!
59//! const OPTIONS: Options = options::new().with_integer(Integer::Fixed).build();
60//! const CONFIG: Encoding<OPTIONS> = Encoding::new().with_options();
61//!
62//! #[derive(Debug, PartialEq, Encode, Decode)]
63//! struct Struct<'a> {
64//!     name: &'a str,
65//!     age: u32,
66//! }
67//!
68//! let mut out = Vec::new();
69//!
70//! let expected = Struct {
71//!     name: "Aristotle",
72//!     age: 61,
73//! };
74//!
75//! CONFIG.encode(&mut out, &expected)?;
76//! let actual = CONFIG.decode(&out[..])?;
77//!
78//! assert_eq!(expected, actual);
79//! # Ok::<_, musli_wire::Error>(())
80//! ```
81//!
82//! <br>
83//!
84//! ## Implementation details
85//!
86//! Each field is prefix *typed* with a single byte tag that allows a receiver
87//! to figure out exactly how much should be skipped over.
88//!
89//! Packed items are prefix-length encoded, and have a limited size. Its exact
90//! length is defined by [MAX_INLINE_LEN] and can be modified with
91//! [Encoding::with_max_pack].
92//!
93//! [default encoding format]: https://docs.rs/musli-wire/latest/musli-wire/struct.Encoding.html
94//! [MAX_INLINE_LEN]: https://docs.rs/musli-wire/latest/musli_wire/tag/constant.MAX_INLINE_LEN.html
95//! [Müsli]: https://docs.rs/musli
96//! [Encoding::with_max_pack]: https://docs.rs/musli-wire/latest/musli_wire/encoding/struct.Encoding.html#method.with_max_pack
97//! [`Encoding`]: https://docs.rs/musli-wire/latest/musli-wire/struct.Encoding.html
98
99#![deny(missing_docs)]
100#![no_std]
101#![cfg_attr(doc_cfg, feature(doc_cfg))]
102
103#[cfg(feature = "alloc")]
104extern crate alloc;
105
106#[cfg(feature = "std")]
107extern crate std;
108
109#[cfg(test)]
110mod tests;
111
112mod de;
113mod en;
114pub mod encoding;
115mod error;
116pub mod tag;
117mod wire_int;
118
119#[cfg(feature = "test")]
120#[cfg_attr(doc_cfg, doc(cfg(feature = "test")))]
121#[doc(hidden)]
122#[macro_use]
123pub mod test;
124
125/// Convenient result alias for use with `musli_wire`.
126pub type Result<T, E = Error> = core::result::Result<T, E>;
127
128#[cfg(feature = "alloc")]
129#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))]
130#[doc(inline)]
131pub use self::encoding::to_vec;
132#[doc(inline)]
133#[cfg(feature = "std")]
134#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
135pub use self::encoding::to_writer;
136#[doc(inline)]
137pub use self::encoding::{decode, encode, from_slice, to_fixed_bytes, Encoding, OPTIONS};
138#[doc(inline)]
139pub use self::error::Error;
140#[cfg(feature = "test")]
141#[cfg_attr(doc_cfg, doc(cfg(feature = "test")))]
142#[doc(hidden)]
143pub use self::test::{transcode, Typed};
144
145musli_utils::simdutf8!();
musli_wire/lib.rs

musli_wire/
lib.rs
