vendor/serde/src/lib.rs

   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 //! [https://serde.rs/]: https://serde.rs/
  16 //!
  17 //! ## Design
  18 //!
  19 //! Where many other languages rely on runtime reflection for serializing data,
  20 //! Serde is instead built on Rust's powerful trait system. A data structure
  21 //! that knows how to serialize and deserialize itself is one that implements
  22 //! Serde's `Serialize` and `Deserialize` traits (or uses Serde's derive
  23 //! attribute to automatically generate implementations at compile time). This
  24 //! avoids any overhead of reflection or runtime type information. In fact in
  25 //! many situations the interaction between data structure and data format can
  26 //! be completely optimized away by the Rust compiler, leaving Serde
  27 //! serialization to perform the same speed as a handwritten serializer for the
  28 //! specific selection of data structure and data format.
  29 //!
  30 //! ## Data formats
  31 //!
  32 //! The following is a partial list of data formats that have been implemented
  33 //! for Serde by the community.
  34 //!
  35 //! - [JSON], the ubiquitous JavaScript Object Notation used by many HTTP APIs.
  36 //! - [Bincode], a compact binary format
  37 //!   used for IPC within the Servo rendering engine.
  38 //! - [CBOR], a Concise Binary Object Representation designed for small message
  39 //!   size without the need for version negotiation.
  40 //! - [YAML], a self-proclaimed human-friendly configuration language that ain't
  41 //!   markup language.
  42 //! - [MessagePack], an efficient binary format that resembles a compact JSON.
  43 //! - [TOML], a minimal configuration format used by [Cargo].
  44 //! - [Pickle], a format common in the Python world.
  45 //! - [RON], a Rusty Object Notation.
  46 //! - [BSON], the data storage and network transfer format used by MongoDB.
  47 //! - [Avro], a binary format used within Apache Hadoop, with support for schema
  48 //!   definition.
  49 //! - [JSON5], A superset of JSON including some productions from ES5.
  50 //! - [Postcard], a no\_std and embedded-systems friendly compact binary format.
  51 //! - [URL] query strings, in the x-www-form-urlencoded format.
  52 //! - [Envy], a way to deserialize environment variables into Rust structs.
  53 //!   *(deserialization only)*
  54 //! - [Envy Store], a way to deserialize [AWS Parameter Store] parameters into
  55 //!   Rust structs. *(deserialization only)*
  56 //! - [S-expressions], the textual representation of code and data used by the
  57 //!   Lisp language family.
  58 //! - [D-Bus]'s binary wire format.
  59 //! - [FlexBuffers], the schemaless cousin of Google's FlatBuffers zero-copy serialization format.
  60 //!
  61 //! [JSON]: https://github.com/serde-rs/json
  62 //! [Bincode]: https://github.com/servo/bincode
  63 //! [CBOR]: https://github.com/pyfisch/cbor
  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]: http://doc.crates.io/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
  82 ////////////////////////////////////////////////////////////////////////////////
  83
  84 // Serde types in rustdoc of other crates get linked to here.
  85 #![doc(html_root_url = "https://docs.rs/serde/1.0.116")]
  86 // Support using Serde without the standard library!
  87 #![cfg_attr(not(feature = "std"), no_std)]
  88 // Unstable functionality only if the user asks for it. For tracking and
  89 // discussion of these features please refer to this issue:
  90 //
  91 //    https://github.com/serde-rs/serde/issues/812
  92 #![cfg_attr(feature = "unstable", feature(never_type))]
  93 #![allow(unknown_lints, bare_trait_objects, deprecated)]
  94 #![cfg_attr(feature = "cargo-clippy", allow(renamed_and_removed_lints))]
  95 #![cfg_attr(feature = "cargo-clippy", deny(clippy, clippy_pedantic))]
  96 // Ignored clippy and clippy_pedantic lints
  97 #![cfg_attr(
  98     feature = "cargo-clippy",
  99     allow(
 100         // clippy bug: https://github.com/rust-lang/rust-clippy/issues/5704
 101         unnested_or_patterns,
 102         // not available in our oldest supported compiler
 103         checked_conversions,
 104         empty_enum,
 105         redundant_field_names,
 106         redundant_static_lifetimes,
 107         // integer and float ser/de requires these sorts of casts
 108         cast_possible_truncation,
 109         cast_possible_wrap,
 110         cast_sign_loss,
 111         // things are often more readable this way
 112         cast_lossless,
 113         module_name_repetitions,
 114         option_if_let_else,
 115         single_match_else,
 116         type_complexity,
 117         use_self,
 118         zero_prefixed_literal,
 119         // correctly used
 120         enum_glob_use,
 121         wildcard_imports,
 122         // not practical
 123         needless_pass_by_value,
 124         similar_names,
 125         too_many_lines,
 126         // preference
 127         doc_markdown,
 128         unseparated_literal_suffix,
 129         // false positive
 130         needless_doctest_main,
 131         // noisy
 132         missing_errors_doc,
 133         must_use_candidate,
 134     )
 135 )]
 136 // Rustc lints.
 137 #![forbid(unsafe_code)]
 138 #![deny(missing_docs, unused_imports)]
 139
 140 ////////////////////////////////////////////////////////////////////////////////
 141
 142 #[cfg(feature = "alloc")]
 143 extern crate alloc;
 144
 145 /// A facade around all the types we need from the `std`, `core`, and `alloc`
 146 /// crates. This avoids elaborate import wrangling having to happen in every
 147 /// module.
 148 mod lib {
 149     mod core {
 150         #[cfg(not(feature = "std"))]
 151         pub use core::*;
 152         #[cfg(feature = "std")]
 153         pub use std::*;
 154     }
 155
 156     pub use self::core::{cmp, iter, mem, num, slice, str};
 157     pub use self::core::{f32, f64};
 158     pub use self::core::{i16, i32, i64, i8, isize};
 159     pub use self::core::{u16, u32, u64, u8, usize};
 160
 161     pub use self::core::cell::{Cell, RefCell};
 162     pub use self::core::clone::{self, Clone};
 163     pub use self::core::convert::{self, From, Into};
 164     pub use self::core::default::{self, Default};
 165     pub use self::core::fmt::{self, Debug, Display};
 166     pub use self::core::marker::{self, PhantomData};
 167     pub use self::core::ops::Range;
 168     pub use self::core::option::{self, Option};
 169     pub use self::core::result::{self, Result};
 170
 171     #[cfg(all(feature = "alloc", not(feature = "std")))]
 172     pub use alloc::borrow::{Cow, ToOwned};
 173     #[cfg(feature = "std")]
 174     pub use std::borrow::{Cow, ToOwned};
 175
 176     #[cfg(all(feature = "alloc", not(feature = "std")))]
 177     pub use alloc::string::{String, ToString};
 178     #[cfg(feature = "std")]
 179     pub use std::string::{String, ToString};
 180
 181     #[cfg(all(feature = "alloc", not(feature = "std")))]
 182     pub use alloc::vec::Vec;
 183     #[cfg(feature = "std")]
 184     pub use std::vec::Vec;
 185
 186     #[cfg(all(feature = "alloc", not(feature = "std")))]
 187     pub use alloc::boxed::Box;
 188     #[cfg(feature = "std")]
 189     pub use std::boxed::Box;
 190
 191     #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
 192     pub use alloc::rc::{Rc, Weak as RcWeak};
 193     #[cfg(all(feature = "rc", feature = "std"))]
 194     pub use std::rc::{Rc, Weak as RcWeak};
 195
 196     #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
 197     pub use alloc::sync::{Arc, Weak as ArcWeak};
 198     #[cfg(all(feature = "rc", feature = "std"))]
 199     pub use std::sync::{Arc, Weak as ArcWeak};
 200
 201     #[cfg(all(feature = "alloc", not(feature = "std")))]
 202     pub use alloc::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque};
 203     #[cfg(feature = "std")]
 204     pub use std::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque};
 205
 206     #[cfg(feature = "std")]
 207     pub use std::{error, net};
 208
 209     #[cfg(feature = "std")]
 210     pub use std::collections::{HashMap, HashSet};
 211     #[cfg(feature = "std")]
 212     pub use std::ffi::{CStr, CString, OsStr, OsString};
 213     #[cfg(feature = "std")]
 214     pub use std::hash::{BuildHasher, Hash};
 215     #[cfg(feature = "std")]
 216     pub use std::io::Write;
 217     #[cfg(feature = "std")]
 218     pub use std::num::Wrapping;
 219     #[cfg(feature = "std")]
 220     pub use std::path::{Path, PathBuf};
 221     #[cfg(feature = "std")]
 222     pub use std::sync::{Mutex, RwLock};
 223     #[cfg(feature = "std")]
 224     pub use std::time::{SystemTime, UNIX_EPOCH};
 225
 226     #[cfg(all(feature = "std", collections_bound))]
 227     pub use std::collections::Bound;
 228
 229     #[cfg(core_reverse)]
 230     pub use self::core::cmp::Reverse;
 231
 232     #[cfg(ops_bound)]
 233     pub use self::core::ops::Bound;
 234
 235     #[cfg(range_inclusive)]
 236     pub use self::core::ops::RangeInclusive;
 237
 238     #[cfg(all(feature = "std", std_atomic))]
 239     pub use std::sync::atomic::{
 240         AtomicBool, AtomicI16, AtomicI32, AtomicI8, AtomicIsize, AtomicU16, AtomicU32, AtomicU8,
 241         AtomicUsize, Ordering,
 242     };
 243     #[cfg(all(feature = "std", std_atomic64))]
 244     pub use std::sync::atomic::{AtomicI64, AtomicU64};
 245
 246     #[cfg(any(core_duration, feature = "std"))]
 247     pub use self::core::time::Duration;
 248 }
 249
 250 ////////////////////////////////////////////////////////////////////////////////
 251
 252 #[macro_use]
 253 mod macros;
 254
 255 #[macro_use]
 256 mod integer128;
 257
 258 pub mod de;
 259 pub mod ser;
 260
 261 #[doc(inline)]
 262 pub use de::{Deserialize, Deserializer};
 263 #[doc(inline)]
 264 pub use ser::{Serialize, Serializer};
 265
 266 // Generated code uses these to support no_std. Not public API.
 267 #[doc(hidden)]
 268 pub mod export;
 269
 270 // Helpers used by generated code and doc tests. Not public API.
 271 #[doc(hidden)]
 272 pub mod private;
 273
 274 #[cfg(not(feature = "std"))]
 275 mod std_error;
 276
 277 // Re-export #[derive(Serialize, Deserialize)].
 278 //
 279 // The reason re-exporting is not enabled by default is that disabling it would
 280 // be annoying for crates that provide handwritten impls or data formats. They
 281 // would need to disable default features and then explicitly re-enable std.
 282 #[cfg(feature = "serde_derive")]
 283 #[allow(unused_imports)]
 284 #[macro_use]
 285 extern crate serde_derive;
 286 #[cfg(feature = "serde_derive")]
 287 #[doc(hidden)]
 288 pub use serde_derive::*;