serde_core/
lib.rs

1//! Serde is a framework for ***ser***ializing and ***de***serializing Rust data
2//! structures efficiently and generically.
3//!
4//! The `serde_core` crate contains Serde's trait definitions with **no support
5//! for #\[derive()\]**.
6//!
7//! In crates that derive an implementation of `Serialize` or `Deserialize`, you
8//! must depend on the [`serde`] crate, not `serde_core`.
9//!
10//! [`serde`]: https://crates.io/crates/serde
11//!
12//! In crates that handwrite implementations of Serde traits, or only use them
13//! as trait bounds, depending on `serde_core` is permitted. But `serde`
14//! re-exports all of these traits and can be used for this use case too. If in
15//! doubt, disregard `serde_core` and always use `serde`.
16//!
17//! Crates that depend on `serde_core` instead of `serde` are able to compile in
18//! parallel with `serde_derive` even when `serde`'s "derive" feature is turned on,
19//! as shown in the following build timings.
20//!
21//! <br>
22//!
23//! <table>
24//! <tr><td align="center">When <code>serde_json</code> depends on <code>serde</code></td></tr>
25//! <tr><td><img src="https://github.com/user-attachments/assets/78dc179c-6ab1-4059-928c-1474b0d9d0bb"></td></tr>
26//! </table>
27//!
28//! <br>
29//!
30//! <table>
31//! <tr><td align="center">When <code>serde_json</code> depends on <code>serde_core</code></td></tr>
32//! <tr><td><img src="https://github.com/user-attachments/assets/6b6cff5e-3e45-4ac7-9db1-d99ee8b9f5f7"></td></tr>
33//! </table>
34
35////////////////////////////////////////////////////////////////////////////////
36
37// Serde types in rustdoc of other crates get linked to here.
38#![doc(html_root_url = "https://docs.rs/serde_core/1.0.226")]
39// Support using Serde without the standard library!
40#![cfg_attr(not(feature = "std"), no_std)]
41// Show which crate feature enables conditionally compiled APIs in documentation.
42#![cfg_attr(docsrs, feature(doc_cfg, rustdoc_internals))]
43#![cfg_attr(docsrs, allow(internal_features))]
44// Unstable functionality only if the user asks for it. For tracking and
45// discussion of these features please refer to this issue:
46//
47//    https://github.com/serde-rs/serde/issues/812
48#![cfg_attr(feature = "unstable", feature(never_type))]
49#![allow(unknown_lints, bare_trait_objects, deprecated)]
50// Ignored clippy and clippy_pedantic lints
51#![allow(
52    // clippy bug: https://github.com/rust-lang/rust-clippy/issues/5704
53    clippy::unnested_or_patterns,
54    // clippy bug: https://github.com/rust-lang/rust-clippy/issues/7768
55    clippy::semicolon_if_nothing_returned,
56    // not available in our oldest supported compiler
57    clippy::empty_enum,
58    clippy::type_repetition_in_bounds, // https://github.com/rust-lang/rust-clippy/issues/8772
59    // integer and float ser/de requires these sorts of casts
60    clippy::cast_possible_truncation,
61    clippy::cast_possible_wrap,
62    clippy::cast_precision_loss,
63    clippy::cast_sign_loss,
64    // things are often more readable this way
65    clippy::cast_lossless,
66    clippy::module_name_repetitions,
67    clippy::single_match_else,
68    clippy::type_complexity,
69    clippy::use_self,
70    clippy::zero_prefixed_literal,
71    // correctly used
72    clippy::derive_partial_eq_without_eq,
73    clippy::enum_glob_use,
74    clippy::explicit_auto_deref,
75    clippy::incompatible_msrv,
76    clippy::let_underscore_untyped,
77    clippy::map_err_ignore,
78    clippy::new_without_default,
79    clippy::result_unit_err,
80    clippy::wildcard_imports,
81    // not practical
82    clippy::needless_pass_by_value,
83    clippy::similar_names,
84    clippy::too_many_lines,
85    // preference
86    clippy::doc_markdown,
87    clippy::elidable_lifetime_names,
88    clippy::needless_lifetimes,
89    clippy::unseparated_literal_suffix,
90    // false positive
91    clippy::needless_doctest_main,
92    // noisy
93    clippy::missing_errors_doc,
94    clippy::must_use_candidate,
95)]
96// Restrictions
97#![deny(clippy::question_mark_used)]
98// Rustc lints.
99#![deny(missing_docs, unused_imports)]
100
101////////////////////////////////////////////////////////////////////////////////
102
103#[cfg(feature = "alloc")]
104extern crate alloc;
105
106/// A facade around all the types we need from the `std`, `core`, and `alloc`
107/// crates. This avoids elaborate import wrangling having to happen in every
108/// module.
109mod lib {
110    mod core {
111        #[cfg(not(feature = "std"))]
112        pub use core::*;
113        #[cfg(feature = "std")]
114        pub use std::*;
115    }
116
117    pub use self::core::{f32, f64};
118    pub use self::core::{iter, num, str};
119
120    #[cfg(any(feature = "std", feature = "alloc"))]
121    pub use self::core::{cmp, mem};
122
123    pub use self::core::cell::{Cell, RefCell};
124    pub use self::core::cmp::Reverse;
125    pub use self::core::fmt::{self, Debug, Display, Write as FmtWrite};
126    pub use self::core::marker::PhantomData;
127    pub use self::core::num::Wrapping;
128    pub use self::core::ops::{Bound, Range, RangeFrom, RangeInclusive, RangeTo};
129    pub use self::core::result;
130    pub use self::core::time::Duration;
131
132    #[cfg(all(feature = "alloc", not(feature = "std")))]
133    pub use alloc::borrow::{Cow, ToOwned};
134    #[cfg(feature = "std")]
135    pub use std::borrow::{Cow, ToOwned};
136
137    #[cfg(all(feature = "alloc", not(feature = "std")))]
138    pub use alloc::string::{String, ToString};
139    #[cfg(feature = "std")]
140    pub use std::string::{String, ToString};
141
142    #[cfg(all(feature = "alloc", not(feature = "std")))]
143    pub use alloc::vec::Vec;
144    #[cfg(feature = "std")]
145    pub use std::vec::Vec;
146
147    #[cfg(all(feature = "alloc", not(feature = "std")))]
148    pub use alloc::boxed::Box;
149    #[cfg(feature = "std")]
150    pub use std::boxed::Box;
151
152    #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
153    pub use alloc::rc::{Rc, Weak as RcWeak};
154    #[cfg(all(feature = "rc", feature = "std"))]
155    pub use std::rc::{Rc, Weak as RcWeak};
156
157    #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))]
158    pub use alloc::sync::{Arc, Weak as ArcWeak};
159    #[cfg(all(feature = "rc", feature = "std"))]
160    pub use std::sync::{Arc, Weak as ArcWeak};
161
162    #[cfg(all(feature = "alloc", not(feature = "std")))]
163    pub use alloc::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque};
164    #[cfg(feature = "std")]
165    pub use std::collections::{BTreeMap, BTreeSet, BinaryHeap, LinkedList, VecDeque};
166
167    #[cfg(all(not(no_core_cstr), not(feature = "std")))]
168    pub use self::core::ffi::CStr;
169    #[cfg(feature = "std")]
170    pub use std::ffi::CStr;
171
172    #[cfg(all(not(no_core_cstr), feature = "alloc", not(feature = "std")))]
173    pub use alloc::ffi::CString;
174    #[cfg(feature = "std")]
175    pub use std::ffi::CString;
176
177    #[cfg(all(not(no_core_net), not(feature = "std")))]
178    pub use self::core::net;
179    #[cfg(feature = "std")]
180    pub use std::net;
181
182    #[cfg(feature = "std")]
183    pub use std::error;
184
185    #[cfg(feature = "std")]
186    pub use std::collections::{HashMap, HashSet};
187    #[cfg(feature = "std")]
188    pub use std::ffi::{OsStr, OsString};
189    #[cfg(feature = "std")]
190    pub use std::hash::{BuildHasher, Hash};
191    #[cfg(feature = "std")]
192    pub use std::io::Write;
193    #[cfg(feature = "std")]
194    pub use std::path::{Path, PathBuf};
195    #[cfg(feature = "std")]
196    pub use std::sync::{Mutex, RwLock};
197    #[cfg(feature = "std")]
198    pub use std::time::{SystemTime, UNIX_EPOCH};
199
200    #[cfg(all(feature = "std", no_target_has_atomic, not(no_std_atomic)))]
201    pub use std::sync::atomic::{
202        AtomicBool, AtomicI16, AtomicI32, AtomicI8, AtomicIsize, AtomicU16, AtomicU32, AtomicU8,
203        AtomicUsize, Ordering,
204    };
205    #[cfg(all(feature = "std", no_target_has_atomic, not(no_std_atomic64)))]
206    pub use std::sync::atomic::{AtomicI64, AtomicU64};
207
208    #[cfg(all(feature = "std", not(no_target_has_atomic)))]
209    pub use std::sync::atomic::Ordering;
210    #[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "8"))]
211    pub use std::sync::atomic::{AtomicBool, AtomicI8, AtomicU8};
212    #[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "16"))]
213    pub use std::sync::atomic::{AtomicI16, AtomicU16};
214    #[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "32"))]
215    pub use std::sync::atomic::{AtomicI32, AtomicU32};
216    #[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "64"))]
217    pub use std::sync::atomic::{AtomicI64, AtomicU64};
218    #[cfg(all(feature = "std", not(no_target_has_atomic), target_has_atomic = "ptr"))]
219    pub use std::sync::atomic::{AtomicIsize, AtomicUsize};
220
221    #[cfg(not(no_core_num_saturating))]
222    pub use self::core::num::Saturating;
223}
224
225// None of this crate's error handling needs the `From::from` error conversion
226// performed implicitly by the `?` operator or the standard library's `try!`
227// macro. This simplified macro gives a 5.5% improvement in compile time
228// compared to standard `try!`, and 9% improvement compared to `?`.
229macro_rules! tri {
230    ($expr:expr) => {
231        match $expr {
232            Ok(val) => val,
233            Err(err) => return Err(err),
234        }
235    };
236}
237
238////////////////////////////////////////////////////////////////////////////////
239
240#[macro_use]
241mod macros;
242
243pub mod de;
244pub mod ser;
245
246mod format;
247
248#[doc(inline)]
249pub use crate::de::{Deserialize, Deserializer};
250#[doc(inline)]
251pub use crate::ser::{Serialize, Serializer};
252
253// Used by generated code. Not public API.
254#[doc(hidden)]
255mod private;
256
257// Used by declarative macro generated code. Not public API.
258#[doc(hidden)]
259pub mod __private {
260    #[doc(hidden)]
261    pub use crate::private::doc;
262    #[doc(hidden)]
263    pub use core::result::Result;
264}
265
266include!(concat!(env!("OUT_DIR"), "/private.rs"));
267
268#[cfg(all(not(feature = "std"), no_core_error))]
269mod std_error;
270
271#[macro_export]
272#[doc(hidden)]
273macro_rules! __require_serde_not_serde_core {
274    () => {
275        ::core::compile_error!(
276            "Serde derive requires a dependency on the serde crate, not serde_core"
277        );
278    };
279}
serde_core/lib.rs

serde_core/
lib.rs
