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 //! - [Bincode], a compact binary format 35 //! used for IPC within the Servo rendering engine. 36 //! - [CBOR], a Concise Binary Object Representation designed for small message 37 //! size without the need for version negotiation. 38 //! - [YAML], a self-proclaimed human-friendly configuration language that ain't 39 //! markup language. 40 //! - [MessagePack], an efficient binary format that resembles a compact JSON. 41 //! - [TOML], a minimal configuration format used by [Cargo]. 42 //! - [Pickle], a format common in the Python world. 43 //! - [RON], a Rusty Object Notation. 44 //! - [BSON], the data storage and network transfer format used by MongoDB. 45 //! - [Avro], a binary format used within Apache Hadoop, with support for schema 46 //! definition. 47 //! - [JSON5], a superset of JSON including some productions from ES5. 48 //! - [Postcard], a no\_std and embedded-systems friendly compact binary format. 49 //! - [URL] query strings, in the x-www-form-urlencoded format. 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 serialization format. 58 //! - [DynamoDB Items], the format used by [rusoto_dynamodb] to transfer data to 59 //! and from DynamoDB. 60 //! 61 //! [JSON]: https://github.com/serde-rs/json 62 //! [Bincode]: https://github.com/servo/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://docs.rs/serde_qs 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 81 //! [DynamoDB Items]: https://docs.rs/serde_dynamo 82 //! [rusoto_dynamodb]: https://docs.rs/rusoto_dynamodb 83 84 //////////////////////////////////////////////////////////////////////////////// 85 86 // Serde types in rustdoc of other crates get linked to here. 87 #![doc(html_root_url = "https://docs.rs/serde/1.0.126")] 88 // Support using Serde without the standard library! 89 #![cfg_attr(not(feature = "std"), no_std)] 90 // Unstable functionality only if the user asks for it. For tracking and 91 // discussion of these features please refer to this issue: 92 // 93 // https://github.com/serde-rs/serde/issues/812 94 #![cfg_attr(feature = "unstable", feature(never_type))] 95 #![allow(unknown_lints, bare_trait_objects, deprecated)] 96 #![cfg_attr(feature = "cargo-clippy", allow(renamed_and_removed_lints))] 97 #![cfg_attr(feature = "cargo-clippy", deny(clippy, clippy_pedantic))] 98 // Ignored clippy and clippy_pedantic lints 99 #![cfg_attr( 100 feature = "cargo-clippy", 101 allow( 102 // clippy bug: https://github.com/rust-lang/rust-clippy/issues/5704 103 unnested_or_patterns, 104 // not available in our oldest supported compiler 105 checked_conversions, 106 empty_enum, 107 redundant_field_names, 108 redundant_static_lifetimes, 109 // integer and float ser/de requires these sorts of casts 110 cast_possible_truncation, 111 cast_possible_wrap, 112 cast_sign_loss, 113 // things are often more readable this way 114 cast_lossless, 115 module_name_repetitions, 116 option_if_let_else, 117 single_match_else, 118 type_complexity, 119 use_self, 120 zero_prefixed_literal, 121 // correctly used 122 enum_glob_use, 123 let_underscore_drop, 124 map_err_ignore, 125 result_unit_err, 126 wildcard_imports, 127 // not practical 128 needless_pass_by_value, 129 similar_names, 130 too_many_lines, 131 // preference 132 doc_markdown, 133 unseparated_literal_suffix, 134 // false positive 135 needless_doctest_main, 136 // noisy 137 missing_errors_doc, 138 must_use_candidate, 139 ) 140 )] 141 // Rustc lints. 142 #![deny(missing_docs, unused_imports)] 143 144 //////////////////////////////////////////////////////////////////////////////// 145 146 #[cfg(feature = "alloc")] 147 extern crate alloc; 148 149 /// A facade around all the types we need from the `std`, `core`, and `alloc` 150 /// crates. This avoids elaborate import wrangling having to happen in every 151 /// module. 152 mod lib { 153 mod core { 154 #[cfg(not(feature = "std"))] 155 pub use core::*; 156 #[cfg(feature = "std")] 157 pub use std::*; 158 } 159 160 pub use self::core::{cmp, iter, mem, num, slice, str}; 161 pub use self::core::{f32, f64}; 162 pub use self::core::{i16, i32, i64, i8, isize}; 163 pub use self::core::{u16, u32, u64, u8, usize}; 164 165 pub use self::core::cell::{Cell, RefCell}; 166 pub use self::core::clone::{self, Clone}; 167 pub use self::core::convert::{self, From, Into}; 168 pub use self::core::default::{self, Default}; 169 pub use self::core::fmt::{self, Debug, Display}; 170 pub use self::core::marker::{self, PhantomData}; 171 pub use self::core::num::Wrapping; 172 pub use self::core::ops::Range; 173 pub use self::core::option::{self, Option}; 174 pub use self::core::result::{self, Result}; 175 176 #[cfg(all(feature = "alloc", not(feature = "std")))] 177 pub use alloc::borrow::{Cow, ToOwned}; 178 #[cfg(feature = "std")] 179 pub use std::borrow::{Cow, ToOwned}; 180 181 #[cfg(all(feature = "alloc", not(feature = "std")))] 182 pub use alloc::string::{String, ToString}; 183 #[cfg(feature = "std")] 184 pub use std::string::{String, ToString}; 185 186 #[cfg(all(feature = "alloc", not(feature = "std")))] 187 pub use alloc::vec::Vec; 188 #[cfg(feature = "std")] 189 pub use std::vec::Vec; 190 191 #[cfg(all(feature = "alloc", not(feature = "std")))] 192 pub use alloc::boxed::Box; 193 #[cfg(feature = "std")] 194 pub use std::boxed::Box; 195 196 #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))] 197 pub use alloc::rc::{Rc, Weak as RcWeak}; 198 #[cfg(all(feature = "rc", feature = "std"))] 199 pub use std::rc::{Rc, Weak as RcWeak}; 200 201 #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))] 202 pub use alloc::sync::{Arc, Weak as ArcWeak}; 203 #[cfg(all(feature = "rc", feature = "std"))] 204 pub use std::sync::{Arc, Weak as ArcWeak}; 205 206 #[cfg(all(feature = "alloc", not(feature = "std")))] 207 pub use alloc::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque}; 208 #[cfg(feature = "std")] 209 pub use std::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque}; 210 211 #[cfg(feature = "std")] 212 pub use std::{error, net}; 213 214 #[cfg(feature = "std")] 215 pub use std::collections::{HashMap, HashSet}; 216 #[cfg(feature = "std")] 217 pub use std::ffi::{CStr, CString, OsStr, OsString}; 218 #[cfg(feature = "std")] 219 pub use std::hash::{BuildHasher, Hash}; 220 #[cfg(feature = "std")] 221 pub use std::io::Write; 222 #[cfg(feature = "std")] 223 pub use std::path::{Path, PathBuf}; 224 #[cfg(feature = "std")] 225 pub use std::sync::{Mutex, RwLock}; 226 #[cfg(feature = "std")] 227 pub use std::time::{SystemTime, UNIX_EPOCH}; 228 229 #[cfg(all(feature = "std", collections_bound))] 230 pub use std::collections::Bound; 231 232 #[cfg(core_reverse)] 233 pub use self::core::cmp::Reverse; 234 235 #[cfg(ops_bound)] 236 pub use self::core::ops::Bound; 237 238 #[cfg(range_inclusive)] 239 pub use self::core::ops::RangeInclusive; 240 241 #[cfg(all(feature = "std", std_atomic))] 242 pub use std::sync::atomic::{ 243 AtomicBool, AtomicI16, AtomicI32, AtomicI8, AtomicIsize, AtomicU16, AtomicU32, AtomicU8, 244 AtomicUsize, Ordering, 245 }; 246 #[cfg(all(feature = "std", std_atomic64))] 247 pub use std::sync::atomic::{AtomicI64, AtomicU64}; 248 249 #[cfg(any(core_duration, feature = "std"))] 250 pub use self::core::time::Duration; 251 } 252 253 //////////////////////////////////////////////////////////////////////////////// 254 255 #[macro_use] 256 mod macros; 257 258 #[macro_use] 259 mod integer128; 260 261 pub mod de; 262 pub mod ser; 263 264 #[doc(inline)] 265 pub use de::{Deserialize, Deserializer}; 266 #[doc(inline)] 267 pub use ser::{Serialize, Serializer}; 268 269 // Used by generated code and doc tests. Not public API. 270 #[doc(hidden)] 271 #[path = "private/mod.rs"] 272 pub mod __private; 273 274 #[allow(unused_imports)] 275 use self::__private as export; 276 #[allow(unused_imports)] 277 use self::__private as private; 278 279 #[path = "de/seed.rs"] 280 mod seed; 281 282 #[cfg(not(feature = "std"))] 283 mod std_error; 284 285 // Re-export #[derive(Serialize, Deserialize)]. 286 // 287 // The reason re-exporting is not enabled by default is that disabling it would 288 // be annoying for crates that provide handwritten impls or data formats. They 289 // would need to disable default features and then explicitly re-enable std. 290 #[cfg(feature = "serde_derive")] 291 #[allow(unused_imports)] 292 #[macro_use] 293 extern crate serde_derive; 294 #[cfg(feature = "serde_derive")] 295 #[doc(hidden)] 296 pub use serde_derive::*; 297