pub struct Digest<const N: usize> { /* private fields */ }Expand description
A fixed-width hash value of N bytes.
N is the output width in bytes. The value is copied around by
value: it is small, and hex output in this workspace is compared
byte-for-byte against specification vectors constantly, so hex
encoding never allocates — to_hex_into
writes into a caller-owned fixed buffer, not a heap string.
Default is the all-zero value and is not a valid hash of
anything: a zeroed buffer is what a failed hash computation tends to
leave behind, and it must not be mistaken for a result.
Ordering is bytewise lexicographic on the raw bytes, matching
[u8; N] itself, so digests can serve as index keys.
Implementations§
Source§impl<const N: usize> Digest<N>
impl<const N: usize> Digest<N>
Sourcepub fn from_bytes(bytes: [u8; N]) -> Self
pub fn from_bytes(bytes: [u8; N]) -> Self
Wraps N bytes. Never fails.
let d = pith_digest::Digest::<2>::from_bytes([0xaa, 0x55]);
assert_eq!(d.as_bytes(), &[0xaa, 0x55]);Sourcepub fn to_hex_into(self, out: &mut [u8]) -> Result<()>
pub fn to_hex_into(self, out: &mut [u8]) -> Result<()>
Writes the lowercase hexadecimal form into out.
out must be exactly HEX_LEN bytes; any other
length is Error::BadValue "hex buffer length". No allocation, no hex crate, and leading
zeroes are kept — the output is exactly 2 * N characters.
The buffer is caller-owned rather than returned because stable
Rust cannot name the type [u8; 2 * N] inside a generic
context (that needs generic_const_exprs, still unstable at the
workspace MSRV); at a concrete N the caller’s array is a plain
constant-sized type.
let d = pith_digest::Digest::<2>::from_bytes([0x00, 0xff]);
let mut hex = [0u8; 4];
d.to_hex_into(&mut hex).unwrap();
assert_eq!(&hex[..], b"00ff");Sourcepub fn from_hex(hex: &[u8]) -> Result<Self>
pub fn from_hex(hex: &[u8]) -> Result<Self>
Parses exactly 2 * N hexadecimal characters, lowercase or
uppercase.
Rejections are named: an odd-length input is
Error::BadValue "hex length is odd", an even input shorter than 2 * N is
Error::Truncated, an input longer
than 2 * N is Error::BadValue
"hex digest length", and any non-hex byte is
Error::BadValue "hex digit".
let d = pith_digest::Digest::<4>::from_hex(b"DeadBeef").unwrap();
assert_eq!(d.as_bytes(), &[0xde, 0xad, 0xbe, 0xef]);
assert_eq!(
pith_digest::Digest::<4>::from_hex(b"odd"),
Err(pith_digest::Error::BadValue("hex length is odd"))
);Sourcepub fn from_slice(data: &[u8]) -> Result<Self>
pub fn from_slice(data: &[u8]) -> Result<Self>
Copies exactly N bytes out of data.
A shorter slice is Error::Truncated
with needed set to N; a longer one is
Error::BadValue "digest length".
Sourcepub fn from_stream<R: Read + ?Sized>(stream: &mut R) -> Result<Self>
pub fn from_stream<R: Read + ?Sized>(stream: &mut R) -> Result<Self>
Reads exactly N bytes out of stream.
Partial reads are followed until the digest is full. A source
that supplies fewer than N bytes before it is exhausted yields
Error::Truncated with found set
to the number of bytes actually supplied. A source with more than
N bytes simply keeps the rest.
let mut src: &[u8] = &[1, 2, 3];
let d = pith_digest::Digest::<3>::from_stream(&mut src).unwrap();
assert_eq!(d.as_bytes(), &[1, 2, 3]);