1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
//! Module for [`SerializeAs`][] implementations
//!
//! The module contains the [`SerializeAs`][] trait and helper code.
//! Additionally, it contains implementations of [`SerializeAs`][] for types defined in the Rust Standard Library or this crate.
//!
//! You can find more details on how to implement this trait for your types in the documentation of the [`SerializeAs`][] trait and details about the usage in the [user guide][].
//!
//! [user guide]: crate::guide
#[macro_use]
mod impls;
// The redirection via macro_rules is necessary to circumvent https://github.com/rust-lang/rust/issues/54727
// which prevents proc macros on non-inline modules
#[rustversion::before(1.51)]
macro_rules! mod_arrays {
() => {
#[path = "legacy_arrays.rs"]
mod arrays;
};
}
#[rustversion::since(1.51)]
macro_rules! mod_arrays {
() => {
#[path = "const_arrays.rs"]
mod arrays;
};
}
mod_arrays!();
use super::*;
/// A **data structure** that can be serialized into any data format supported by Serde, analogue to [`Serialize`].
///
/// The trait is analogue to the [`serde::Serialize`][`Serialize`] trait, with the same meaning of input and output arguments.
/// It can and should the implemented using the same code structure as the [`Serialize`] trait.
/// As such, the same advice for [implementing `Serialize`][impl-serialize] applies here.
///
/// # Differences to [`Serialize`]
///
/// The trait is only required for container-like types or types implementing specific conversion functions.
/// Container-like types are [`Vec`][], [`BTreeMap`][], but also [`Option`][] and [`Box`][].
/// Conversion types serialize into a different serde data type.
/// For example, [`DisplayFromStr`] uses the [`Display`] trait to serialize a String and [`DurationSeconds`] converts a [`Duration`] into either String or integer values.
///
/// This code shows how to implement [`Serialize`] for [`Box`]:
///
/// ```rust,ignore
/// impl<T> Serialize for Box<T>
/// where
/// T: Serialize,
/// {
/// #[inline]
/// fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
/// where
/// S: Serializer,
/// {
/// (**self).serialize(serializer)
/// }
/// }
/// ```
///
/// and this code shows how to do the same using [`SerializeAs`][]:
///
/// ```rust,ignore
/// impl<T, U> SerializeAs<Box<T>> for Box<U>
/// where
/// U: SerializeAs<T>,
/// {
/// fn serialize_as<S>(source: &Box<T>, serializer: S) -> Result<S::Ok, S::Error>
/// where
/// S: Serializer,
/// {
/// SerializeAsWrap::<T, U>::new(source).serialize(serializer)
/// }
/// }
/// ```
///
/// It uses two type parameters, `T` and `U` instead of only one and performs the serialization step using the `SerializeAsWrap` type.
/// The `T` type is the on the Rust side before serialization, whereas the `U` type determines how the value will be serialized.
/// These two changes are usually enough to make a container type implement [`SerializeAs`][].
///
/// [`SerializeAsWrap`] is a piece of glue code which turns [`SerializeAs`] into a serde compatible datatype, by converting all calls to `serialize` into `serialize_as`.
/// This allows us to implement [`SerializeAs`] such that it can be applied recursively throughout the whole data structure.
/// This is mostly important for container types, such as `Vec` or `BTreeMap`.
/// In a `BTreeMap` this allows us to specify two different serialization behaviors, one for key and one for value, using the [`SerializeAs`] trait.
///
/// ## Implementing a converter Type
///
/// This shows a simplified implementation for [`DisplayFromStr`].
///
/// ```rust
/// # #[cfg(all(feature = "macros"))] {
/// # use serde_with::SerializeAs;
/// # use std::fmt::Display;
/// struct DisplayFromStr;
///
/// impl<T> SerializeAs<T> for DisplayFromStr
/// where
/// T: Display,
/// {
/// fn serialize_as<S>(source: &T, serializer: S) -> Result<S::Ok, S::Error>
/// where
/// S: serde::Serializer,
/// {
/// serializer.collect_str(&source)
/// }
/// }
/// #
/// # #[serde_with::serde_as]
/// # #[derive(serde::Serialize)]
/// # struct S (#[serde_as(as = "DisplayFromStr")] bool);
/// #
/// # assert_eq!(r#""false""#, serde_json::to_string(&S(false)).unwrap());
/// # }
/// ```
///
/// [`BTreeMap`]: std::collections::BTreeMap
/// [`Display`]: std::fmt::Display
/// [`Duration`]: std::time::Duration
/// [impl-serialize]: https://serde.rs/impl-serialize.html
pub trait SerializeAs<T: ?Sized> {
/// Serialize this value into the given Serde serializer.
fn serialize_as<S>(source: &T, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer;
}
/// Helper type to implement [`SerializeAs`] for container-like types.
#[derive(Debug)]
pub struct SerializeAsWrap<'a, T: ?Sized, U: ?Sized> {
value: &'a T,
marker: PhantomData<U>,
}
impl<'a, T, U> SerializeAsWrap<'a, T, U>
where
T: ?Sized,
U: ?Sized,
{
/// Create new instance with provided value.
pub fn new(value: &'a T) -> Self {
Self {
value,
marker: PhantomData,
}
}
}
impl<'a, T, U> Serialize for SerializeAsWrap<'a, T, U>
where
T: ?Sized,
U: ?Sized,
U: SerializeAs<T>,
{
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
U::serialize_as(self.value, serializer)
}
}
impl<'a, T, U> From<&'a T> for SerializeAsWrap<'a, T, U>
where
T: ?Sized,
U: ?Sized,
U: SerializeAs<T>,
{
fn from(value: &'a T) -> Self {
Self::new(value)
}
}