serde/lib.rs
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//! [https://serde.rs/]: https://serde.rs/
16//!
17//! ## Design
18//!
19//! Where many other languages rely on runtime reflection for serializing data,
20//! Serde is instead built on Rust's powerful trait system. A data structure
21//! that knows how to serialize and deserialize itself is one that implements
22//! Serde's `Serialize` and `Deserialize` traits (or uses Serde's derive
23//! attribute to automatically generate implementations at compile time). This
24//! avoids any overhead of reflection or runtime type information. In fact in
25//! many situations the interaction between data structure and data format can
26//! be completely optimized away by the Rust compiler, leaving Serde
27//! serialization to perform the same speed as a handwritten serializer for the
28//! specific selection of data structure and data format.
29//!
30//! ## Data formats
31//!
32//! The following is a partial list of data formats that have been implemented
33//! for Serde by the community.
34//!
35//! - [JSON], the ubiquitous JavaScript Object Notation used by many HTTP APIs.
36//! - [Bincode], a compact binary format
37//! used for IPC within the Servo rendering engine.
38//! - [CBOR], a Concise Binary Object Representation designed for small message
39//! size without the need for version negotiation.
40//! - [YAML], a popular human-friendly configuration language that ain't markup
41//! language.
42//! - [MessagePack], an efficient binary format that resembles a compact JSON.
43//! - [TOML], a minimal configuration format used by [Cargo].
44//! - [Pickle], a format common in the Python world.
45//! - [RON], a Rusty Object Notation.
46//! - [BSON], the data storage and network transfer format used by MongoDB.
47//! - [Avro], a binary format used within Apache Hadoop, with support for schema
48//! definition.
49//! - [JSON5], A superset of JSON including some productions from ES5.
50//! - [Postcard], a no\_std and embedded-systems friendly compact binary format.
51//! - [URL], the x-www-form-urlencoded format.
52//! - [Envy], a way to deserialize environment variables into Rust structs.
53//! *(deserialization only)*
54//! - [Envy Store], a way to deserialize [AWS Parameter Store] parameters into
55//! Rust structs. *(deserialization only)*
56//!
57//! [JSON]: https://github.com/serde-rs/json
58//! [Bincode]: https://github.com/TyOverby/bincode
59//! [CBOR]: https://github.com/pyfisch/cbor
60//! [YAML]: https://github.com/dtolnay/serde-yaml
61//! [MessagePack]: https://github.com/3Hren/msgpack-rust
62//! [TOML]: https://github.com/alexcrichton/toml-rs
63//! [Pickle]: https://github.com/birkenfeld/serde-pickle
64//! [RON]: https://github.com/ron-rs/ron
65//! [BSON]: https://github.com/zonyitoo/bson-rs
66//! [Avro]: https://github.com/flavray/avro-rs
67//! [JSON5]: https://github.com/callum-oakley/json5-rs
68//! [Postcard]: https://github.com/jamesmunns/postcard
69//! [URL]: https://github.com/nox/serde_urlencoded
70//! [Envy]: https://github.com/softprops/envy
71//! [Envy Store]: https://github.com/softprops/envy-store
72//! [Cargo]: http://doc.crates.io/manifest.html
73//! [AWS Parameter Store]: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html
74
75////////////////////////////////////////////////////////////////////////////////
76
77// Serde types in rustdoc of other crates get linked to here.
78#![doc(html_root_url = "https://docs.rs/serde/1.0.103")]
79// Support using Serde without the standard library!
80#![cfg_attr(not(feature = "std"), no_std)]
81// Unstable functionality only if the user asks for it. For tracking and
82// discussion of these features please refer to this issue:
83//
84// https://github.com/serde-rs/serde/issues/812
85#![cfg_attr(feature = "unstable", feature(specialization))]
86#![allow(unknown_lints, bare_trait_objects, deprecated)]
87#![cfg_attr(feature = "cargo-clippy", allow(renamed_and_removed_lints))]
88#![cfg_attr(feature = "cargo-clippy", deny(clippy, clippy_pedantic))]
89// Ignored clippy and clippy_pedantic lints
90#![cfg_attr(
91 feature = "cargo-clippy",
92 allow(
93 // not available in our oldest supported compiler
94 checked_conversions,
95 empty_enum,
96 redundant_field_names,
97 redundant_static_lifetimes,
98 // integer and float ser/de requires these sorts of casts
99 cast_possible_truncation,
100 cast_possible_wrap,
101 cast_sign_loss,
102 // things are often more readable this way
103 cast_lossless,
104 module_name_repetitions,
105 single_match_else,
106 type_complexity,
107 use_self,
108 zero_prefixed_literal,
109 // not practical
110 needless_pass_by_value,
111 similar_names,
112 too_many_lines,
113 // preference
114 doc_markdown,
115 // false positive
116 needless_doctest_main,
117 // noisy
118 must_use_candidate,
119 )
120)]
121// Rustc lints.
122#![deny(missing_docs, unused_imports)]
123
124////////////////////////////////////////////////////////////////////////////////
125
126#[cfg(feature = "alloc")]
127extern crate alloc;
128
129/// A facade around all the types we need from the `std`, `core`, and `alloc`
130/// crates. This avoids elaborate import wrangling having to happen in every
131/// module.
132mod lib {
133 mod core {
134 #[cfg(not(feature = "std"))]
135 pub use core::*;
136 #[cfg(feature = "std")]
137 pub use std::*;
138 }
139
140 pub use self::core::{cmp, iter, mem, num, slice, str};
141 pub use self::core::{f32, f64};
142 pub use self::core::{i16, i32, i64, i8, isize};
143 pub use self::core::{u16, u32, u64, u8, usize};
144
145 pub use self::core::cell::{Cell, RefCell};
146 pub use self::core::clone::{self, Clone};
147 pub use self::core::convert::{self, From, Into};
148 pub use self::core::default::{self, Default};
149 pub use self::core::fmt::{self, Debug, Display};
150 pub use self::core::marker::{self, PhantomData};
151 pub use self::core::ops::Range;
152 pub use self::core::option::{self, Option};
153 pub use self::core::result::{self, Result};
154
155 #[cfg(all(feature = "alloc", not(feature = "std")))]
156 pub use alloc::borrow::{Cow, ToOwned};
157 #[cfg(feature = "std")]
158 pub use std::borrow::{Cow, ToOwned};
159
160 #[cfg(all(feature = "alloc", not(feature = "std")))]
161 pub use alloc::string::{String, ToString};
162 #[cfg(feature = "std")]
163 pub use std::string::{String, ToString};
164
165 #[cfg(all(feature = "alloc", not(feature = "std")))]
166 pub use alloc::vec::Vec;
167 #[cfg(feature = "std")]
168 pub use std::vec::Vec;
169
170 #[cfg(all(feature = "alloc", not(feature = "std")))]
171 pub use alloc::boxed::Box;
172 #[cfg(feature = "std")]
173 pub use std::boxed::Box;
174
175 #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
176 pub use alloc::rc::{Rc, Weak as RcWeak};
177 #[cfg(all(feature = "rc", feature = "std"))]
178 pub use std::rc::{Rc, Weak as RcWeak};
179
180 #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
181 pub use alloc::sync::{Arc, Weak as ArcWeak};
182 #[cfg(all(feature = "rc", feature = "std"))]
183 pub use std::sync::{Arc, Weak as ArcWeak};
184
185 #[cfg(all(feature = "alloc", not(feature = "std")))]
186 pub use alloc::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque};
187 #[cfg(feature = "std")]
188 pub use std::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque};
189
190 #[cfg(feature = "std")]
191 pub use std::{error, net};
192
193 #[cfg(feature = "std")]
194 pub use std::collections::{HashMap, HashSet};
195 #[cfg(feature = "std")]
196 pub use std::ffi::{CStr, CString, OsStr, OsString};
197 #[cfg(feature = "std")]
198 pub use std::hash::{BuildHasher, Hash};
199 #[cfg(feature = "std")]
200 pub use std::io::Write;
201 #[cfg(feature = "std")]
202 pub use std::num::Wrapping;
203 #[cfg(feature = "std")]
204 pub use std::path::{Path, PathBuf};
205 #[cfg(feature = "std")]
206 pub use std::sync::{Mutex, RwLock};
207 #[cfg(feature = "std")]
208 pub use std::time::{SystemTime, UNIX_EPOCH};
209
210 #[cfg(all(feature = "std", collections_bound))]
211 pub use std::collections::Bound;
212
213 #[cfg(core_reverse)]
214 pub use self::core::cmp::Reverse;
215
216 #[cfg(ops_bound)]
217 pub use self::core::ops::Bound;
218
219 #[cfg(range_inclusive)]
220 pub use self::core::ops::RangeInclusive;
221
222 #[cfg(all(feature = "std", std_atomic))]
223 pub use std::sync::atomic::{
224 AtomicBool, AtomicI16, AtomicI32, AtomicI8, AtomicIsize, AtomicU16, AtomicU32, AtomicU8,
225 AtomicUsize, Ordering,
226 };
227 #[cfg(all(feature = "std", std_atomic64))]
228 pub use std::sync::atomic::{AtomicI64, AtomicU64};
229
230 #[cfg(any(core_duration, feature = "std"))]
231 pub use self::core::time::Duration;
232}
233
234////////////////////////////////////////////////////////////////////////////////
235
236#[macro_use]
237mod macros;
238
239#[macro_use]
240mod integer128;
241
242pub mod de;
243pub mod ser;
244
245#[doc(inline)]
246pub use de::{Deserialize, Deserializer};
247#[doc(inline)]
248pub use ser::{Serialize, Serializer};
249
250// Generated code uses these to support no_std. Not public API.
251#[doc(hidden)]
252pub mod export;
253
254// Helpers used by generated code and doc tests. Not public API.
255#[doc(hidden)]
256pub mod private;
257
258#[cfg(not(feature = "std"))]
259mod std_error;
260
261// Re-export #[derive(Serialize, Deserialize)].
262//
263// The reason re-exporting is not enabled by default is that disabling it would
264// be annoying for crates that provide handwritten impls or data formats. They
265// would need to disable default features and then explicitly re-enable std.
266#[cfg(feature = "serde_derive")]
267#[allow(unused_imports)]
268#[macro_use]
269extern crate serde_derive;
270#[cfg(feature = "serde_derive")]
271#[doc(hidden)]
272pub use serde_derive::*;