byte-wrapper

License: MIT OR Apache-2.0

Newtype wrappers for byte arrays and vectors with hex and base64 formatting.

This crate provides wrapper types that display byte data in human-readable encodings. HexArray<N> encodes fixed-length byte arrays as hex strings, and Base64Vec encodes variable-length byte vectors as base64 strings.

With the serde feature, this crate’s types implement Serialize and Deserialize, encoding as human-readable strings (hex or base64) in text formats like JSON, and as efficient raw bytes in binary formats like CBOR. You do not have to use the newtypes in your own type definitions; you can refer to them via #[serde(with = "...")] instead.

With the schemars08 feature, this crate’s types implement JsonSchema, including automatic opt-in replacement with typify and progenitor.

Types

HexArray<N> encodes a fixed-length byte array as a hex string. (Requires the hex feature.)
HexSlice encodes a borrowed byte slice as a hex string. (Requires the hex feature.)
HexVec encodes a variable-length byte vector as a hex string. (Requires the hex and alloc features.)
Base64Vec encodes a variable-length byte vector as a base64 string. (Requires the base64 and alloc features.)
Base64Slice encodes a borrowed byte slice as a base64 string. (Requires the base64 feature.)

Examples

use byte_wrapper::HexArray;

let h = HexArray::new([0x01, 0x02, 0xab, 0xff]);
assert_eq!(h.to_string(), "0102abff");

let parsed: HexArray<4> = "0102abff".parse().unwrap();
assert_eq!(parsed, h);

With the serde feature:

use byte_wrapper::HexArray;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct Record {
    checksum: HexArray<32>,
}

Using #[serde(with = "...")] on an existing byte array:

use byte_wrapper::HexArray;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct Record {
    #[serde(with = "HexArray::<32>")]
    checksum: [u8; 32],
}

Alternatives

Several crates solve parts of this problem, often using slightly different approaches from byte-wrapper.

feature	`byte-wrapper`	`serde-human-bytes` 0.1.2	`serde-encoded-bytes` 0.2.1	`serde_with` 3.17.0	`hex-buffer-serde` 0.4.0	`hexutil` 0.1.0	`serde-bytes-repr` 0.3.0
newtype wrappers	yes	yes (hex only)	no	no	no	no	no
`is_human_readable()` switch	yes	yes	yes	no	yes	yes	no
`Display` / `FromStr` / `Deref`	yes	`Deref` only	no	no	no	`Display` / `FromStr` via macro	no
hex encoding	yes	yes	yes	yes	yes	yes	yes
base64 encoding	yes	yes	yes	yes	no	no	yes
`[u8; N]` support	yes	yes	yes	yes	yes	via macros	no
`no_std`	yes	yes	yes	yes	yes	yes	no
`JsonSchema` (schemars)	yes	no	no	yes	no	no	no
`#[serde(with)]` support	yes	yes	yes	yes	yes	no	no

The closest alternatives are:

serde-human-bytes, which provides newtypes with Deref, is_human_readable() switching, and both hex and base64 encoding, but lacks Display / FromStr and JsonSchema support.
serde-encoded-bytes, which provides most of the features of this crate, and is more general in some ways, but doesn’t provide newtype or schemars support.
serde_with, which offers schemars integration but does not check is_human_readable() by default.

Features

hex: enables HexArray and HexSlice, and HexVec together with alloc. Enabled by default.
base64: enables Base64Slice, and Base64Vec together with alloc. Enabled by default.
alloc: enables alloc support (required by Base64Vec and HexVec). Enabled by default.
serde: implements Serialize and Deserialize for enabled types. Not enabled by default.
schemars08: derives JsonSchema for enabled types. Requires std. Not enabled by default.

All features other than schemars08 are compatible with no_std.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.