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