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 popular human-friendly configuration language that ain't markup
  41 //!   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 //! - [Hjson], a variant of JSON designed to be readable and writable by humans.
  50 //! - [JSON5], A superset of JSON including some productions from ES5.
  51 //! - [URL], 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 //!
  57 //! [JSON]: https://github.com/serde-rs/json
  58 //! [Bincode]: https://github.com/TyOverby/bincode
  59 //! [CBOR]: https://github.com/pyfisch/cbor
  60 //! [YAML]: https://github.com/dtolnay/serde-yaml
  61 //! [MessagePack]: https://github.com/3Hren/msgpack-rust
  62 //! [TOML]: https://github.com/alexcrichton/toml-rs
  63 //! [Pickle]: https://github.com/birkenfeld/serde-pickle
  64 //! [RON]: https://github.com/ron-rs/ron
  65 //! [BSON]: https://github.com/zonyitoo/bson-rs
  66 //! [Avro]: https://github.com/flavray/avro-rs
  67 //! [Hjson]: https://github.com/laktak/hjson-rust
  68 //! [JSON5]: https://github.com/callum-oakley/json5-rs
  69 //! [URL]: https://github.com/nox/serde_urlencoded
  70 //! [Envy]: https://github.com/softprops/envy
  71 //! [Envy Store]: https://github.com/softprops/envy-store
  72 //! [Cargo]: http://doc.crates.io/manifest.html
  73 //! [AWS Parameter Store]: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html
  74
  75 ////////////////////////////////////////////////////////////////////////////////
  76
  77 // Serde types in rustdoc of other crates get linked to here.
  78 #![doc(html_root_url = "https://docs.rs/serde/1.0.81")]
  79 // Support using Serde without the standard library!
  80 #![cfg_attr(not(feature = "std"), no_std)]
  81 // Unstable functionality only if the user asks for it. For tracking and
  82 // discussion of these features please refer to this issue:
  83 //
  84 //    https://github.com/serde-rs/serde/issues/812
  85 #![cfg_attr(feature = "unstable", feature(specialization, never_type))]
  86 #![cfg_attr(feature = "alloc", feature(alloc))]
  87 #![cfg_attr(feature = "cargo-clippy", allow(renamed_and_removed_lints))]
  88 #![cfg_attr(feature = "cargo-clippy", deny(clippy, clippy_pedantic))]
  89 // Whitelisted clippy lints
  90 #![cfg_attr(
  91     feature = "cargo-clippy",
  92     allow(
  93         cast_lossless,
  94         const_static_lifetime,
  95         doc_markdown,
  96         linkedlist,
  97         needless_pass_by_value,
  98         redundant_field_names,
  99         type_complexity,
 100         unreadable_literal,
 101         zero_prefixed_literal
 102     )
 103 )]
 104 // Whitelisted clippy_pedantic lints
 105 #![cfg_attr(feature = "cargo-clippy", allow(
 106 // integer and float ser/de requires these sorts of casts
 107     cast_possible_truncation,
 108     cast_possible_wrap,
 109     cast_precision_loss,
 110     cast_sign_loss,
 111 // simplifies some macros
 112     invalid_upcast_comparisons,
 113 // things are often more readable this way
 114     decimal_literal_representation,
 115     option_unwrap_used,
 116     result_unwrap_used,
 117     shadow_reuse,
 118     single_match_else,
 119     stutter,
 120     use_self,
 121 // not practical
 122     indexing_slicing,
 123     many_single_char_names,
 124     missing_docs_in_private_items,
 125     similar_names,
 126 // alternative is not stable
 127     empty_enum,
 128     use_debug,
 129 ))]
 130 // Blacklisted Rust lints.
 131 //
 132 // Compiler bug involving unused_imports:
 133 // https://github.com/rust-lang/rust/issues/51661
 134 #![deny(missing_docs, /*unused_imports*/)]
 135
 136 ////////////////////////////////////////////////////////////////////////////////
 137
 138 #[cfg(feature = "alloc")]
 139 extern crate alloc;
 140
 141 /// A facade around all the types we need from the `std`, `core`, and `alloc`
 142 /// crates. This avoids elaborate import wrangling having to happen in every
 143 /// module.
 144 mod lib {
 145     mod core {
 146         #[cfg(not(feature = "std"))]
 147         pub use core::*;
 148         #[cfg(feature = "std")]
 149         pub use std::*;
 150     }
 151
 152     pub use self::core::{cmp, iter, mem, num, slice, str};
 153     pub use self::core::{f32, f64};
 154     pub use self::core::{i16, i32, i64, i8, isize};
 155     pub use self::core::{u16, u32, u64, u8, usize};
 156
 157     pub use self::core::cell::{Cell, RefCell};
 158     pub use self::core::clone::{self, Clone};
 159     pub use self::core::convert::{self, From, Into};
 160     pub use self::core::default::{self, Default};
 161     pub use self::core::fmt::{self, Debug, Display};
 162     pub use self::core::marker::{self, PhantomData};
 163     pub use self::core::ops::Range;
 164     pub use self::core::option::{self, Option};
 165     pub use self::core::result::{self, Result};
 166
 167     #[cfg(all(feature = "alloc", not(feature = "std")))]
 168     pub use alloc::borrow::{Cow, ToOwned};
 169     #[cfg(feature = "std")]
 170     pub use std::borrow::{Cow, ToOwned};
 171
 172     #[cfg(all(feature = "alloc", not(feature = "std")))]
 173     pub use alloc::string::{String, ToString};
 174     #[cfg(feature = "std")]
 175     pub use std::string::String;
 176
 177     #[cfg(all(feature = "alloc", not(feature = "std")))]
 178     pub use alloc::vec::Vec;
 179     #[cfg(feature = "std")]
 180     pub use std::vec::Vec;
 181
 182     #[cfg(all(feature = "alloc", not(feature = "std")))]
 183     pub use alloc::boxed::Box;
 184     #[cfg(feature = "std")]
 185     pub use std::boxed::Box;
 186
 187     #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
 188     pub use alloc::rc::{Rc, Weak as RcWeak};
 189     #[cfg(all(feature = "rc", feature = "std"))]
 190     pub use std::rc::{Rc, Weak as RcWeak};
 191
 192     #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
 193     pub use alloc::sync::{Arc, Weak as ArcWeak};
 194     #[cfg(all(feature = "rc", feature = "std"))]
 195     pub use std::sync::{Arc, Weak as ArcWeak};
 196
 197     #[cfg(all(feature = "alloc", not(feature = "std")))]
 198     pub use alloc::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque};
 199     #[cfg(feature = "std")]
 200     pub use std::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque};
 201
 202     #[cfg(feature = "std")]
 203     pub use std::{error, net};
 204
 205     #[cfg(feature = "std")]
 206     pub use std::collections::{HashMap, HashSet};
 207     #[cfg(feature = "std")]
 208     pub use std::ffi::{CStr, CString, OsStr, OsString};
 209     #[cfg(feature = "std")]
 210     pub use std::hash::{BuildHasher, Hash};
 211     #[cfg(feature = "std")]
 212     pub use std::io::Write;
 213     #[cfg(feature = "std")]
 214     pub use std::num::Wrapping;
 215     #[cfg(feature = "std")]
 216     pub use std::path::{Path, PathBuf};
 217     #[cfg(feature = "std")]
 218     pub use std::sync::{Mutex, RwLock};
 219     #[cfg(feature = "std")]
 220     pub use std::time::{SystemTime, UNIX_EPOCH};
 221
 222     #[cfg(any(core_duration, feature = "std"))]
 223     pub use self::core::time::Duration;
 224
 225     #[cfg(range_inclusive)]
 226     pub use self::core::ops::RangeInclusive;
 227 }
 228
 229 ////////////////////////////////////////////////////////////////////////////////
 230
 231 #[macro_use]
 232 mod macros;
 233
 234 #[macro_use]
 235 mod integer128;
 236
 237 pub mod de;
 238 pub mod ser;
 239
 240 #[doc(inline)]
 241 pub use de::{Deserialize, Deserializer};
 242 #[doc(inline)]
 243 pub use ser::{Serialize, Serializer};
 244
 245 // Generated code uses these to support no_std. Not public API.
 246 #[doc(hidden)]
 247 pub mod export;
 248
 249 // Helpers used by generated code and doc tests. Not public API.
 250 #[doc(hidden)]
 251 pub mod private;
 252
 253 // Re-export #[derive(Serialize, Deserialize)].
 254 //
 255 // This is a workaround for https://github.com/rust-lang/cargo/issues/1286.
 256 // Without this re-export, crates that put Serde derives behind a cfg_attr would
 257 // need to use some silly feature name that depends on both serde and
 258 // serde_derive.
 259 //
 260 //     [features]
 261 //     serde-impls = ["serde", "serde_derive"]
 262 //
 263 //     [dependencies]
 264 //     serde = { version = "1.0", optional = true }
 265 //     serde_derive = { version = "1.0", optional = true }
 266 //
 267 //     # Used like this:
 268 //     # #[cfg(feature = "serde-impls")]
 269 //     # #[macro_use]
 270 //     # extern crate serde_derive;
 271 //     #
 272 //     # #[cfg_attr(feature = "serde-impls", derive(Serialize, Deserialize))]
 273 //     # struct S { /* ... */ }
 274 //
 275 // The re-exported derives allow crates to use "serde" as the name of their
 276 // Serde feature which is more intuitive.
 277 //
 278 //     [dependencies]
 279 //     serde = { version = "1.0", optional = true, features = ["derive"] }
 280 //
 281 //     # Used like this:
 282 //     # #[cfg(feature = "serde")]
 283 //     # #[macro_use]
 284 //     # extern crate serde;
 285 //     #
 286 //     # #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 287 //     # struct S { /* ... */ }
 288 //
 289 // The reason re-exporting is not enabled by default is that disabling it would
 290 // be annoying for crates that provide handwritten impls or data formats. They
 291 // would need to disable default features and then explicitly re-enable std.
 292 #[cfg(feature = "serde_derive")]
 293 #[allow(unused_imports)]
 294 #[macro_use]
 295 extern crate serde_derive;
 296 #[cfg(feature = "serde_derive")]
 297 #[doc(hidden)]
 298 pub use serde_derive::*;