3 //! Serde is a framework for ***ser***ializing and ***de***serializing Rust data
4 //! structures efficiently and generically.
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.
12 //! See the Serde website [https://serde.rs/] for additional documentation and
15 //! [https://serde.rs/]: https://serde.rs/
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.
32 //! The following is a partial list of data formats that have been implemented
33 //! for Serde by the community.
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
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
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 //! - [S-expressions], the textual representation of code and data used by the
57 //! Lisp language family.
58 //! - [D-Bus]'s binary wire format.
59 //! - [FlexBuffers], the schemaless cousin of Google's FlatBuffers zero-copy serialization format.
61 //! [JSON]: https://github.com/serde-rs/json
62 //! [Bincode]: https://github.com/TyOverby/bincode
63 //! [CBOR]: https://github.com/pyfisch/cbor
64 //! [YAML]: https://github.com/dtolnay/serde-yaml
65 //! [MessagePack]: https://github.com/3Hren/msgpack-rust
66 //! [TOML]: https://github.com/alexcrichton/toml-rs
67 //! [Pickle]: https://github.com/birkenfeld/serde-pickle
68 //! [RON]: https://github.com/ron-rs/ron
69 //! [BSON]: https://github.com/zonyitoo/bson-rs
70 //! [Avro]: https://github.com/flavray/avro-rs
71 //! [JSON5]: https://github.com/callum-oakley/json5-rs
72 //! [Postcard]: https://github.com/jamesmunns/postcard
73 //! [URL]: https://github.com/nox/serde_urlencoded
74 //! [Envy]: https://github.com/softprops/envy
75 //! [Envy Store]: https://github.com/softprops/envy-store
76 //! [Cargo]: http://doc.crates.io/manifest.html
77 //! [AWS Parameter Store]: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html
78 //! [S-expressions]: https://github.com/rotty/lexpr-rs
79 //! [D-Bus]: https://docs.rs/zvariant
80 //! [FlexBuffers]: https://github.com/google/flatbuffers/tree/master/rust/flexbuffers
82 ////////////////////////////////////////////////////////////////////////////////
84 // Serde types in rustdoc of other crates get linked to here.
85 #![doc(html_root_url = "https://docs.rs/serde/1.0.114")]
86 // Support using Serde without the standard library!
87 #![cfg_attr(not(feature = "std"), no_std)]
88 // Unstable functionality only if the user asks for it. For tracking and
89 // discussion of these features please refer to this issue:
91 // https://github.com/serde-rs/serde/issues/812
92 #![cfg_attr(feature = "unstable", feature(never_type))]
93 #![allow(unknown_lints, bare_trait_objects, deprecated)]
94 #![cfg_attr(feature = "cargo-clippy", allow(renamed_and_removed_lints))]
95 #![cfg_attr(feature = "cargo-clippy", deny(clippy, clippy_pedantic))]
96 // Ignored clippy and clippy_pedantic lints
98 feature
= "cargo-clippy",
100 // clippy bug: https://github.com/rust-lang/rust-clippy/issues/5704
101 unnested_or_patterns
,
102 // not available in our oldest supported compiler
105 redundant_field_names
,
106 redundant_static_lifetimes
,
107 // integer and float ser/de requires these sorts of casts
108 cast_possible_truncation
,
111 // things are often more readable this way
113 module_name_repetitions
,
117 zero_prefixed_literal
,
122 needless_pass_by_value
,
127 unseparated_literal_suffix
,
129 needless_doctest_main
,
136 #![forbid(unsafe_code)]
137 #![deny(missing_docs, unused_imports)]
139 ////////////////////////////////////////////////////////////////////////////////
141 #[cfg(feature = "alloc")]
144 /// A facade around all the types we need from the `std`, `core`, and `alloc`
145 /// crates. This avoids elaborate import wrangling having to happen in every
149 #[cfg(not(feature = "std"))]
151 #[cfg(feature = "std")]
155 pub use self::core
::{cmp, iter, mem, num, slice, str}
;
156 pub use self::core
::{f32, f64}
;
157 pub use self::core
::{i16, i32, i64, i8, isize}
;
158 pub use self::core
::{u16, u32, u64, u8, usize}
;
160 pub use self::core
::cell
::{Cell, RefCell}
;
161 pub use self::core
::clone
::{self, Clone}
;
162 pub use self::core
::convert
::{self, From, Into}
;
163 pub use self::core
::default::{self, Default}
;
164 pub use self::core
::fmt
::{self, Debug, Display}
;
165 pub use self::core
::marker
::{self, PhantomData}
;
166 pub use self::core
::ops
::Range
;
167 pub use self::core
::option
::{self, Option}
;
168 pub use self::core
::result
::{self, Result}
;
170 #[cfg(all(feature = "alloc", not(feature = "std")))]
171 pub use alloc
::borrow
::{Cow, ToOwned}
;
172 #[cfg(feature = "std")]
173 pub use std
::borrow
::{Cow, ToOwned}
;
175 #[cfg(all(feature = "alloc", not(feature = "std")))]
176 pub use alloc
::string
::{String, ToString}
;
177 #[cfg(feature = "std")]
178 pub use std
::string
::{String, ToString}
;
180 #[cfg(all(feature = "alloc", not(feature = "std")))]
181 pub use alloc
::vec
::Vec
;
182 #[cfg(feature = "std")]
183 pub use std
::vec
::Vec
;
185 #[cfg(all(feature = "alloc", not(feature = "std")))]
186 pub use alloc
::boxed
::Box
;
187 #[cfg(feature = "std")]
188 pub use std
::boxed
::Box
;
190 #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
191 pub use alloc
::rc
::{Rc, Weak as RcWeak}
;
192 #[cfg(all(feature = "rc", feature = "std"))]
193 pub use std
::rc
::{Rc, Weak as RcWeak}
;
195 #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
196 pub use alloc
::sync
::{Arc, Weak as ArcWeak}
;
197 #[cfg(all(feature = "rc", feature = "std"))]
198 pub use std
::sync
::{Arc, Weak as ArcWeak}
;
200 #[cfg(all(feature = "alloc", not(feature = "std")))]
201 pub use alloc
::collections
::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque}
;
202 #[cfg(feature = "std")]
203 pub use std
::collections
::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque}
;
205 #[cfg(feature = "std")]
206 pub use std
::{error, net}
;
208 #[cfg(feature = "std")]
209 pub use std
::collections
::{HashMap, HashSet}
;
210 #[cfg(feature = "std")]
211 pub use std
::ffi
::{CStr, CString, OsStr, OsString}
;
212 #[cfg(feature = "std")]
213 pub use std
::hash
::{BuildHasher, Hash}
;
214 #[cfg(feature = "std")]
215 pub use std
::io
::Write
;
216 #[cfg(feature = "std")]
217 pub use std
::num
::Wrapping
;
218 #[cfg(feature = "std")]
219 pub use std
::path
::{Path, PathBuf}
;
220 #[cfg(feature = "std")]
221 pub use std
::sync
::{Mutex, RwLock}
;
222 #[cfg(feature = "std")]
223 pub use std
::time
::{SystemTime, UNIX_EPOCH}
;
225 #[cfg(all(feature = "std", collections_bound))]
226 pub use std
::collections
::Bound
;
229 pub use self::core
::cmp
::Reverse
;
232 pub use self::core
::ops
::Bound
;
234 #[cfg(range_inclusive)]
235 pub use self::core
::ops
::RangeInclusive
;
237 #[cfg(all(feature = "std", std_atomic))]
238 pub use std
::sync
::atomic
::{
239 AtomicBool
, AtomicI16
, AtomicI32
, AtomicI8
, AtomicIsize
, AtomicU16
, AtomicU32
, AtomicU8
,
240 AtomicUsize
, Ordering
,
242 #[cfg(all(feature = "std", std_atomic64))]
243 pub use std
::sync
::atomic
::{AtomicI64, AtomicU64}
;
245 #[cfg(any(core_duration, feature = "std"))]
246 pub use self::core
::time
::Duration
;
249 ////////////////////////////////////////////////////////////////////////////////
261 pub use de
::{Deserialize, Deserializer}
;
263 pub use ser
::{Serialize, Serializer}
;
265 // Generated code uses these to support no_std. Not public API.
269 // Helpers used by generated code and doc tests. Not public API.
273 #[cfg(not(feature = "std"))]
276 // Re-export #[derive(Serialize, Deserialize)].
278 // The reason re-exporting is not enabled by default is that disabling it would
279 // be annoying for crates that provide handwritten impls or data formats. They
280 // would need to disable default features and then explicitly re-enable std.
281 #[cfg(feature = "serde_derive")]
282 #[allow(unused_imports)]
284 extern crate serde_derive
;
285 #[cfg(feature = "serde_derive")]
287 pub use serde_derive
::*;