pub struct Hasher { /* private fields */ }
Expand description
An incremental hash state that can accept any number of writes.
The rayon
and mmap
Cargo features enable additional methods on this
type related to multithreading and memory-mapped IO.
When the traits-preview
Cargo feature is enabled, this type implements
several commonly used traits from the
digest
crate. However, those
traits aren’t stable, and they’re expected to change in incompatible ways
before that crate reaches 1.0. For that reason, this crate makes no SemVer
guarantees for this feature, and callers who use it should expect breaking
changes between patch versions.
§Examples
// Hash an input incrementally.
let mut hasher = blake3::Hasher::new();
hasher.update(b"foo");
hasher.update(b"bar");
hasher.update(b"baz");
assert_eq!(hasher.finalize(), blake3::hash(b"foobarbaz"));
// Extended output. OutputReader also implements Read and Seek.
let mut output = [0; 1000];
let mut output_reader = hasher.finalize_xof();
output_reader.fill(&mut output);
assert_eq!(&output[..32], blake3::hash(b"foobarbaz").as_bytes());
Implementations§
source§impl Hasher
impl Hasher
sourcepub fn new_keyed(key: &[u8; 32]) -> Self
pub fn new_keyed(key: &[u8; 32]) -> Self
Construct a new Hasher
for the keyed hash function. See
keyed_hash
.
sourcepub fn new_derive_key(context: &str) -> Self
pub fn new_derive_key(context: &str) -> Self
Construct a new Hasher
for the key derivation function. See
derive_key
. The context string should be hardcoded, globally
unique, and application-specific.
sourcepub fn reset(&mut self) -> &mut Self
pub fn reset(&mut self) -> &mut Self
Reset the Hasher
to its initial state.
This is functionally the same as overwriting the Hasher
with a new
one, using the same key or context string if any.
sourcepub fn update(&mut self, input: &[u8]) -> &mut Self
pub fn update(&mut self, input: &[u8]) -> &mut Self
Add input bytes to the hash state. You can call this any number of times.
This method is always single-threaded. For multithreading support, see
update_rayon
(enabled with the rayon
Cargo feature).
Note that the degree of SIMD parallelism that update
can use is limited by the size of
this input buffer. See update_reader
.
sourcepub fn finalize(&self) -> Hash
pub fn finalize(&self) -> Hash
Finalize the hash state and return the Hash
of
the input.
This method is idempotent. Calling it twice will give the same result. You can also add more input and finalize again.
sourcepub fn finalize_xof(&self) -> OutputReader ⓘ
pub fn finalize_xof(&self) -> OutputReader ⓘ
Finalize the hash state and return an OutputReader
, which can
supply any number of output bytes.
This method is idempotent. Calling it twice will give the same result. You can also add more input and finalize again.
sourcepub fn update_reader(&mut self, reader: impl Read) -> Result<&mut Self>
pub fn update_reader(&mut self, reader: impl Read) -> Result<&mut Self>
As update
, but reading from a
std::io::Read
implementation.
Hasher
implements
std::io::Write
, so it’s possible to
use std::io::copy
to update a Hasher
from any reader. Unfortunately, this standard approach can limit performance, because
copy
currently uses an internal 8 KiB buffer that isn’t big enough to take advantage of
all SIMD instruction sets. (In particular, AVX-512
needs a 16 KiB buffer.) update_reader
avoids this performance problem and is slightly
more convenient.
The internal buffer size this method uses may change at any time, and it may be different for different targets. The only guarantee is that it will be large enough for all of this crate’s SIMD implementations on the current platform.
The most common implementer of
std::io::Read
might be
std::fs::File
, but note that memory
mapping can be faster than this method for hashing large files. See
update_mmap
and update_mmap_rayon
,
which require the mmap
and (for the latter) rayon
Cargo features.
This method requires the std
Cargo feature, which is enabled by default.
§Example
// Hash standard input.
let mut hasher = blake3::Hasher::new();
hasher.update_reader(std::io::stdin().lock())?;
println!("{}", hasher.finalize());
sourcepub fn update_rayon(&mut self, input: &[u8]) -> &mut Self
pub fn update_rayon(&mut self, input: &[u8]) -> &mut Self
As update
, but using Rayon-based multithreading
internally.
This method is gated by the rayon
Cargo feature, which is disabled by
default but enabled on docs.rs.
To get any performance benefit from multithreading, the input buffer
needs to be large. As a rule of thumb on x86_64, update_rayon
is
slower than update
for inputs under 128 KiB. That threshold varies
quite a lot across different processors, and it’s important to benchmark
your specific use case. See also the performance warning associated with
update_mmap_rayon
.
If you already have a large buffer in memory, and you want to hash it
with multiple threads, this method is a good option. However, reading a
file into memory just to call this method can be a performance mistake,
both because it requires lots of memory and because single-threaded
reads can be slow. For hashing whole files, see
update_mmap_rayon
, which is gated by both
the rayon
and mmap
Cargo features.
Trait Implementations§
source§impl BlockSizeUser for Hasher
impl BlockSizeUser for Hasher
source§impl ExtendableOutput for Hasher
impl ExtendableOutput for Hasher
source§type Reader = OutputReader
type Reader = OutputReader
source§fn finalize_xof(self) -> Self::Reader
fn finalize_xof(self) -> Self::Reader
source§fn finalize_xof_into(self, out: &mut [u8])
fn finalize_xof_into(self, out: &mut [u8])
out
.source§impl ExtendableOutputReset for Hasher
impl ExtendableOutputReset for Hasher
source§fn finalize_xof_reset(&mut self) -> Self::Reader
fn finalize_xof_reset(&mut self) -> Self::Reader
source§fn finalize_xof_reset_into(&mut self, out: &mut [u8])
fn finalize_xof_reset_into(&mut self, out: &mut [u8])
out
, and reset the hasher state.source§impl FixedOutput for Hasher
impl FixedOutput for Hasher
source§fn finalize_into(self, out: &mut GenericArray<u8, Self::OutputSize>)
fn finalize_into(self, out: &mut GenericArray<u8, Self::OutputSize>)
source§fn finalize_fixed(self) -> GenericArray<u8, Self::OutputSize>
fn finalize_fixed(self) -> GenericArray<u8, Self::OutputSize>
source§impl FixedOutputReset for Hasher
impl FixedOutputReset for Hasher
source§fn finalize_into_reset(&mut self, out: &mut GenericArray<u8, Self::OutputSize>)
fn finalize_into_reset(&mut self, out: &mut GenericArray<u8, Self::OutputSize>)
source§fn finalize_fixed_reset(&mut self) -> GenericArray<u8, Self::OutputSize>
fn finalize_fixed_reset(&mut self) -> GenericArray<u8, Self::OutputSize>
source§impl KeyInit for Hasher
impl KeyInit for Hasher
source§fn new_from_slice(key: &[u8]) -> Result<Self, InvalidLength>
fn new_from_slice(key: &[u8]) -> Result<Self, InvalidLength>
source§impl KeySizeUser for Hasher
impl KeySizeUser for Hasher
source§impl OutputSizeUser for Hasher
impl OutputSizeUser for Hasher
source§impl Write for Hasher
impl Write for Hasher
source§fn flush(&mut self) -> Result<()>
fn flush(&mut self) -> Result<()>
source§fn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)1.0.0 · source§fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
source§fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)impl HashMarker for Hasher
impl MacMarker for Hasher
Auto Trait Implementations§
impl Freeze for Hasher
impl RefUnwindSafe for Hasher
impl Send for Hasher
impl Sync for Hasher
impl Unpin for Hasher
impl UnwindSafe for Hasher
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)source§impl<D> Digest for D
impl<D> Digest for D
source§fn new_with_prefix(data: impl AsRef<[u8]>) -> Dwhere
D: Default,
fn new_with_prefix(data: impl AsRef<[u8]>) -> Dwhere
D: Default,
source§fn chain_update(self, data: impl AsRef<[u8]>) -> D
fn chain_update(self, data: impl AsRef<[u8]>) -> D
source§fn finalize(self) -> GenericArray<u8, <D as OutputSizeUser>::OutputSize>
fn finalize(self) -> GenericArray<u8, <D as OutputSizeUser>::OutputSize>
source§fn finalize_into(
self,
out: &mut GenericArray<u8, <D as OutputSizeUser>::OutputSize>,
)
fn finalize_into( self, out: &mut GenericArray<u8, <D as OutputSizeUser>::OutputSize>, )
source§fn finalize_reset(
&mut self,
) -> GenericArray<u8, <D as OutputSizeUser>::OutputSize>where
D: FixedOutputReset,
fn finalize_reset(
&mut self,
) -> GenericArray<u8, <D as OutputSizeUser>::OutputSize>where
D: FixedOutputReset,
source§fn finalize_into_reset(
&mut self,
out: &mut GenericArray<u8, <D as OutputSizeUser>::OutputSize>,
)where
D: FixedOutputReset,
fn finalize_into_reset(
&mut self,
out: &mut GenericArray<u8, <D as OutputSizeUser>::OutputSize>,
)where
D: FixedOutputReset,
source§fn output_size() -> usize
fn output_size() -> usize
source§fn digest(
data: impl AsRef<[u8]>,
) -> GenericArray<u8, <D as OutputSizeUser>::OutputSize>
fn digest( data: impl AsRef<[u8]>, ) -> GenericArray<u8, <D as OutputSizeUser>::OutputSize>
data
.source§impl<D> DynDigest for D
impl<D> DynDigest for D
source§fn finalize_reset(&mut self) -> Box<[u8]>
fn finalize_reset(&mut self) -> Box<[u8]>
source§fn finalize_into(self, buf: &mut [u8]) -> Result<(), InvalidBufferSize>
fn finalize_into(self, buf: &mut [u8]) -> Result<(), InvalidBufferSize>
source§fn finalize_into_reset(
&mut self,
buf: &mut [u8],
) -> Result<(), InvalidBufferSize>
fn finalize_into_reset( &mut self, buf: &mut [u8], ) -> Result<(), InvalidBufferSize>
source§fn output_size(&self) -> usize
fn output_size(&self) -> usize
source§impl<T> Mac for T
impl<T> Mac for T
source§fn new(key: &GenericArray<u8, <T as KeySizeUser>::KeySize>) -> Twhere
T: KeyInit,
fn new(key: &GenericArray<u8, <T as KeySizeUser>::KeySize>) -> Twhere
T: KeyInit,
source§fn new_from_slice(key: &[u8]) -> Result<T, InvalidLength>where
T: KeyInit,
fn new_from_slice(key: &[u8]) -> Result<T, InvalidLength>where
T: KeyInit,
source§fn chain_update(self, data: impl AsRef<[u8]>) -> T
fn chain_update(self, data: impl AsRef<[u8]>) -> T
source§fn finalize_reset(&mut self) -> CtOutput<T>where
T: FixedOutputReset,
fn finalize_reset(&mut self) -> CtOutput<T>where
T: FixedOutputReset,
source§fn verify(
self,
tag: &GenericArray<u8, <T as OutputSizeUser>::OutputSize>,
) -> Result<(), MacError>
fn verify( self, tag: &GenericArray<u8, <T as OutputSizeUser>::OutputSize>, ) -> Result<(), MacError>
source§fn verify_reset(
&mut self,
tag: &GenericArray<u8, <T as OutputSizeUser>::OutputSize>,
) -> Result<(), MacError>where
T: FixedOutputReset,
fn verify_reset(
&mut self,
tag: &GenericArray<u8, <T as OutputSizeUser>::OutputSize>,
) -> Result<(), MacError>where
T: FixedOutputReset,
Mac
instance.