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
/// Create new conversion adapters from functions
///
/// The macro lets you create a new converter, which is usable for serde's with-attribute and `#[serde_as]`.
/// Its main use case is to write simple converters for types, which are not serializable.
/// Another use-case is to change the serialization behavior if the implemented `Serialize`/`Deserialize` trait is insufficient.
///
/// The macro takes four arguments:
///
/// 1. The name of the converter type.
/// The type can be prefixed with a visibility modifies like `pub` or `pub(crate)`.
/// By default, the type is not marked as public (`pub(self)`).
/// 2. The type `T` we want to extend with custom behavior.
/// 3. A function or macro taking a `&T` and returning a serializable type.
/// 4. A function or macro taking a deserializable type and returning a `Result<T, E>`.
/// The error type `E` must implement `Display`.
///
/// # Example
///
/// In this example, we write custom serialization behavior for a `Rgb` type.
/// We want to serialize it as a `[u8; 3]`.
///
/// ```rust
/// # #[cfg(feature = "macros")] {
/// # use serde::{Serialize, Deserialize};
///
/// #[derive(Clone, Copy, Debug, PartialEq)]
/// struct Rgb {
/// red: u8,
/// green: u8,
/// blue: u8,
/// }
///
/// serde_with::serde_conv!(
/// RgbAsArray,
/// Rgb,
/// |rgb: &Rgb| [rgb.red, rgb.green, rgb.blue],
/// |value: [u8; 3]| -> Result<_, std::convert::Infallible> {
/// Ok(Rgb {
/// red: value[0],
/// green: value[1],
/// blue: value[2],
/// })
/// }
/// );
///
/// //////////////////////////////////////////////////
///
/// // We define some colors to be used later
///
/// let green = Rgb {red: 0, green: 255, blue: 0};
/// let orange = Rgb {red: 255, green: 128, blue: 0};
/// let pink = Rgb {red: 255, green: 0, blue: 255};
///
/// //////////////////////////////////////////////////
///
/// // We can now use the `RgbAsArray` adapter with `serde_as`.
///
/// #[serde_with::serde_as]
/// #[derive(Debug, PartialEq, Serialize, Deserialize)]
/// struct Colors {
/// #[serde_as(as = "RgbAsArray")]
/// one_rgb: Rgb,
/// #[serde_as(as = "Vec<RgbAsArray>")]
/// rgbs_in_vec: Vec<Rgb>,
/// }
///
/// let data = Colors {
/// one_rgb: orange,
/// rgbs_in_vec: vec![green, pink],
/// };
/// let json = serde_json::json!({
/// "one_rgb": [255, 128, 0],
/// "rgbs_in_vec": [
/// [0, 255, 0],
/// [255, 0, 255]
/// ]
/// });
///
/// assert_eq!(json, serde_json::to_value(&data).unwrap());
/// assert_eq!(data, serde_json::from_value(json).unwrap());
///
/// //////////////////////////////////////////////////
///
/// // The types generated by `serde_conv` is also compatible with serde's with attribute
///
/// #[derive(Debug, PartialEq, Serialize, Deserialize)]
/// struct ColorsWith {
/// #[serde(with = "RgbAsArray")]
/// rgb_with: Rgb,
/// }
///
/// let data = ColorsWith {
/// rgb_with: pink,
/// };
/// let json = serde_json::json!({
/// "rgb_with": [255, 0, 255]
/// });
///
/// assert_eq!(json, serde_json::to_value(&data).unwrap());
/// assert_eq!(data, serde_json::from_value(json).unwrap());
/// # }
/// ```