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/enarx/ciborium 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]: https://doc.rust-lang.org/cargo/reference/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.136")] 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 // Ignored clippy and clippy_pedantic lints 98 #![cfg_attr( 99 feature = "cargo-clippy", 100 allow( 101 // clippy bug: https://github.com/rust-lang/rust-clippy/issues/5704 102 unnested_or_patterns, 103 // clippy bug: https://github.com/rust-lang/rust-clippy/issues/7768 104 semicolon_if_nothing_returned, 105 // not available in our oldest supported compiler 106 checked_conversions, 107 empty_enum, 108 redundant_field_names, 109 redundant_static_lifetimes, 110 // integer and float ser/de requires these sorts of casts 111 cast_possible_truncation, 112 cast_possible_wrap, 113 cast_sign_loss, 114 // things are often more readable this way 115 cast_lossless, 116 module_name_repetitions, 117 option_if_let_else, 118 single_match_else, 119 type_complexity, 120 use_self, 121 zero_prefixed_literal, 122 // correctly used 123 enum_glob_use, 124 let_underscore_drop, 125 map_err_ignore, 126 result_unit_err, 127 wildcard_imports, 128 // not practical 129 needless_pass_by_value, 130 similar_names, 131 too_many_lines, 132 // preference 133 doc_markdown, 134 unseparated_literal_suffix, 135 // false positive 136 needless_doctest_main, 137 // noisy 138 missing_errors_doc, 139 must_use_candidate, 140 ) 141 )] 142 // Rustc lints. 143 #![deny(missing_docs, unused_imports)] 144 145 //////////////////////////////////////////////////////////////////////////////// 146 147 #[cfg(feature = "alloc")] 148 extern crate alloc; 149 150 /// A facade around all the types we need from the `std`, `core`, and `alloc` 151 /// crates. This avoids elaborate import wrangling having to happen in every 152 /// module. 153 mod lib { 154 mod core { 155 #[cfg(not(feature = "std"))] 156 pub use core::*; 157 #[cfg(feature = "std")] 158 pub use std::*; 159 } 160 161 pub use self::core::{cmp, iter, mem, num, ptr, slice, str}; 162 pub use self::core::{f32, f64}; 163 pub use self::core::{i16, i32, i64, i8, isize}; 164 pub use self::core::{u16, u32, u64, u8, usize}; 165 166 pub use self::core::cell::{Cell, RefCell}; 167 pub use self::core::clone::{self, Clone}; 168 pub use self::core::convert::{self, From, Into}; 169 pub use self::core::default::{self, Default}; 170 pub use self::core::fmt::{self, Debug, Display}; 171 pub use self::core::marker::{self, PhantomData}; 172 pub use self::core::num::Wrapping; 173 pub use self::core::ops::Range; 174 pub use self::core::option::{self, Option}; 175 pub use self::core::result::{self, Result}; 176 177 #[cfg(all(feature = "alloc", not(feature = "std")))] 178 pub use alloc::borrow::{Cow, ToOwned}; 179 #[cfg(feature = "std")] 180 pub use std::borrow::{Cow, ToOwned}; 181 182 #[cfg(all(feature = "alloc", not(feature = "std")))] 183 pub use alloc::string::{String, ToString}; 184 #[cfg(feature = "std")] 185 pub use std::string::{String, ToString}; 186 187 #[cfg(all(feature = "alloc", not(feature = "std")))] 188 pub use alloc::vec::Vec; 189 #[cfg(feature = "std")] 190 pub use std::vec::Vec; 191 192 #[cfg(all(feature = "alloc", not(feature = "std")))] 193 pub use alloc::boxed::Box; 194 #[cfg(feature = "std")] 195 pub use std::boxed::Box; 196 197 #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))] 198 pub use alloc::rc::{Rc, Weak as RcWeak}; 199 #[cfg(all(feature = "rc", feature = "std"))] 200 pub use std::rc::{Rc, Weak as RcWeak}; 201 202 #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))] 203 pub use alloc::sync::{Arc, Weak as ArcWeak}; 204 #[cfg(all(feature = "rc", feature = "std"))] 205 pub use std::sync::{Arc, Weak as ArcWeak}; 206 207 #[cfg(all(feature = "alloc", not(feature = "std")))] 208 pub use alloc::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque}; 209 #[cfg(feature = "std")] 210 pub use std::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque}; 211 212 #[cfg(feature = "std")] 213 pub use std::{error, net}; 214 215 #[cfg(feature = "std")] 216 pub use std::collections::{HashMap, HashSet}; 217 #[cfg(feature = "std")] 218 pub use std::ffi::{CStr, CString, OsStr, OsString}; 219 #[cfg(feature = "std")] 220 pub use std::hash::{BuildHasher, Hash}; 221 #[cfg(feature = "std")] 222 pub use std::io::Write; 223 #[cfg(feature = "std")] 224 pub use std::path::{Path, PathBuf}; 225 #[cfg(feature = "std")] 226 pub use std::sync::{Mutex, RwLock}; 227 #[cfg(feature = "std")] 228 pub use std::time::{SystemTime, UNIX_EPOCH}; 229 230 #[cfg(all(feature = "std", not(no_collections_bound), no_ops_bound))] 231 pub use std::collections::Bound; 232 233 #[cfg(not(no_core_reverse))] 234 pub use self::core::cmp::Reverse; 235 236 #[cfg(not(no_ops_bound))] 237 pub use self::core::ops::Bound; 238 239 #[cfg(not(no_range_inclusive))] 240 pub use self::core::ops::RangeInclusive; 241 242 #[cfg(all(feature = "std", not(no_std_atomic)))] 243 pub use std::sync::atomic::{ 244 AtomicBool, AtomicI16, AtomicI32, AtomicI8, AtomicIsize, AtomicU16, AtomicU32, AtomicU8, 245 AtomicUsize, Ordering, 246 }; 247 #[cfg(all(feature = "std", not(no_std_atomic64)))] 248 pub use std::sync::atomic::{AtomicI64, AtomicU64}; 249 250 #[cfg(any(feature = "std", not(no_core_duration)))] 251 pub use self::core::time::Duration; 252 } 253 254 //////////////////////////////////////////////////////////////////////////////// 255 256 #[macro_use] 257 mod macros; 258 259 #[macro_use] 260 mod integer128; 261 262 pub mod de; 263 pub mod ser; 264 265 #[doc(inline)] 266 pub use de::{Deserialize, Deserializer}; 267 #[doc(inline)] 268 pub use ser::{Serialize, Serializer}; 269 270 // Used by generated code and doc tests. Not public API. 271 #[doc(hidden)] 272 #[path = "private/mod.rs"] 273 pub mod __private; 274 275 #[allow(unused_imports)] 276 use self::__private as export; 277 #[allow(unused_imports)] 278 use self::__private as private; 279 280 #[path = "de/seed.rs"] 281 mod seed; 282 283 #[cfg(not(feature = "std"))] 284 mod std_error; 285 286 // Re-export #[derive(Serialize, Deserialize)]. 287 // 288 // The reason re-exporting is not enabled by default is that disabling it would 289 // be annoying for crates that provide handwritten impls or data formats. They 290 // would need to disable default features and then explicitly re-enable std. 291 #[cfg(feature = "serde_derive")] 292 #[allow(unused_imports)] 293 #[macro_use] 294 extern crate serde_derive; 295 #[cfg(feature = "serde_derive")] 296 #[doc(hidden)] 297 pub use serde_derive::*; 298 299 #[cfg(all(not(no_serde_derive), any(feature = "std", feature = "alloc")))] 300 mod actually_private { 301 pub struct T; 302 } 303