blockscout_display_bytes/
serde_as.rs

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

blockscout_display_bytes/
serde_as.rs
