Crate hex_serde_util

Expand description

hex-serde-util

This crate provides a convenient approach to serializing/deserializing hex numbers with hex string of several formats.

Examples

use hex_serde_util::{HexUsizeUpper, HexUsizeLower, HexUsizePrefixUpper, HexUsizePrefixLower};

let lower_data: HexUsizeLower = 0x1ausize.into();
let upper_data: HexUsizeUpper = 0x1ausize.into();
let prefix_lower_data: HexUsizePrefixLower = 0x1ausize.into();
let prefix_upper_data: HexUsizePrefixUpper = 0x1ausize.into();
assert_eq!(&serde_json::to_string(&lower_data).unwrap(), r#""1a""#);
assert_eq!(&serde_json::to_string(&upper_data).unwrap(), r#""1A""#);
assert_eq!(
    &serde_json::to_string(&prefix_lower_data).unwrap(),
    r#""0x1a""#
);
assert_eq!(
    &serde_json::to_string(&prefix_upper_data).unwrap(),
    r#""0x1A""#
);
assert_eq!(
    serde_json::from_str::<HexUsizeLower>(r#""1a""#).unwrap(),
    0x1ausize.into()
);
assert_eq!(
    serde_json::from_str::<HexUsizeUpper>(r#""1A""#).unwrap(),
    0x1ausize.into()
);
assert_eq!(
    serde_json::from_str::<HexUsizePrefixLower>(r#""0x1a""#).unwrap(),
    0x1ausize.into()
);
assert_eq!(
    serde_json::from_str::<HexUsizePrefixUpper>(r#""0x1A""#).unwrap(),
    0x1ausize.into()
);

In summary, this crate provides a way to serialize/deserialize hex number from/to hex string with:

lower case without 0x prefix (1a for example)
upper case without 0x prefix (1A for example)
lower case with 0x prefix (0x1a for example)
upper case with 0x prefix (0x1A for example)

Generally, a project may only use one format of hex string, so just use an alias when using this crate in your project for convenience:

use hex_serde_util::HexUsizePrefixUpper as Hex;
use serde::Deserialize;

#[derive(Deserialize)]
struct AnalysisInfo {
    base_addr: Hex,
}

Necessity

serde provides many attributes for customizing serialization/deserialization, such as

[serde(serialize_with = "path")]
[serde(deserialize_with = "path")]
[serde(with = "module")]

These attributes can be used to work with hex strings, but there are some disadvantages:

Boilerplate needed

You need to write some boilerplates in your project to use these attributes.
Can’t use these attributes when in a wrapper such as Option

It is a common practice to use Option to wrap some fields if these type may be null when processing. However, if this field is designed to be a hex string, you have to write additional boilerplates for just serializing/deserializing those fields.

This crate handles these problems.

Usages

Just as shown above, users can just use types provided by this crate when serialize/deserialize hex strings with hex numbers. Moreover, these types also implements some convenient traits:

Deref, DerefMut

After deserializing, users can just use these traits to get the real number:

use hex_serde_util::HexUsizePrefixUpper as Hex;
let hex_wrapper = serde_json::from_str::<Hex>(r#""0x1A""#).unwrap();
let value = *hex_wrapper; // `value` is 26 with type `usize`
assert_eq!(value, 26);

From, Into

Before serializing, users can just use .into to construct corresponding types.

Display

When printing those structs with println!("{}");, the field is displayed as if it is a hex string:

use hex_serde_util::HexUsizePrefixUpper as Hex;
let hex_wrapper: Hex = 0x1a.into();
let hex_str = hex_wrapper.to_string();
assert_eq!(&hex_str, "0x1A");