serde_with/
hex.rs

Help
1//! De/Serialization of hexadecimal encoded bytes
2//!
3//! This modules is only available when using the `hex` feature of the crate.
4//!
5//! Please check the documentation on the [`Hex`] type for details.
6
7use crate::prelude::*;
8
9/// Serialize bytes as a hex string
10///
11/// The type serializes a sequence of bytes as a hexadecimal string.
12/// It works on any type implementing `AsRef<[u8]>` for serialization and `TryFrom<Vec<u8>>` for deserialization.
13///
14/// The format type parameter specifies if the hex string should use lower- or uppercase characters.
15/// Valid options are the types [`formats::Lowercase`] and [`formats::Uppercase`].
16/// Deserialization always supports lower- and uppercase characters, even mixed in one string.
17///
18/// # Example
19///
20/// ```rust
21/// # #[cfg(feature = "macros")] {
22/// # use serde::{Deserialize, Serialize};
23/// # use serde_json::json;
24/// # use serde_with::serde_as;
25/// #
26/// #[serde_as]
27/// # #[derive(Debug, PartialEq, Eq)]
28/// #[derive(Deserialize, Serialize)]
29/// struct BytesLowercase(
30///     // Equivalent to serde_with::hex::Hex<serde_with::formats::Lowercase>
31///     #[serde_as(as = "serde_with::hex::Hex")]
32///     Vec<u8>
33/// );
34///
35/// #[serde_as]
36/// # #[derive(Debug, PartialEq, Eq)]
37/// #[derive(Deserialize, Serialize)]
38/// struct BytesUppercase(
39///     #[serde_as(as = "serde_with::hex::Hex<serde_with::formats::Uppercase>")]
40///     Vec<u8>
41/// );
42///
43/// let b = b"Hello World!";
44///
45/// // Hex with lowercase letters
46/// assert_eq!(
47///     json!("48656c6c6f20576f726c6421"),
48///     serde_json::to_value(BytesLowercase(b.to_vec())).unwrap()
49/// );
50/// // Hex with uppercase letters
51/// assert_eq!(
52///     json!("48656C6C6F20576F726C6421"),
53///     serde_json::to_value(BytesUppercase(b.to_vec())).unwrap()
54/// );
55///
56/// // Serialization always work from lower- and uppercase characters, even mixed case.
57/// assert_eq!(
58///     BytesLowercase(vec![0x00, 0xaa, 0xbc, 0x99, 0xff]),
59///     serde_json::from_value(json!("00aAbc99FF")).unwrap()
60/// );
61/// assert_eq!(
62///     BytesUppercase(vec![0x00, 0xaa, 0xbc, 0x99, 0xff]),
63///     serde_json::from_value(json!("00aAbc99FF")).unwrap()
64/// );
65///
66/// #[serde_as]
67/// # #[derive(Debug, PartialEq, Eq)]
68/// #[derive(Deserialize, Serialize)]
69/// struct ByteArray(
70///     // Equivalent to serde_with::hex::Hex<serde_with::formats::Lowercase>
71///     #[serde_as(as = "serde_with::hex::Hex")]
72///     [u8; 12]
73/// );
74///
75/// let b = *b"Hello World!";
76///
77/// assert_eq!(
78///     json!("48656c6c6f20576f726c6421"),
79///     serde_json::to_value(ByteArray(b)).unwrap()
80/// );
81///
82/// // Serialization always work from lower- and uppercase characters, even mixed case.
83/// assert_eq!(
84///     ByteArray([0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0xaa, 0xbc, 0x99, 0xff]),
85///     serde_json::from_value(json!("0011223344556677aAbc99FF")).unwrap()
86/// );
87///
88/// // Remember that the conversion may fail. (The following errors are specific to fixed-size arrays)
89/// let error_result: Result<ByteArray, _> = serde_json::from_value(json!("42")); // Too short
90/// error_result.unwrap_err();
91///
92/// let error_result: Result<ByteArray, _> =
93///     serde_json::from_value(json!("000000000000000000000000000000")); // Too long
94/// error_result.unwrap_err();
95/// # }
96/// ```
97pub struct Hex<FORMAT: formats::Format = formats::Lowercase>(PhantomData<FORMAT>);
98
99impl<T> SerializeAs<T> for Hex<formats::Lowercase>
100where
101    T: AsRef<[u8]>,
102{
103    fn serialize_as<S>(source: &T, serializer: S) -> Result<S::Ok, S::Error>
104    where
105        S: Serializer,
106    {
107        serializer.serialize_str(&::hex::encode(source))
108    }
109}
110
111impl<T> SerializeAs<T> for Hex<formats::Uppercase>
112where
113    T: AsRef<[u8]>,
114{
115    fn serialize_as<S>(source: &T, serializer: S) -> Result<S::Ok, S::Error>
116    where
117        S: Serializer,
118    {
119        serializer.serialize_str(&::hex::encode_upper(source))
120    }
121}
122
123impl<'de, T, FORMAT> DeserializeAs<'de, T> for Hex<FORMAT>
124where
125    T: TryFrom<Vec<u8>>,
126    FORMAT: formats::Format,
127{
128    fn deserialize_as<D>(deserializer: D) -> Result<T, D::Error>
129    where
130        D: Deserializer<'de>,
131    {
132        <Cow<'de, str> as Deserialize<'de>>::deserialize(deserializer)
133            .and_then(|s| ::hex::decode(&*s).map_err(DeError::custom))
134            .and_then(|vec: Vec<u8>| {
135                let length = vec.len();
136                vec.try_into().map_err(|_e: T::Error| {
137                    DeError::custom(format_args!(
138                        "Can't convert a Byte Vector of length {length} to the output type."
139                    ))
140                })
141            })
142    }
143}
serde_with/hex.rs

serde_with/
hex.rs
