1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
// Copyright (c) The byte-wrapper Contributors
// SPDX-License-Identifier: 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, both 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, both types implement [`JsonSchema`],
//! including automatic opt-in replacement with
//! [typify](https://crates.io/crates/typify) and
//! [progenitor](https://crates.io/crates/progenitor).
//!
//! [CBOR]: https://cbor.io/
//!
//! # Types
//!
//! * [`HexArray<N>`] encodes a fixed-length byte array as a hex
//! string. (Requires the `hex` feature.)
//! * [`Base64Vec`] encodes a variable-length byte vector as a base64
//! string. (Requires the `base64` feature.)
//!
//! # Examples
//!
//! ```
//! # #[cfg(feature = "hex")] {
//! 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:
//!
//! ```
//! # #[cfg(all(feature = "hex", feature = "serde"))] {
//! use byte_wrapper::HexArray;
//! use serde::{Deserialize, Serialize};
//!
//! #[derive(Serialize, Deserialize)]
//! struct Record {
//! checksum: HexArray<32>,
//! }
//! # }
//! ```
//!
//! Using `#[serde(with = "...")]` on an existing byte array:
//!
//! ```
//! # #[cfg(all(feature = "hex", feature = "serde"))] {
//! 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.
//!
//! [`serde-encoded-bytes`]: https://docs.rs/serde-encoded-bytes
//! [`hex-buffer-serde`]: https://docs.rs/hex-buffer-serde
//! [`hexutil`]: https://docs.rs/hexutil
//! [`serde_with`]: https://docs.rs/serde_with
//! [`serde-bytes-repr`]: https://docs.rs/serde-bytes-repr
//! [`serde-human-bytes`]: https://docs.rs/serde-human-bytes
//! [`Display`]: core::fmt::Display
//! [`FromStr`]: core::str::FromStr
//! [`Deref`]: core::ops::Deref
//! [`JsonSchema`]: https://docs.rs/schemars/0.8/schemars/trait.JsonSchema.html
//! [`is_human_readable()`]: https://docs.rs/serde/latest/serde/trait.Serializer.html#method.is_human_readable
//! [`Hex`]: https://docs.rs/serde_with/latest/serde_with/hex/struct.Hex.html
//! [`Base64`]: https://docs.rs/serde_with/latest/serde_with/base64/struct.Base64.html
//!
//! # Features
//!
//! - **`hex`**: enables [`HexArray`]. *Enabled by default.*
//! - **`base64`**: enables [`Base64Vec`] (implies `alloc`).
//! *Enabled by default.*
//! - **`alloc`**: enables `alloc` support (required by `base64`).
//! - **`serde`**: implements `Serialize` and `Deserialize` for
//! enabled types. *Not enabled by default.*
//! - **`schemars08`**: derives `JsonSchema` for enabled types.
//! *Not enabled by default.*
extern crate alloc;
pub use ;
pub use ;