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.219")]
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(docsrs, feature(doc_cfg, rustdoc_internals))]
103#![cfg_attr(docsrs, allow(internal_features))]
104// Unstable functionality only if the user asks for it. For tracking and
105// discussion of these features please refer to this issue:
106//
107// https://github.com/serde-rs/serde/issues/812
108#![cfg_attr(feature = "unstable", feature(never_type))]
109#![allow(unknown_lints, bare_trait_objects, deprecated)]
110// Ignored clippy and clippy_pedantic lints
111#![allow(
112 // clippy bug: https://github.com/rust-lang/rust-clippy/issues/5704
113 clippy::unnested_or_patterns,
114 // clippy bug: https://github.com/rust-lang/rust-clippy/issues/7768
115 clippy::semicolon_if_nothing_returned,
116 // not available in our oldest supported compiler
117 clippy::empty_enum,
118 clippy::type_repetition_in_bounds, // https://github.com/rust-lang/rust-clippy/issues/8772
119 // integer and float ser/de requires these sorts of casts
120 clippy::cast_possible_truncation,
121 clippy::cast_possible_wrap,
122 clippy::cast_precision_loss,
123 clippy::cast_sign_loss,
124 // things are often more readable this way
125 clippy::cast_lossless,
126 clippy::module_name_repetitions,
127 clippy::single_match_else,
128 clippy::type_complexity,
129 clippy::use_self,
130 clippy::zero_prefixed_literal,
131 // correctly used
132 clippy::derive_partial_eq_without_eq,
133 clippy::enum_glob_use,
134 clippy::explicit_auto_deref,
135 clippy::incompatible_msrv,
136 clippy::let_underscore_untyped,
137 clippy::map_err_ignore,
138 clippy::new_without_default,
139 clippy::result_unit_err,
140 clippy::wildcard_imports,
141 // not practical
142 clippy::needless_pass_by_value,
143 clippy::similar_names,
144 clippy::too_many_lines,
145 // preference
146 clippy::doc_markdown,
147 clippy::elidable_lifetime_names,
148 clippy::needless_lifetimes,
149 clippy::unseparated_literal_suffix,
150 // false positive
151 clippy::needless_doctest_main,
152 // noisy
153 clippy::missing_errors_doc,
154 clippy::must_use_candidate,
155)]
156// Restrictions
157#![deny(clippy::question_mark_used)]
158// Rustc lints.
159#![deny(missing_docs, unused_imports)]
160
161////////////////////////////////////////////////////////////////////////////////
162
163#[cfg(feature = "alloc")]
164extern crate alloc;
165
166/// A facade around all the types we need from the `std`, `core`, and `alloc`
167/// crates. This avoids elaborate import wrangling having to happen in every
168/// module.
169mod lib {
170 mod core {
171 #[cfg(not(feature = "std"))]
172 pub use core::*;
173 #[cfg(feature = "std")]
174 pub use std::*;
175 }
176
177 pub use self::core::{f32, f64};
178 pub use self::core::{i16, i32, i64, i8, isize};
179 pub use self::core::{iter, num, ptr, str};
180 pub use self::core::{u16, u32, u64, u8, usize};
181
182 #[cfg(any(feature = "std", feature = "alloc"))]
183 pub use self::core::{cmp, mem, slice};
184
185 pub use self::core::cell::{Cell, RefCell};
186 pub use self::core::clone;
187 pub use self::core::cmp::Reverse;
188 pub use self::core::convert;
189 pub use self::core::default;
190 pub use self::core::fmt::{self, Debug, Display, Write as FmtWrite};
191 pub use self::core::marker::{self, PhantomData};
192 pub use self::core::num::Wrapping;
193 pub use self::core::ops::{Bound, Range, RangeFrom, RangeInclusive, RangeTo};
194 pub use self::core::option;
195 pub use self::core::result;
196 pub use self::core::time::Duration;
197
198 #[cfg(all(feature = "alloc", not(feature = "std")))]
199 pub use alloc::borrow::{Cow, ToOwned};
200 #[cfg(feature = "std")]
201 pub use std::borrow::{Cow, ToOwned};
202
203 #[cfg(all(feature = "alloc", not(feature = "std")))]
204 pub use alloc::string::{String, ToString};
205 #[cfg(feature = "std")]
206 pub use std::string::{String, ToString};
207
208 #[cfg(all(feature = "alloc", not(feature = "std")))]
209 pub use alloc::vec::Vec;
210 #[cfg(feature = "std")]
211 pub use std::vec::Vec;
212
213 #[cfg(all(feature = "alloc", not(feature = "std")))]
214 pub use alloc::boxed::Box;
215 #[cfg(feature = "std")]
216 pub use std::boxed::Box;
217
218 #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
219 pub use alloc::rc::{Rc, Weak as RcWeak};
220 #[cfg(all(feature = "rc", feature = "std"))]
221 pub use std::rc::{Rc, Weak as RcWeak};
222
223 #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
224 pub use alloc::sync::{Arc, Weak as ArcWeak};
225 #[cfg(all(feature = "rc", feature = "std"))]
226 pub use std::sync::{Arc, Weak as ArcWeak};
227
228 #[cfg(all(feature = "alloc", not(feature = "std")))]
229 pub use alloc::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque};
230 #[cfg(feature = "std")]
231 pub use std::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque};
232
233 #[cfg(all(not(no_core_cstr), not(feature = "std")))]
234 pub use self::core::ffi::CStr;
235 #[cfg(feature = "std")]
236 pub use std::ffi::CStr;
237
238 #[cfg(all(not(no_core_cstr), feature = "alloc", not(feature = "std")))]
239 pub use alloc::ffi::CString;
240 #[cfg(feature = "std")]
241 pub use std::ffi::CString;
242
243 #[cfg(all(not(no_core_net), not(feature = "std")))]
244 pub use self::core::net;
245 #[cfg(feature = "std")]
246 pub use std::net;
247
248 #[cfg(feature = "std")]
249 pub use std::error;
250
251 #[cfg(feature = "std")]
252 pub use std::collections::{HashMap, HashSet};
253 #[cfg(feature = "std")]
254 pub use std::ffi::{OsStr, OsString};
255 #[cfg(feature = "std")]
256 pub use std::hash::{BuildHasher, Hash};
257 #[cfg(feature = "std")]
258 pub use std::io::Write;
259 #[cfg(feature = "std")]
260 pub use std::path::{Path, PathBuf};
261 #[cfg(feature = "std")]
262 pub use std::sync::{Mutex, RwLock};
263 #[cfg(feature = "std")]
264 pub use std::time::{SystemTime, UNIX_EPOCH};
265
266 #[cfg(all(feature = "std", no_target_has_atomic, not(no_std_atomic)))]
267 pub use std::sync::atomic::{
268 AtomicBool, AtomicI16, AtomicI32, AtomicI8, AtomicIsize, AtomicU16, AtomicU32, AtomicU8,
269 AtomicUsize, Ordering,
270 };
271 #[cfg(all(feature = "std", no_target_has_atomic, not(no_std_atomic64)))]
272 pub use std::sync::atomic::{AtomicI64, AtomicU64};
273
274 #[cfg(all(feature = "std", not(no_target_has_atomic)))]
275 pub use std::sync::atomic::Ordering;
276 #[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "8"))]
277 pub use std::sync::atomic::{AtomicBool, AtomicI8, AtomicU8};
278 #[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "16"))]
279 pub use std::sync::atomic::{AtomicI16, AtomicU16};
280 #[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "32"))]
281 pub use std::sync::atomic::{AtomicI32, AtomicU32};
282 #[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "64"))]
283 pub use std::sync::atomic::{AtomicI64, AtomicU64};
284 #[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "ptr"))]
285 pub use std::sync::atomic::{AtomicIsize, AtomicUsize};
286
287 #[cfg(not(no_core_num_saturating))]
288 pub use self::core::num::Saturating;
289}
290
291// None of this crate's error handling needs the `From::from` error conversion
292// performed implicitly by the `?` operator or the standard library's `try!`
293// macro. This simplified macro gives a 5.5% improvement in compile time
294// compared to standard `try!`, and 9% improvement compared to `?`.
295macro_rules! tri {
296 ($expr:expr) => {
297 match $expr {
298 Ok(val) => val,
299 Err(err) => return Err(err),
300 }
301 };
302}
303
304////////////////////////////////////////////////////////////////////////////////
305
306#[macro_use]
307mod macros;
308
309#[macro_use]
310mod integer128;
311
312pub mod de;
313pub mod ser;
314
315mod format;
316
317#[doc(inline)]
318pub use crate::de::{Deserialize, Deserializer};
319#[doc(inline)]
320pub use crate::ser::{Serialize, Serializer};
321
322// Used by generated code and doc tests. Not public API.
323#[doc(hidden)]
324#[path = "private/mod.rs"]
325pub mod __private;
326
327#[path = "de/seed.rs"]
328mod seed;
329
330#[cfg(all(not(feature = "std"), no_core_error))]
331mod std_error;
332
333// Re-export #[derive(Serialize, Deserialize)].
334//
335// The reason re-exporting is not enabled by default is that disabling it would
336// be annoying for crates that provide handwritten impls or data formats. They
337// would need to disable default features and then explicitly re-enable std.
338#[cfg(feature = "serde_derive")]
339extern crate serde_derive;
340
341/// Derive macro available if serde is built with `features = ["derive"]`.
342#[cfg(feature = "serde_derive")]
343#[cfg_attr(docsrs, doc(cfg(feature = "derive")))]
344pub use serde_derive::{Deserialize, Serialize};
345
346#[cfg(all(not(no_serde_derive), any(feature = "std", feature = "alloc")))]
347mod actually_private {
348 pub struct T;
349}
350