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