Struct serde_with::hex::Hex

source ·

pub struct Hex<FORMAT: Format = Lowercase>(_);

Available on crate feature hex only.

Expand description

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 formats::Lowercase and formats::Uppercase. Deserialization always supports lower- and uppercase characters, even mixed in one string.

Example

#[serde_as]
#[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(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(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();