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
|
//! De/Serialization of hexadecimal encoded bytes
//!
//! This modules is only available when using the `hex` feature of the crate.
//!
//! Please check the documentation on the [`Hex`] type for details.
use crate::{
de::DeserializeAs,
formats::{Format, Lowercase, Uppercase},
ser::SerializeAs,
};
use alloc::{borrow::Cow, format, vec::Vec};
use core::{
convert::{TryFrom, TryInto},
marker::PhantomData,
};
use serde::{de::Error, Deserialize, Deserializer, Serializer};
/// Serialize bytes as a hex string
///
/// The type serializes a sequence of bytes as a hexadecimal string.
/// It works on any type implementing `AsRef<[u8]>` for serialization and `TryFrom<Vec<u8>>` for deserialization.
///
/// The format type parameter specifies if the hex string should use lower- or uppercase characters.
/// Valid options are the types [`Lowercase`] and [`Uppercase`].
/// Deserialization always supports lower- and uppercase characters, even mixed in one string.
///
/// # Example
///
/// ```rust
/// # #[cfg(feature = "macros")] {
/// # use serde::{Deserialize, Serialize};
/// # use serde_json::json;
/// # use serde_with::serde_as;
/// #
/// #[serde_as]
/// # #[derive(Debug, PartialEq, Eq)]
/// #[derive(Deserialize, Serialize)]
/// struct BytesLowercase(
/// // Equivalent to serde_with::hex::Hex<serde_with::formats::Lowercase>
/// #[serde_as(as = "serde_with::hex::Hex")]
/// Vec<u8>
/// );
///
/// #[serde_as]
/// # #[derive(Debug, PartialEq, Eq)]
/// #[derive(Deserialize, Serialize)]
/// struct BytesUppercase(
/// #[serde_as(as = "serde_with::hex::Hex<serde_with::formats::Uppercase>")]
/// Vec<u8>
/// );
///
/// let b = b"Hello World!";
///
/// // Hex with lowercase letters
/// assert_eq!(
/// json!("48656c6c6f20576f726c6421"),
/// serde_json::to_value(BytesLowercase(b.to_vec())).unwrap()
/// );
/// // Hex with uppercase letters
/// assert_eq!(
/// json!("48656C6C6F20576F726C6421"),
/// serde_json::to_value(BytesUppercase(b.to_vec())).unwrap()
/// );
///
/// // Serialization always work from lower- and uppercase characters, even mixed case.
/// assert_eq!(
/// BytesLowercase(vec![0x00, 0xaa, 0xbc, 0x99, 0xff]),
/// serde_json::from_value(json!("00aAbc99FF")).unwrap()
/// );
/// assert_eq!(
/// BytesUppercase(vec![0x00, 0xaa, 0xbc, 0x99, 0xff]),
/// serde_json::from_value(json!("00aAbc99FF")).unwrap()
/// );
///
/// #[serde_as]
/// # #[derive(Debug, PartialEq, Eq)]
/// #[derive(Deserialize, Serialize)]
/// struct ByteArray(
/// // Equivalent to serde_with::hex::Hex<serde_with::formats::Lowercase>
/// #[serde_as(as = "serde_with::hex::Hex")]
/// [u8; 12]
/// );
///
/// let b = b"Hello World!";
///
/// assert_eq!(
/// json!("48656c6c6f20576f726c6421"),
/// serde_json::to_value(ByteArray(b.clone())).unwrap()
/// );
///
/// // Serialization always work from lower- and uppercase characters, even mixed case.
/// assert_eq!(
/// ByteArray([0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0xaa, 0xbc, 0x99, 0xff]),
/// serde_json::from_value(json!("0011223344556677aAbc99FF")).unwrap()
/// );
///
/// // Remember that the conversion may fail. (The following errors are specific to fixed-size arrays)
/// let error_result: Result<ByteArray, _> = serde_json::from_value(json!("42")); // Too short
/// error_result.unwrap_err();
///
/// let error_result: Result<ByteArray, _> =
/// serde_json::from_value(json!("000000000000000000000000000000")); // Too long
/// error_result.unwrap_err();
/// # }
/// ```
#[derive(Copy, Clone, Debug, Default)]
pub struct Hex<FORMAT: Format = Lowercase>(PhantomData<FORMAT>);
impl<T> SerializeAs<T> for Hex<Lowercase>
where
T: AsRef<[u8]>,
{
fn serialize_as<S>(source: &T, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.serialize_str(&hex::encode(source))
}
}
impl<T> SerializeAs<T> for Hex<Uppercase>
where
T: AsRef<[u8]>,
{
fn serialize_as<S>(source: &T, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.serialize_str(&hex::encode_upper(source))
}
}
impl<'de, T, FORMAT> DeserializeAs<'de, T> for Hex<FORMAT>
where
T: TryFrom<Vec<u8>>,
FORMAT: Format,
{
fn deserialize_as<D>(deserializer: D) -> Result<T, D::Error>
where
D: Deserializer<'de>,
{
<Cow<'de, str> as Deserialize<'de>>::deserialize(deserializer)
.and_then(|s| hex::decode(&*s).map_err(Error::custom))
.and_then(|vec: Vec<u8>| {
let length = vec.len();
vec.try_into().map_err(|_e: T::Error| {
Error::custom(format!(
"Can't convert a Byte Vector of length {} to the output type.",
length
))
})
})
}
}
|
