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

alt_serde/
lib.rs
