| 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.200")] |
| 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_precision_loss, |
| 122 |
clippy::cast_sign_loss, |
| 123 |
// things are often more readable this way |
| 124 |
clippy::cast_lossless, |
| 125 |
clippy::module_name_repetitions, |
| 126 |
clippy::single_match_else, |
| 127 |
clippy::type_complexity, |
| 128 |
clippy::use_self, |
| 129 |
clippy::zero_prefixed_literal, |
| 130 |
// correctly used |
| 131 |
clippy::derive_partial_eq_without_eq, |
| 132 |
clippy::enum_glob_use, |
| 133 |
clippy::explicit_auto_deref, |
| 134 |
clippy::incompatible_msrv, |
| 135 |
clippy::let_underscore_untyped, |
| 136 |
clippy::map_err_ignore, |
| 137 |
clippy::new_without_default, |
| 138 |
clippy::result_unit_err, |
| 139 |
clippy::wildcard_imports, |
| 140 |
// not practical |
| 141 |
clippy::needless_pass_by_value, |
| 142 |
clippy::similar_names, |
| 143 |
clippy::too_many_lines, |
| 144 |
// preference |
| 145 |
clippy::doc_markdown, |
| 146 |
clippy::unseparated_literal_suffix, |
| 147 |
// false positive |
| 148 |
clippy::needless_doctest_main, |
| 149 |
// noisy |
| 150 |
clippy::missing_errors_doc, |
| 151 |
clippy::must_use_candidate, |
| 152 |
)] |
| 153 |
// Restrictions |
| 154 |
#![deny(clippy::question_mark_used)] |
| 155 |
// Rustc lints. |
| 156 |
#![deny(missing_docs, unused_imports)] |
| 157 |
|
| 158 |
//////////////////////////////////////////////////////////////////////////////// |
| 159 |
|
| 160 |
#[cfg(feature = "alloc")] |
| 161 |
extern crate alloc; |
| 162 |
|
| 163 |
/// A facade around all the types we need from the `std`, `core`, and `alloc` |
| 164 |
/// crates. This avoids elaborate import wrangling having to happen in every |
| 165 |
/// module. |
| 166 |
mod lib { |
| 167 |
mod core { |
| 168 |
#[cfg(not(feature = "std"))] |
| 169 |
pub use core::*; |
| 170 |
#[cfg(feature = "std")] |
| 171 |
pub use std::*; |
| 172 |
} |
| 173 |
|
| 174 |
pub use self::core::{f32, f64}; |
| 175 |
pub use self::core::{i16, i32, i64, i8, isize}; |
| 176 |
pub use self::core::{iter, num, ptr, str}; |
| 177 |
pub use self::core::{u16, u32, u64, u8, usize}; |
| 178 |
|
| 179 |
#[cfg(any(feature = "std", feature = "alloc"))] |
| 180 |
pub use self::core::{cmp, mem, slice}; |
| 181 |
|
| 182 |
pub use self::core::cell::{Cell, RefCell}; |
| 183 |
pub use self::core::clone; |
| 184 |
pub use self::core::cmp::Reverse; |
| 185 |
pub use self::core::convert; |
| 186 |
pub use self::core::default; |
| 187 |
pub use self::core::fmt::{self, Debug, Display, Write as FmtWrite}; |
| 188 |
pub use self::core::marker::{self, PhantomData}; |
| 189 |
pub use self::core::num::Wrapping; |
| 190 |
pub use self::core::ops::{Bound, Range, RangeFrom, RangeInclusive, RangeTo}; |
| 191 |
pub use self::core::option; |
| 192 |
pub use self::core::result; |
| 193 |
pub use self::core::time::Duration; |
| 194 |
|
| 195 |
#[cfg(all(feature = "alloc", not(feature = "std")))] |
| 196 |
pub use alloc::borrow::{Cow, ToOwned}; |
| 197 |
#[cfg(feature = "std")] |
| 198 |
pub use std::borrow::{Cow, ToOwned}; |
| 199 |
|
| 200 |
#[cfg(all(feature = "alloc", not(feature = "std")))] |
| 201 |
pub use alloc::string::{String, ToString}; |
| 202 |
#[cfg(feature = "std")] |
| 203 |
pub use std::string::{String, ToString}; |
| 204 |
|
| 205 |
#[cfg(all(feature = "alloc", not(feature = "std")))] |
| 206 |
pub use alloc::vec::Vec; |
| 207 |
#[cfg(feature = "std")] |
| 208 |
pub use std::vec::Vec; |
| 209 |
|
| 210 |
#[cfg(all(feature = "alloc", not(feature = "std")))] |
| 211 |
pub use alloc::boxed::Box; |
| 212 |
#[cfg(feature = "std")] |
| 213 |
pub use std::boxed::Box; |
| 214 |
|
| 215 |
#[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))] |
| 216 |
pub use alloc::rc::{Rc, Weak as RcWeak}; |
| 217 |
#[cfg(all(feature = "rc", feature = "std"))] |
| 218 |
pub use std::rc::{Rc, Weak as RcWeak}; |
| 219 |
|
| 220 |
#[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))] |
| 221 |
pub use alloc::sync::{Arc, Weak as ArcWeak}; |
| 222 |
#[cfg(all(feature = "rc", feature = "std"))] |
| 223 |
pub use std::sync::{Arc, Weak as ArcWeak}; |
| 224 |
|
| 225 |
#[cfg(all(feature = "alloc", not(feature = "std")))] |
| 226 |
pub use alloc::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque}; |
| 227 |
#[cfg(feature = "std")] |
| 228 |
pub use std::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque}; |
| 229 |
|
| 230 |
#[cfg(all(not(no_core_cstr), not(feature = "std")))] |
| 231 |
pub use self::core::ffi::CStr; |
| 232 |
#[cfg(feature = "std")] |
| 233 |
pub use std::ffi::CStr; |
| 234 |
|
| 235 |
#[cfg(all(not(no_core_cstr), feature = "alloc", not(feature = "std")))] |
| 236 |
pub use alloc::ffi::CString; |
| 237 |
#[cfg(feature = "std")] |
| 238 |
pub use std::ffi::CString; |
| 239 |
|
| 240 |
#[cfg(feature = "std")] |
| 241 |
pub use std::{error, net}; |
| 242 |
|
| 243 |
#[cfg(feature = "std")] |
| 244 |
pub use std::collections::{HashMap, HashSet}; |
| 245 |
#[cfg(feature = "std")] |
| 246 |
pub use std::ffi::{OsStr, OsString}; |
| 247 |
#[cfg(feature = "std")] |
| 248 |
pub use std::hash::{BuildHasher, Hash}; |
| 249 |
#[cfg(feature = "std")] |
| 250 |
pub use std::io::Write; |
| 251 |
#[cfg(feature = "std")] |
| 252 |
pub use std::path::{Path, PathBuf}; |
| 253 |
#[cfg(feature = "std")] |
| 254 |
pub use std::sync::{Mutex, RwLock}; |
| 255 |
#[cfg(feature = "std")] |
| 256 |
pub use std::time::{SystemTime, UNIX_EPOCH}; |
| 257 |
|
| 258 |
#[cfg(all(feature = "std", no_target_has_atomic, not(no_std_atomic)))] |
| 259 |
pub use std::sync::atomic::{ |
| 260 |
AtomicBool, AtomicI16, AtomicI32, AtomicI8, AtomicIsize, AtomicU16, AtomicU32, AtomicU8, |
| 261 |
AtomicUsize, Ordering, |
| 262 |
}; |
| 263 |
#[cfg(all(feature = "std", no_target_has_atomic, not(no_std_atomic64)))] |
| 264 |
pub use std::sync::atomic::{AtomicI64, AtomicU64}; |
| 265 |
|
| 266 |
#[cfg(all(feature = "std", not(no_target_has_atomic)))] |
| 267 |
pub use std::sync::atomic::Ordering; |
| 268 |
#[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "8"))] |
| 269 |
pub use std::sync::atomic::{AtomicBool, AtomicI8, AtomicU8}; |
| 270 |
#[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "16"))] |
| 271 |
pub use std::sync::atomic::{AtomicI16, AtomicU16}; |
| 272 |
#[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "32"))] |
| 273 |
pub use std::sync::atomic::{AtomicI32, AtomicU32}; |
| 274 |
#[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "64"))] |
| 275 |
pub use std::sync::atomic::{AtomicI64, AtomicU64}; |
| 276 |
#[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "ptr"))] |
| 277 |
pub use std::sync::atomic::{AtomicIsize, AtomicUsize}; |
| 278 |
|
| 279 |
#[cfg(not(no_core_num_saturating))] |
| 280 |
pub use self::core::num::Saturating; |
| 281 |
} |
| 282 |
|
| 283 |
// None of this crate's error handling needs the `From::from` error conversion |
| 284 |
// performed implicitly by the `?` operator or the standard library's `try!` |
| 285 |
// macro. This simplified macro gives a 5.5% improvement in compile time |
| 286 |
// compared to standard `try!`, and 9% improvement compared to `?`. |
| 287 |
macro_rules! tri { |
| 288 |
($expr:expr) => { |
| 289 |
match $expr { |
| 290 |
Ok(val) => val, |
| 291 |
Err(err) => return Err(err), |
| 292 |
} |
| 293 |
}; |
| 294 |
} |
| 295 |
|
| 296 |
//////////////////////////////////////////////////////////////////////////////// |
| 297 |
|
| 298 |
#[macro_use] |
| 299 |
mod macros; |
| 300 |
|
| 301 |
#[macro_use] |
| 302 |
mod integer128; |
| 303 |
|
| 304 |
pub mod de; |
| 305 |
pub mod ser; |
| 306 |
|
| 307 |
#[doc(inline)] |
| 308 |
pub use crate::de::{Deserialize, Deserializer}; |
| 309 |
#[doc(inline)] |
| 310 |
pub use crate::ser::{Serialize, Serializer}; |
| 311 |
|
| 312 |
// Used by generated code and doc tests. Not public API. |
| 313 |
#[doc(hidden)] |
| 314 |
#[path = "private/mod.rs"] |
| 315 |
pub mod __private; |
| 316 |
|
| 317 |
#[path = "de/seed.rs"] |
| 318 |
mod seed; |
| 319 |
|
| 320 |
#[cfg(not(any(feature = "std", feature = "unstable")))] |
| 321 |
mod std_error; |
| 322 |
|
| 323 |
// Re-export #[derive(Serialize, Deserialize)]. |
| 324 |
// |
| 325 |
// The reason re-exporting is not enabled by default is that disabling it would |
| 326 |
// be annoying for crates that provide handwritten impls or data formats. They |
| 327 |
// would need to disable default features and then explicitly re-enable std. |
| 328 |
#[cfg(feature = "serde_derive")] |
| 329 |
extern crate serde_derive; |
| 330 |
|
| 331 |
/// Derive macro available if serde is built with `features = ["derive"]`. |
| 332 |
#[cfg(feature = "serde_derive")] |
| 333 |
#[cfg_attr(doc_cfg, doc(cfg(feature = "derive")))] |
| 334 |
pub use serde_derive::{Deserialize, Serialize}; |
| 335 |
|
| 336 |
#[cfg(all(not(no_serde_derive), any(feature = "std", feature = "alloc")))] |
| 337 |
mod actually_private { |
| 338 |
pub struct T; |
| 339 |
} |