src/vendor/serde/src/lib.rs

   1 // Copyright 2017 Serde Developers
   2 //
   3 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   4 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   5 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   6 // option. This file may not be copied, modified, or distributed
   7 // except according to those terms.
   8
   9 //! # Serde
  10 //!
  11 //! Serde is a framework for ***ser***ializing and ***de***serializing Rust data
  12 //! structures efficiently and generically.
  13 //!
  14 //! The Serde ecosystem consists of data structures that know how to serialize
  15 //! and deserialize themselves along with data formats that know how to
  16 //! serialize and deserialize other things. Serde provides the layer by which
  17 //! these two groups interact with each other, allowing any supported data
  18 //! structure to be serialized and deserialized using any supported data format.
  19 //!
  20 //! See the Serde website [https://serde.rs/] for additional documentation and
  21 //! usage examples.
  22 //!
  23 //! [https://serde.rs/]: https://serde.rs/
  24 //!
  25 //! ## Design
  26 //!
  27 //! Where many other languages rely on runtime reflection for serializing data,
  28 //! Serde is instead built on Rust's powerful trait system. A data structure
  29 //! that knows how to serialize and deserialize itself is one that implements
  30 //! Serde's `Serialize` and `Deserialize` traits (or uses Serde's derive
  31 //! attribute to automatically generate implementations at compile time). This
  32 //! avoids any overhead of reflection or runtime type information. In fact in
  33 //! many situations the interaction between data structure and data format can
  34 //! be completely optimized away by the Rust compiler, leaving Serde
  35 //! serialization to perform the same speed as a handwritten serializer for the
  36 //! specific selection of data structure and data format.
  37 //!
  38 //! ## Data formats
  39 //!
  40 //! The following is a partial list of data formats that have been implemented
  41 //! for Serde by the community.
  42 //!
  43 //! - [JSON], the ubiquitous JavaScript Object Notation used by many HTTP APIs.
  44 //! - [Bincode], a compact binary format
  45 //!   used for IPC within the Servo rendering engine.
  46 //! - [CBOR], a Concise Binary Object Representation designed for small message
  47 //!   size without the need for version negotiation.
  48 //! - [YAML], a popular human-friendly configuration language that ain't markup
  49 //!   language.
  50 //! - [MessagePack], an efficient binary format that resembles a compact JSON.
  51 //! - [TOML], a minimal configuration format used by [Cargo].
  52 //! - [Pickle], a format common in the Python world.
  53 //! - [Hjson], a variant of JSON designed to be readable and writable by humans.
  54 //! - [BSON], the data storage and network transfer format used by MongoDB.
  55 //! - [URL], the x-www-form-urlencoded format.
  56 //! - [XML], the flexible machine-friendly W3C standard.
  57 //!   *(deserialization only)*
  58 //! - [Envy], a way to deserialize environment variables into Rust structs.
  59 //!   *(deserialization only)*
  60 //! - [Redis], deserialize values from Redis when using [redis-rs].
  61 //!   *(deserialization only)*
  62 //!
  63 //! [JSON]: https://github.com/serde-rs/json
  64 //! [Bincode]: https://github.com/TyOverby/bincode
  65 //! [CBOR]: https://github.com/pyfisch/cbor
  66 //! [YAML]: https://github.com/dtolnay/serde-yaml
  67 //! [MessagePack]: https://github.com/3Hren/msgpack-rust
  68 //! [TOML]: https://github.com/alexcrichton/toml-rs
  69 //! [Pickle]: https://github.com/birkenfeld/serde-pickle
  70 //! [Hjson]: https://github.com/laktak/hjson-rust
  71 //! [BSON]: https://github.com/zonyitoo/bson-rs
  72 //! [URL]: https://github.com/nox/serde_urlencoded
  73 //! [XML]: https://github.com/RReverser/serde-xml-rs
  74 //! [Envy]: https://github.com/softprops/envy
  75 //! [Redis]: https://github.com/OneSignal/serde-redis
  76 //! [Cargo]: http://doc.crates.io/manifest.html
  77 //! [redis-rs]: https://crates.io/crates/redis
  78
  79 ////////////////////////////////////////////////////////////////////////////////
  80
  81 // Serde types in rustdoc of other crates get linked to here.
  82 #![doc(html_root_url = "https://docs.rs/serde/1.0.35")]
  83 // Support using Serde without the standard library!
  84 #![cfg_attr(not(feature = "std"), no_std)]
  85 // Unstable functionality only if the user asks for it. For tracking and
  86 // discussion of these features please refer to this issue:
  87 //
  88 //    https://github.com/serde-rs/serde/issues/812
  89 #![cfg_attr(feature = "unstable", feature(nonzero, specialization))]
  90 #![cfg_attr(feature = "alloc", feature(alloc))]
  91 #![cfg_attr(feature = "cargo-clippy", deny(clippy, clippy_pedantic))]
  92 // Whitelisted clippy lints
  93 #![cfg_attr(feature = "cargo-clippy",
  94             allow(cast_lossless, const_static_lifetime, doc_markdown, linkedlist,
  95                   needless_pass_by_value, redundant_field_names, type_complexity,
  96                   unreadable_literal, zero_prefixed_literal))]
  97 // Whitelisted clippy_pedantic lints
  98 #![cfg_attr(feature = "cargo-clippy", allow(
  99 // integer and float ser/de requires these sorts of casts
 100     cast_possible_truncation,
 101     cast_possible_wrap,
 102     cast_precision_loss,
 103     cast_sign_loss,
 104 // simplifies some macros
 105     invalid_upcast_comparisons,
 106 // things are often more readable this way
 107     decimal_literal_representation,
 108     option_unwrap_used,
 109     result_unwrap_used,
 110     shadow_reuse,
 111     single_match_else,
 112     stutter,
 113     use_self,
 114 // not practical
 115     many_single_char_names,
 116     missing_docs_in_private_items,
 117     similar_names,
 118 // alternative is not stable
 119     empty_enum,
 120     use_debug,
 121 ))]
 122 // Blacklisted Rust lints.
 123 #![deny(missing_docs, unused_imports)]
 124
 125 ////////////////////////////////////////////////////////////////////////////////
 126
 127 #[cfg(feature = "alloc")]
 128 extern crate alloc;
 129
 130 #[cfg(all(feature = "unstable", feature = "std"))]
 131 extern crate core;
 132
 133 /// A facade around all the types we need from the `std`, `core`, and `alloc`
 134 /// crates. This avoids elaborate import wrangling having to happen in every
 135 /// module.
 136 mod lib {
 137     mod core {
 138         #[cfg(feature = "std")]
 139         pub use std::*;
 140         #[cfg(not(feature = "std"))]
 141         pub use core::*;
 142     }
 143
 144     pub use self::core::{cmp, iter, mem, ops, slice, str};
 145     pub use self::core::{isize, i16, i32, i64, i8};
 146     pub use self::core::{usize, u16, u32, u64, u8};
 147     pub use self::core::{f32, f64};
 148
 149     pub use self::core::cell::{Cell, RefCell};
 150     pub use self::core::clone::{self, Clone};
 151     pub use self::core::convert::{self, From, Into};
 152     pub use self::core::default::{self, Default};
 153     pub use self::core::fmt::{self, Debug, Display};
 154     pub use self::core::marker::{self, PhantomData};
 155     pub use self::core::option::{self, Option};
 156     pub use self::core::result::{self, Result};
 157
 158     #[cfg(feature = "std")]
 159     pub use std::borrow::{Cow, ToOwned};
 160     #[cfg(all(feature = "alloc", not(feature = "std")))]
 161     pub use alloc::borrow::{Cow, ToOwned};
 162
 163     #[cfg(feature = "std")]
 164     pub use std::string::String;
 165     #[cfg(all(feature = "alloc", not(feature = "std")))]
 166     pub use alloc::string::{String, ToString};
 167
 168     #[cfg(feature = "std")]
 169     pub use std::vec::Vec;
 170     #[cfg(all(feature = "alloc", not(feature = "std")))]
 171     pub use alloc::vec::Vec;
 172
 173     #[cfg(feature = "std")]
 174     pub use std::boxed::Box;
 175     #[cfg(all(feature = "alloc", not(feature = "std")))]
 176     pub use alloc::boxed::Box;
 177
 178     #[cfg(all(feature = "rc", feature = "std"))]
 179     pub use std::rc::Rc;
 180     #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
 181     pub use alloc::rc::Rc;
 182
 183     #[cfg(all(feature = "rc", feature = "std"))]
 184     pub use std::sync::Arc;
 185     #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
 186     pub use alloc::arc::Arc;
 187
 188     #[cfg(feature = "std")]
 189     pub use std::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque};
 190     #[cfg(all(feature = "alloc", not(feature = "std")))]
 191     pub use alloc::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque};
 192
 193     #[cfg(feature = "std")]
 194     pub use std::{error, net};
 195
 196     #[cfg(feature = "std")]
 197     pub use std::collections::{HashMap, HashSet};
 198     #[cfg(feature = "std")]
 199     pub use std::ffi::{CStr, CString, OsStr, OsString};
 200     #[cfg(feature = "std")]
 201     pub use std::hash::{BuildHasher, Hash};
 202     #[cfg(feature = "std")]
 203     pub use std::io::Write;
 204     #[cfg(feature = "std")]
 205     pub use std::num::Wrapping;
 206     #[cfg(feature = "std")]
 207     pub use std::path::{Path, PathBuf};
 208     #[cfg(feature = "std")]
 209     pub use std::time::{Duration, SystemTime, UNIX_EPOCH};
 210     #[cfg(feature = "std")]
 211     pub use std::sync::{Mutex, RwLock};
 212
 213     #[cfg(feature = "unstable")]
 214     #[allow(deprecated)]
 215     pub use core::nonzero::{NonZero, Zeroable};
 216
 217     #[cfg(feature = "unstable")]
 218     pub use core::num::{NonZeroU8, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroUsize};
 219 }
 220
 221 ////////////////////////////////////////////////////////////////////////////////
 222
 223 #[macro_use]
 224 mod macros;
 225
 226 pub mod ser;
 227 pub mod de;
 228
 229 #[doc(inline)]
 230 pub use ser::{Serialize, Serializer};
 231 #[doc(inline)]
 232 pub use de::{Deserialize, Deserializer};
 233
 234 // Generated code uses these to support no_std. Not public API.
 235 #[doc(hidden)]
 236 pub mod export;
 237
 238 // Helpers used by generated code and doc tests. Not public API.
 239 #[doc(hidden)]
 240 pub mod private;
 241
 242 // Re-export #[derive(Serialize, Deserialize)].
 243 //
 244 // This is a workaround for https://github.com/rust-lang/cargo/issues/1286.
 245 // Without this re-export, crates that put Serde derives behind a cfg_attr would
 246 // need to use some silly feature name that depends on both serde and
 247 // serde_derive.
 248 //
 249 //     [features]
 250 //     serde-impls = ["serde", "serde_derive"]
 251 //
 252 //     [dependencies]
 253 //     serde = { version = "1.0", optional = true }
 254 //     serde_derive = { version = "1.0", optional = true }
 255 //
 256 //     # Used like this:
 257 //     # #[cfg(feature = "serde-impls")]
 258 //     # #[macro_use]
 259 //     # extern crate serde_derive;
 260 //     #
 261 //     # #[cfg_attr(feature = "serde-impls", derive(Serialize, Deserialize))]
 262 //     # struct S { /* ... */ }
 263 //
 264 // The re-exported derives allow crates to use "serde" as the name of their
 265 // Serde feature which is more intuitive.
 266 //
 267 //     [dependencies]
 268 //     serde = { version = "1.0", optional = true, features = ["derive"] }
 269 //
 270 //     # Used like this:
 271 //     # #[cfg(feature = "serde")]
 272 //     # #[macro_use]
 273 //     # extern crate serde;
 274 //     #
 275 //     # #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 276 //     # struct S { /* ... */ }
 277 //
 278 // The reason re-exporting is not enabled by default is that disabling it would
 279 // be annoying for crates that provide handwritten impls or data formats. They
 280 // would need to disable default features and then explicitly re-enable std.
 281 #[cfg(feature = "serde_derive")]
 282 #[allow(unused_imports)]
 283 #[macro_use]
 284 extern crate serde_derive;
 285 #[cfg(feature = "serde_derive")]
 286 #[doc(hidden)]
 287 pub use serde_derive::*;