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