]>
Commit | Line | Data |
---|---|---|
041b39d2 XL |
1 | //! # Serde |
2 | //! | |
3 | //! Serde is a framework for ***ser***ializing and ***de***serializing Rust data | |
4 | //! structures efficiently and generically. | |
5 | //! | |
6 | //! The Serde ecosystem consists of data structures that know how to serialize | |
7 | //! and deserialize themselves along with data formats that know how to | |
8 | //! serialize and deserialize other things. Serde provides the layer by which | |
9 | //! these two groups interact with each other, allowing any supported data | |
10 | //! structure to be serialized and deserialized using any supported data format. | |
11 | //! | |
5869c6ff | 12 | //! See the Serde website <https://serde.rs/> for additional documentation and |
041b39d2 XL |
13 | //! usage examples. |
14 | //! | |
041b39d2 XL |
15 | //! ## Design |
16 | //! | |
17 | //! Where many other languages rely on runtime reflection for serializing data, | |
18 | //! Serde is instead built on Rust's powerful trait system. A data structure | |
19 | //! that knows how to serialize and deserialize itself is one that implements | |
20 | //! Serde's `Serialize` and `Deserialize` traits (or uses Serde's derive | |
21 | //! attribute to automatically generate implementations at compile time). This | |
22 | //! avoids any overhead of reflection or runtime type information. In fact in | |
23 | //! many situations the interaction between data structure and data format can | |
24 | //! be completely optimized away by the Rust compiler, leaving Serde | |
25 | //! serialization to perform the same speed as a handwritten serializer for the | |
26 | //! specific selection of data structure and data format. | |
27 | //! | |
28 | //! ## Data formats | |
29 | //! | |
30 | //! The following is a partial list of data formats that have been implemented | |
31 | //! for Serde by the community. | |
32 | //! | |
33 | //! - [JSON], the ubiquitous JavaScript Object Notation used by many HTTP APIs. | |
f2b60f7d | 34 | //! - [Postcard], a no\_std and embedded-systems friendly compact binary format. |
041b39d2 XL |
35 | //! - [CBOR], a Concise Binary Object Representation designed for small message |
36 | //! size without the need for version negotiation. | |
3dfed10e XL |
37 | //! - [YAML], a self-proclaimed human-friendly configuration language that ain't |
38 | //! markup language. | |
041b39d2 XL |
39 | //! - [MessagePack], an efficient binary format that resembles a compact JSON. |
40 | //! - [TOML], a minimal configuration format used by [Cargo]. | |
41 | //! - [Pickle], a format common in the Python world. | |
0731742a | 42 | //! - [RON], a Rusty Object Notation. |
041b39d2 | 43 | //! - [BSON], the data storage and network transfer format used by MongoDB. |
8faf50e0 XL |
44 | //! - [Avro], a binary format used within Apache Hadoop, with support for schema |
45 | //! definition. | |
6a06907d | 46 | //! - [JSON5], a superset of JSON including some productions from ES5. |
1b1a35ee | 47 | //! - [URL] query strings, in the x-www-form-urlencoded format. |
041b39d2 XL |
48 | //! - [Envy], a way to deserialize environment variables into Rust structs. |
49 | //! *(deserialization only)* | |
0731742a XL |
50 | //! - [Envy Store], a way to deserialize [AWS Parameter Store] parameters into |
51 | //! Rust structs. *(deserialization only)* | |
f035d41b XL |
52 | //! - [S-expressions], the textual representation of code and data used by the |
53 | //! Lisp language family. | |
54 | //! - [D-Bus]'s binary wire format. | |
55 | //! - [FlexBuffers], the schemaless cousin of Google's FlatBuffers zero-copy serialization format. | |
5869c6ff XL |
56 | //! - [DynamoDB Items], the format used by [rusoto_dynamodb] to transfer data to |
57 | //! and from DynamoDB. | |
041b39d2 XL |
58 | //! |
59 | //! [JSON]: https://github.com/serde-rs/json | |
f2b60f7d | 60 | //! [Postcard]: https://github.com/jamesmunns/postcard |
a2a8927a | 61 | //! [CBOR]: https://github.com/enarx/ciborium |
041b39d2 XL |
62 | //! [YAML]: https://github.com/dtolnay/serde-yaml |
63 | //! [MessagePack]: https://github.com/3Hren/msgpack-rust | |
64 | //! [TOML]: https://github.com/alexcrichton/toml-rs | |
65 | //! [Pickle]: https://github.com/birkenfeld/serde-pickle | |
0731742a | 66 | //! [RON]: https://github.com/ron-rs/ron |
923072b8 | 67 | //! [BSON]: https://github.com/mongodb/bson-rust |
8faf50e0 | 68 | //! [Avro]: https://github.com/flavray/avro-rs |
0731742a | 69 | //! [JSON5]: https://github.com/callum-oakley/json5-rs |
1b1a35ee | 70 | //! [URL]: https://docs.rs/serde_qs |
041b39d2 | 71 | //! [Envy]: https://github.com/softprops/envy |
0731742a | 72 | //! [Envy Store]: https://github.com/softprops/envy-store |
a2a8927a | 73 | //! [Cargo]: https://doc.rust-lang.org/cargo/reference/manifest.html |
923072b8 | 74 | //! [AWS Parameter Store]: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html |
f035d41b XL |
75 | //! [S-expressions]: https://github.com/rotty/lexpr-rs |
76 | //! [D-Bus]: https://docs.rs/zvariant | |
77 | //! [FlexBuffers]: https://github.com/google/flatbuffers/tree/master/rust/flexbuffers | |
5869c6ff XL |
78 | //! [DynamoDB Items]: https://docs.rs/serde_dynamo |
79 | //! [rusoto_dynamodb]: https://docs.rs/rusoto_dynamodb | |
041b39d2 XL |
80 | |
81 | //////////////////////////////////////////////////////////////////////////////// | |
82 | ||
83 | // Serde types in rustdoc of other crates get linked to here. | |
f2b60f7d | 84 | #![doc(html_root_url = "https://docs.rs/serde/1.0.143")] |
041b39d2 XL |
85 | // Support using Serde without the standard library! |
86 | #![cfg_attr(not(feature = "std"), no_std)] | |
041b39d2 XL |
87 | // Unstable functionality only if the user asks for it. For tracking and |
88 | // discussion of these features please refer to this issue: | |
89 | // | |
90 | // https://github.com/serde-rs/serde/issues/812 | |
f035d41b | 91 | #![cfg_attr(feature = "unstable", feature(never_type))] |
e1599b0c | 92 | #![allow(unknown_lints, bare_trait_objects, deprecated)] |
0731742a | 93 | #![cfg_attr(feature = "cargo-clippy", allow(renamed_and_removed_lints))] |
dc9dc135 | 94 | // Ignored clippy and clippy_pedantic lints |
83c7162d XL |
95 | #![cfg_attr( |
96 | feature = "cargo-clippy", | |
97 | allow( | |
f035d41b XL |
98 | // clippy bug: https://github.com/rust-lang/rust-clippy/issues/5704 |
99 | unnested_or_patterns, | |
a2a8927a XL |
100 | // clippy bug: https://github.com/rust-lang/rust-clippy/issues/7768 |
101 | semicolon_if_nothing_returned, | |
dc9dc135 | 102 | // not available in our oldest supported compiler |
dc9dc135 | 103 | empty_enum, |
923072b8 | 104 | type_repetition_in_bounds, // https://github.com/rust-lang/rust-clippy/issues/8772 |
dc9dc135 XL |
105 | // integer and float ser/de requires these sorts of casts |
106 | cast_possible_truncation, | |
107 | cast_possible_wrap, | |
dc9dc135 XL |
108 | cast_sign_loss, |
109 | // things are often more readable this way | |
110 | cast_lossless, | |
111 | module_name_repetitions, | |
3dfed10e | 112 | option_if_let_else, |
dc9dc135 | 113 | single_match_else, |
b7449926 | 114 | type_complexity, |
dc9dc135 XL |
115 | use_self, |
116 | zero_prefixed_literal, | |
f035d41b | 117 | // correctly used |
064997fb | 118 | derive_partial_eq_without_eq, |
f035d41b | 119 | enum_glob_use, |
064997fb | 120 | explicit_auto_deref, |
6a06907d | 121 | let_underscore_drop, |
fc512014 | 122 | map_err_ignore, |
064997fb | 123 | new_without_default, |
fc512014 | 124 | result_unit_err, |
f035d41b | 125 | wildcard_imports, |
dc9dc135 XL |
126 | // not practical |
127 | needless_pass_by_value, | |
128 | similar_names, | |
f035d41b | 129 | too_many_lines, |
dc9dc135 XL |
130 | // preference |
131 | doc_markdown, | |
f035d41b XL |
132 | unseparated_literal_suffix, |
133 | // false positive | |
134 | needless_doctest_main, | |
135 | // noisy | |
136 | missing_errors_doc, | |
137 | must_use_candidate, | |
83c7162d XL |
138 | ) |
139 | )] | |
dc9dc135 XL |
140 | // Rustc lints. |
141 | #![deny(missing_docs, unused_imports)] | |
041b39d2 XL |
142 | |
143 | //////////////////////////////////////////////////////////////////////////////// | |
144 | ||
145 | #[cfg(feature = "alloc")] | |
146 | extern crate alloc; | |
147 | ||
041b39d2 XL |
148 | /// A facade around all the types we need from the `std`, `core`, and `alloc` |
149 | /// crates. This avoids elaborate import wrangling having to happen in every | |
150 | /// module. | |
151 | mod lib { | |
152 | mod core { | |
041b39d2 XL |
153 | #[cfg(not(feature = "std"))] |
154 | pub use core::*; | |
83c7162d XL |
155 | #[cfg(feature = "std")] |
156 | pub use std::*; | |
041b39d2 XL |
157 | } |
158 | ||
c295e0f8 | 159 | pub use self::core::{cmp, iter, mem, num, ptr, slice, str}; |
041b39d2 | 160 | pub use self::core::{f32, f64}; |
83c7162d XL |
161 | pub use self::core::{i16, i32, i64, i8, isize}; |
162 | pub use self::core::{u16, u32, u64, u8, usize}; | |
041b39d2 XL |
163 | |
164 | pub use self::core::cell::{Cell, RefCell}; | |
165 | pub use self::core::clone::{self, Clone}; | |
166 | pub use self::core::convert::{self, From, Into}; | |
167 | pub use self::core::default::{self, Default}; | |
168 | pub use self::core::fmt::{self, Debug, Display}; | |
169 | pub use self::core::marker::{self, PhantomData}; | |
fc512014 | 170 | pub use self::core::num::Wrapping; |
b7449926 | 171 | pub use self::core::ops::Range; |
041b39d2 XL |
172 | pub use self::core::option::{self, Option}; |
173 | pub use self::core::result::{self, Result}; | |
174 | ||
041b39d2 XL |
175 | #[cfg(all(feature = "alloc", not(feature = "std")))] |
176 | pub use alloc::borrow::{Cow, ToOwned}; | |
041b39d2 | 177 | #[cfg(feature = "std")] |
83c7162d XL |
178 | pub use std::borrow::{Cow, ToOwned}; |
179 | ||
041b39d2 XL |
180 | #[cfg(all(feature = "alloc", not(feature = "std")))] |
181 | pub use alloc::string::{String, ToString}; | |
041b39d2 | 182 | #[cfg(feature = "std")] |
dc9dc135 | 183 | pub use std::string::{String, ToString}; |
83c7162d | 184 | |
041b39d2 XL |
185 | #[cfg(all(feature = "alloc", not(feature = "std")))] |
186 | pub use alloc::vec::Vec; | |
041b39d2 | 187 | #[cfg(feature = "std")] |
83c7162d XL |
188 | pub use std::vec::Vec; |
189 | ||
041b39d2 XL |
190 | #[cfg(all(feature = "alloc", not(feature = "std")))] |
191 | pub use alloc::boxed::Box; | |
83c7162d XL |
192 | #[cfg(feature = "std")] |
193 | pub use std::boxed::Box; | |
041b39d2 | 194 | |
041b39d2 | 195 | #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))] |
8faf50e0 | 196 | pub use alloc::rc::{Rc, Weak as RcWeak}; |
041b39d2 | 197 | #[cfg(all(feature = "rc", feature = "std"))] |
8faf50e0 | 198 | pub use std::rc::{Rc, Weak as RcWeak}; |
83c7162d | 199 | |
041b39d2 | 200 | #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))] |
b7449926 | 201 | pub use alloc::sync::{Arc, Weak as ArcWeak}; |
83c7162d | 202 | #[cfg(all(feature = "rc", feature = "std"))] |
8faf50e0 | 203 | pub use std::sync::{Arc, Weak as ArcWeak}; |
041b39d2 | 204 | |
041b39d2 | 205 | #[cfg(all(feature = "alloc", not(feature = "std")))] |
8faf50e0 | 206 | pub use alloc::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque}; |
83c7162d XL |
207 | #[cfg(feature = "std")] |
208 | pub use std::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque}; | |
041b39d2 XL |
209 | |
210 | #[cfg(feature = "std")] | |
211 | pub use std::{error, net}; | |
212 | ||
213 | #[cfg(feature = "std")] | |
214 | pub use std::collections::{HashMap, HashSet}; | |
215 | #[cfg(feature = "std")] | |
ff7c6d11 | 216 | pub use std::ffi::{CStr, CString, OsStr, OsString}; |
041b39d2 | 217 | #[cfg(feature = "std")] |
ff7c6d11 | 218 | pub use std::hash::{BuildHasher, Hash}; |
041b39d2 XL |
219 | #[cfg(feature = "std")] |
220 | pub use std::io::Write; | |
221 | #[cfg(feature = "std")] | |
222 | pub use std::path::{Path, PathBuf}; | |
223 | #[cfg(feature = "std")] | |
041b39d2 | 224 | pub use std::sync::{Mutex, RwLock}; |
83c7162d | 225 | #[cfg(feature = "std")] |
8faf50e0 | 226 | pub use std::time::{SystemTime, UNIX_EPOCH}; |
0531ce1d | 227 | |
5099ac24 | 228 | #[cfg(all(feature = "std", not(no_collections_bound), no_ops_bound))] |
dc9dc135 XL |
229 | pub use std::collections::Bound; |
230 | ||
5099ac24 | 231 | #[cfg(not(no_core_reverse))] |
dc9dc135 XL |
232 | pub use self::core::cmp::Reverse; |
233 | ||
5099ac24 | 234 | #[cfg(not(no_ops_bound))] |
dc9dc135 | 235 | pub use self::core::ops::Bound; |
b7449926 | 236 | |
5099ac24 | 237 | #[cfg(not(no_range_inclusive))] |
b7449926 | 238 | pub use self::core::ops::RangeInclusive; |
dc9dc135 | 239 | |
5099ac24 | 240 | #[cfg(all(feature = "std", not(no_std_atomic)))] |
e1599b0c XL |
241 | pub use std::sync::atomic::{ |
242 | AtomicBool, AtomicI16, AtomicI32, AtomicI8, AtomicIsize, AtomicU16, AtomicU32, AtomicU8, | |
243 | AtomicUsize, Ordering, | |
244 | }; | |
5099ac24 | 245 | #[cfg(all(feature = "std", not(no_std_atomic64)))] |
e1599b0c XL |
246 | pub use std::sync::atomic::{AtomicI64, AtomicU64}; |
247 | ||
5099ac24 | 248 | #[cfg(any(feature = "std", not(no_core_duration)))] |
dc9dc135 | 249 | pub use self::core::time::Duration; |
041b39d2 XL |
250 | } |
251 | ||
252 | //////////////////////////////////////////////////////////////////////////////// | |
253 | ||
254 | #[macro_use] | |
255 | mod macros; | |
256 | ||
8faf50e0 XL |
257 | #[macro_use] |
258 | mod integer128; | |
259 | ||
041b39d2 | 260 | pub mod de; |
83c7162d | 261 | pub mod ser; |
041b39d2 | 262 | |
041b39d2 XL |
263 | #[doc(inline)] |
264 | pub use de::{Deserialize, Deserializer}; | |
83c7162d XL |
265 | #[doc(inline)] |
266 | pub use ser::{Serialize, Serializer}; | |
041b39d2 | 267 | |
5869c6ff | 268 | // Used by generated code and doc tests. Not public API. |
041b39d2 | 269 | #[doc(hidden)] |
5869c6ff XL |
270 | #[path = "private/mod.rs"] |
271 | pub mod __private; | |
041b39d2 | 272 | |
5869c6ff XL |
273 | #[allow(unused_imports)] |
274 | use self::__private as export; | |
275 | #[allow(unused_imports)] | |
276 | use self::__private as private; | |
277 | ||
278 | #[path = "de/seed.rs"] | |
279 | mod seed; | |
041b39d2 | 280 | |
f035d41b XL |
281 | #[cfg(not(feature = "std"))] |
282 | mod std_error; | |
283 | ||
041b39d2 XL |
284 | // Re-export #[derive(Serialize, Deserialize)]. |
285 | // | |
041b39d2 XL |
286 | // The reason re-exporting is not enabled by default is that disabling it would |
287 | // be annoying for crates that provide handwritten impls or data formats. They | |
288 | // would need to disable default features and then explicitly re-enable std. | |
289 | #[cfg(feature = "serde_derive")] | |
290 | #[allow(unused_imports)] | |
291 | #[macro_use] | |
292 | extern crate serde_derive; | |
293 | #[cfg(feature = "serde_derive")] | |
294 | #[doc(hidden)] | |
295 | pub use serde_derive::*; | |
5099ac24 FG |
296 | |
297 | #[cfg(all(not(no_serde_derive), any(feature = "std", feature = "alloc")))] | |
298 | mod actually_private { | |
299 | pub struct T; | |
300 | } |