Struct blake3::Hasher

source ·
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

source

pub fn new() -> Self

Construct a new Hasher for the regular hash function.

source

pub fn new_keyed(key: &[u8; 32]) -> Self

Construct a new Hasher for the keyed hash function. See keyed_hash.

source

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.

source

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.

source

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.

source

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.

source

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.

source

pub fn count(&self) -> u64

Return the total number of bytes hashed so far.

source

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());

Trait Implementations§

source§

impl Clone for Hasher

source§

fn clone(&self) -> Hasher

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for Hasher

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl Default for Hasher

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl Write for Hasher

source§

fn write(&mut self, input: &[u8]) -> Result<usize>

This is equivalent to update.

source§

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
1.36.0 · source§

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers. Read more
source§

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)
Determines if this Writer has an efficient write_vectored implementation. Read more
1.0.0 · source§

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer. Read more
source§

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)
Attempts to write multiple buffers into this writer. Read more
1.0.0 · source§

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered. Read more
1.0.0 · source§

fn by_ref(&mut self) -> &mut Self
where Self: Sized,

Creates a “by reference” adapter for this instance of Write. Read more

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> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.