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