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 | //! |
12 | //! See the Serde website <https://serde.rs/> for additional documentation and |
13 | //! usage examples. |
14 | //! |
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. |
34 | //! - [Postcard], a no\_std and embedded-systems friendly compact binary format. |
35 | //! - [CBOR], a Concise Binary Object Representation designed for small message |
36 | //! size without the need for version negotiation. |
37 | //! - [YAML], a self-proclaimed human-friendly configuration language that ain't |
38 | //! markup language. |
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. |
42 | //! - [RON], a Rusty Object Notation. |
43 | //! - [BSON], the data storage and network transfer format used by MongoDB. |
44 | //! - [Avro], a binary format used within Apache Hadoop, with support for schema |
45 | //! definition. |
46 | //! - [JSON5], a superset of JSON including some productions from ES5. |
47 | //! - [URL] query strings, in the x-www-form-urlencoded format. |
48 | //! - [Starlark], the format used for describing build targets by the Bazel and |
49 | //! Buck build systems. *(serialization only)* |
50 | //! - [Envy], a way to deserialize environment variables into Rust structs. |
51 | //! *(deserialization only)* |
52 | //! - [Envy Store], a way to deserialize [AWS Parameter Store] parameters into |
53 | //! Rust structs. *(deserialization only)* |
54 | //! - [S-expressions], the textual representation of code and data used by the |
55 | //! Lisp language family. |
56 | //! - [D-Bus]'s binary wire format. |
57 | //! - [FlexBuffers], the schemaless cousin of Google's FlatBuffers zero-copy |
58 | //! serialization format. |
59 | //! - [Bencode], a simple binary format used in the BitTorrent protocol. |
60 | //! - [Token streams], for processing Rust procedural macro input. |
61 | //! *(deserialization only)* |
62 | //! - [DynamoDB Items], the format used by [rusoto_dynamodb] to transfer data to |
63 | //! and from DynamoDB. |
64 | //! - [Hjson], a syntax extension to JSON designed around human reading and |
65 | //! editing. *(deserialization only)* |
66 | //! |
67 | //! [JSON]: https://github.com/serde-rs/json |
68 | //! [Postcard]: https://github.com/jamesmunns/postcard |
69 | //! [CBOR]: https://github.com/enarx/ciborium |
70 | //! [YAML]: https://github.com/dtolnay/serde-yaml |
71 | //! [MessagePack]: https://github.com/3Hren/msgpack-rust |
72 | //! [TOML]: https://docs.rs/toml |
73 | //! [Pickle]: https://github.com/birkenfeld/serde-pickle |
74 | //! [RON]: https://github.com/ron-rs/ron |
75 | //! [BSON]: https://github.com/mongodb/bson-rust |
76 | //! [Avro]: https://docs.rs/apache-avro |
77 | //! [JSON5]: https://github.com/callum-oakley/json5-rs |
78 | //! [URL]: https://docs.rs/serde_qs |
79 | //! [Starlark]: https://github.com/dtolnay/serde-starlark |
80 | //! [Envy]: https://github.com/softprops/envy |
81 | //! [Envy Store]: https://github.com/softprops/envy-store |
82 | //! [Cargo]: https://doc.rust-lang.org/cargo/reference/manifest.html |
83 | //! [AWS Parameter Store]: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html |
84 | //! [S-expressions]: https://github.com/rotty/lexpr-rs |
85 | //! [D-Bus]: https://docs.rs/zvariant |
86 | //! [FlexBuffers]: https://github.com/google/flatbuffers/tree/master/rust/flexbuffers |
87 | //! [Bencode]: https://github.com/P3KI/bendy |
88 | //! [Token streams]: https://github.com/oxidecomputer/serde_tokenstream |
89 | //! [DynamoDB Items]: https://docs.rs/serde_dynamo |
90 | //! [rusoto_dynamodb]: https://docs.rs/rusoto_dynamodb |
91 | //! [Hjson]: https://github.com/Canop/deser-hjson |
92 | |
93 | //////////////////////////////////////////////////////////////////////////////// |
94 | |
95 | // Serde types in rustdoc of other crates get linked to here. |
96 | #![doc (html_root_url = "https://docs.rs/serde/1.0.185" )] |
97 | // Support using Serde without the standard library! |
98 | #![cfg_attr (not(feature = "std" ), no_std)] |
99 | // Unstable functionality only if the user asks for it. For tracking and |
100 | // discussion of these features please refer to this issue: |
101 | // |
102 | // https://github.com/serde-rs/serde/issues/812 |
103 | #![cfg_attr (feature = "unstable" , feature(error_in_core, never_type))] |
104 | #![allow (unknown_lints, bare_trait_objects, deprecated)] |
105 | // Ignored clippy and clippy_pedantic lints |
106 | #![allow ( |
107 | // clippy bug: https://github.com/rust-lang/rust-clippy/issues/5704 |
108 | clippy::unnested_or_patterns, |
109 | // clippy bug: https://github.com/rust-lang/rust-clippy/issues/7768 |
110 | clippy::semicolon_if_nothing_returned, |
111 | // not available in our oldest supported compiler |
112 | clippy::empty_enum, |
113 | clippy::type_repetition_in_bounds, // https://github.com/rust-lang/rust-clippy/issues/8772 |
114 | // integer and float ser/de requires these sorts of casts |
115 | clippy::cast_possible_truncation, |
116 | clippy::cast_possible_wrap, |
117 | clippy::cast_sign_loss, |
118 | // things are often more readable this way |
119 | clippy::cast_lossless, |
120 | clippy::module_name_repetitions, |
121 | clippy::option_if_let_else, |
122 | clippy::single_match_else, |
123 | clippy::type_complexity, |
124 | clippy::use_self, |
125 | clippy::zero_prefixed_literal, |
126 | // correctly used |
127 | clippy::derive_partial_eq_without_eq, |
128 | clippy::enum_glob_use, |
129 | clippy::explicit_auto_deref, |
130 | clippy::let_underscore_untyped, |
131 | clippy::map_err_ignore, |
132 | clippy::new_without_default, |
133 | clippy::result_unit_err, |
134 | clippy::wildcard_imports, |
135 | // not practical |
136 | clippy::needless_pass_by_value, |
137 | clippy::similar_names, |
138 | clippy::too_many_lines, |
139 | // preference |
140 | clippy::doc_markdown, |
141 | clippy::unseparated_literal_suffix, |
142 | // false positive |
143 | clippy::needless_doctest_main, |
144 | // noisy |
145 | clippy::missing_errors_doc, |
146 | clippy::must_use_candidate, |
147 | )] |
148 | // Restrictions |
149 | #![deny (clippy::question_mark_used)] |
150 | // Rustc lints. |
151 | #![deny (missing_docs, unused_imports)] |
152 | |
153 | //////////////////////////////////////////////////////////////////////////////// |
154 | |
155 | #[cfg (feature = "alloc" )] |
156 | extern crate alloc; |
157 | |
158 | /// A facade around all the types we need from the `std`, `core`, and `alloc` |
159 | /// crates. This avoids elaborate import wrangling having to happen in every |
160 | /// module. |
161 | mod lib { |
162 | mod core { |
163 | #[cfg (not(feature = "std" ))] |
164 | pub use core::*; |
165 | #[cfg (feature = "std" )] |
166 | pub use std::*; |
167 | } |
168 | |
169 | pub use self::core::{cmp, iter, mem, num, ptr, slice, str}; |
170 | pub use self::core::{f32, f64}; |
171 | pub use self::core::{i16, i32, i64, i8, isize}; |
172 | pub use self::core::{u16, u32, u64, u8, usize}; |
173 | |
174 | pub use self::core::cell::{Cell, RefCell}; |
175 | pub use self::core::clone::{self, Clone}; |
176 | pub use self::core::cmp::Reverse; |
177 | pub use self::core::convert::{self, From, Into}; |
178 | pub use self::core::default::{self, Default}; |
179 | pub use self::core::fmt::{self, Debug, Display}; |
180 | pub use self::core::marker::{self, PhantomData}; |
181 | pub use self::core::num::Wrapping; |
182 | pub use self::core::ops::{Bound, Range, RangeFrom, RangeInclusive, RangeTo}; |
183 | pub use self::core::option::{self, Option}; |
184 | pub use self::core::result::{self, Result}; |
185 | pub use self::core::time::Duration; |
186 | |
187 | #[cfg (all(feature = "alloc" , not(feature = "std" )))] |
188 | pub use alloc::borrow::{Cow, ToOwned}; |
189 | #[cfg (feature = "std" )] |
190 | pub use std::borrow::{Cow, ToOwned}; |
191 | |
192 | #[cfg (all(feature = "alloc" , not(feature = "std" )))] |
193 | pub use alloc::string::{String, ToString}; |
194 | #[cfg (feature = "std" )] |
195 | pub use std::string::{String, ToString}; |
196 | |
197 | #[cfg (all(feature = "alloc" , not(feature = "std" )))] |
198 | pub use alloc::vec::Vec; |
199 | #[cfg (feature = "std" )] |
200 | pub use std::vec::Vec; |
201 | |
202 | #[cfg (all(feature = "alloc" , not(feature = "std" )))] |
203 | pub use alloc::boxed::Box; |
204 | #[cfg (feature = "std" )] |
205 | pub use std::boxed::Box; |
206 | |
207 | #[cfg (all(feature = "rc" , feature = "alloc" , not(feature = "std" )))] |
208 | pub use alloc::rc::{Rc, Weak as RcWeak}; |
209 | #[cfg (all(feature = "rc" , feature = "std" ))] |
210 | pub use std::rc::{Rc, Weak as RcWeak}; |
211 | |
212 | #[cfg (all(feature = "rc" , feature = "alloc" , not(feature = "std" )))] |
213 | pub use alloc::sync::{Arc, Weak as ArcWeak}; |
214 | #[cfg (all(feature = "rc" , feature = "std" ))] |
215 | pub use std::sync::{Arc, Weak as ArcWeak}; |
216 | |
217 | #[cfg (all(feature = "alloc" , not(feature = "std" )))] |
218 | pub use alloc::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque}; |
219 | #[cfg (feature = "std" )] |
220 | pub use std::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque}; |
221 | |
222 | #[cfg (all(not(no_core_cstr), not(feature = "std" )))] |
223 | pub use self::core::ffi::CStr; |
224 | #[cfg (feature = "std" )] |
225 | pub use std::ffi::CStr; |
226 | |
227 | #[cfg (all(not(no_core_cstr), feature = "alloc" , not(feature = "std" )))] |
228 | pub use alloc::ffi::CString; |
229 | #[cfg (feature = "std" )] |
230 | pub use std::ffi::CString; |
231 | |
232 | #[cfg (feature = "std" )] |
233 | pub use std::{error, net}; |
234 | |
235 | #[cfg (feature = "std" )] |
236 | pub use std::collections::{HashMap, HashSet}; |
237 | #[cfg (feature = "std" )] |
238 | pub use std::ffi::{OsStr, OsString}; |
239 | #[cfg (feature = "std" )] |
240 | pub use std::hash::{BuildHasher, Hash}; |
241 | #[cfg (feature = "std" )] |
242 | pub use std::io::Write; |
243 | #[cfg (feature = "std" )] |
244 | pub use std::path::{Path, PathBuf}; |
245 | #[cfg (feature = "std" )] |
246 | pub use std::sync::{Mutex, RwLock}; |
247 | #[cfg (feature = "std" )] |
248 | pub use std::time::{SystemTime, UNIX_EPOCH}; |
249 | |
250 | #[cfg (all(feature = "std" , no_target_has_atomic, not(no_std_atomic)))] |
251 | pub use std::sync::atomic::{ |
252 | AtomicBool, AtomicI16, AtomicI32, AtomicI8, AtomicIsize, AtomicU16, AtomicU32, AtomicU8, |
253 | AtomicUsize, Ordering, |
254 | }; |
255 | #[cfg (all(feature = "std" , no_target_has_atomic, not(no_std_atomic64)))] |
256 | pub use std::sync::atomic::{AtomicI64, AtomicU64}; |
257 | |
258 | #[cfg (all(feature = "std" , not(no_target_has_atomic)))] |
259 | pub use std::sync::atomic::Ordering; |
260 | #[cfg (all(feature = "std" , not(no_target_has_atomic), target_has_atomic = "8" ))] |
261 | pub use std::sync::atomic::{AtomicBool, AtomicI8, AtomicU8}; |
262 | #[cfg (all(feature = "std" , not(no_target_has_atomic), target_has_atomic = "16" ))] |
263 | pub use std::sync::atomic::{AtomicI16, AtomicU16}; |
264 | #[cfg (all(feature = "std" , not(no_target_has_atomic), target_has_atomic = "32" ))] |
265 | pub use std::sync::atomic::{AtomicI32, AtomicU32}; |
266 | #[cfg (all(feature = "std" , not(no_target_has_atomic), target_has_atomic = "64" ))] |
267 | pub use std::sync::atomic::{AtomicI64, AtomicU64}; |
268 | #[cfg (all(feature = "std" , not(no_target_has_atomic), target_has_atomic = "ptr" ))] |
269 | pub use std::sync::atomic::{AtomicIsize, AtomicUsize}; |
270 | } |
271 | |
272 | // None of this crate's error handling needs the `From::from` error conversion |
273 | // performed implicitly by the `?` operator or the standard library's `try!` |
274 | // macro. This simplified macro gives a 5.5% improvement in compile time |
275 | // compared to standard `try!`, and 9% improvement compared to `?`. |
276 | macro_rules! tri { |
277 | ($expr:expr) => { |
278 | match $expr { |
279 | Ok(val) => val, |
280 | Err(err) => return Err(err), |
281 | } |
282 | }; |
283 | } |
284 | |
285 | //////////////////////////////////////////////////////////////////////////////// |
286 | |
287 | #[macro_use ] |
288 | mod macros; |
289 | |
290 | #[macro_use ] |
291 | mod integer128; |
292 | |
293 | pub mod de; |
294 | pub mod ser; |
295 | |
296 | #[doc (inline)] |
297 | pub use crate::de::{Deserialize, Deserializer}; |
298 | #[doc (inline)] |
299 | pub use crate::ser::{Serialize, Serializer}; |
300 | |
301 | // Used by generated code and doc tests. Not public API. |
302 | #[doc (hidden)] |
303 | #[path = "private/mod.rs" ] |
304 | pub mod __private; |
305 | |
306 | #[path = "de/seed.rs" ] |
307 | mod seed; |
308 | |
309 | #[cfg (not(any(feature = "std" , feature = "unstable" )))] |
310 | mod std_error; |
311 | |
312 | // Re-export #[derive(Serialize, Deserialize)]. |
313 | // |
314 | // The reason re-exporting is not enabled by default is that disabling it would |
315 | // be annoying for crates that provide handwritten impls or data formats. They |
316 | // would need to disable default features and then explicitly re-enable std. |
317 | #[cfg (feature = "serde_derive" )] |
318 | extern crate serde_derive; |
319 | |
320 | /// Derive macro available if serde is built with `features = ["derive"]`. |
321 | #[cfg (feature = "serde_derive" )] |
322 | pub use serde_derive::{Deserialize, Serialize}; |
323 | |
324 | #[cfg (all(not(no_serde_derive), any(feature = "std" , feature = "alloc" )))] |
325 | mod actually_private { |
326 | pub struct T; |
327 | } |
328 | |