Trait Hasher

trait Hasher

A trait for hashing an arbitrary stream of bytes.

Instances of Hasher usually represent state that is changed while hashing data.

Hasher provides a fairly basic interface for retrieving the generated hash (with finish), and writing integers as well as slices of bytes into an instance (with write and write_u8 etc.). Most of the time, Hasher instances are used in conjunction with the Hash trait.

This trait provides no guarantees about how the various write_* methods are defined and implementations of Hash should not assume that they work one way or another. You cannot assume, for example, that a write_u32 call is equivalent to four calls of write_u8. Nor can you assume that adjacent write calls are merged, so it's possible, for example, that

# fn foo(hasher: &mut impl std::hash::Hasher) {
hasher.write(&[1, 2]);
hasher.write(&[3, 4, 5, 6]);
# }

and

# fn foo(hasher: &mut impl std::hash::Hasher) {
hasher.write(&[1, 2, 3, 4]);
hasher.write(&[5, 6]);
# }

end up producing different hashes.

Thus to produce the same hash value, Hash implementations must ensure for equivalent items that exactly the same sequence of calls is made -- the same methods with the same parameters in the same order.

Examples

use std::hash::{DefaultHasher, Hasher};

let mut hasher = DefaultHasher::new();

hasher.write_u32(1989);
hasher.write_u8(11);
hasher.write_u8(9);
hasher.write(b"Huh?");

println!("Hash is {:x}!", hasher.finish());

Required Methods

fn finish(self: &Self) -> u64

Returns the hash value for the values written so far.

Despite its name, the method does not reset the hasher’s internal state. Additional writes will continue from the current value. If you need to start a fresh hash value, you will have to create a new hasher.

Examples

use std::hash::{DefaultHasher, Hasher};

let mut hasher = DefaultHasher::new();
hasher.write(b"Cool!");

println!("Hash is {:x}!", hasher.finish());

fn write(self: &mut Self, bytes: &[u8])

Writes some data into this Hasher.

Examples

use std::hash::{DefaultHasher, Hasher};

let mut hasher = DefaultHasher::new();
let data = [0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef];

hasher.write(&data);

println!("Hash is {:x}!", hasher.finish());

Note to Implementers

You generally should not do length-prefixing as part of implementing this method. It's up to the Hash implementation to call Hasher::write_length_prefix before sequences that need it.

Provided Methods

fn write_u8(self: &mut Self, i: u8)

Writes a single u8 into this hasher.

fn write_u16(self: &mut Self, i: u16)

Writes a single u16 into this hasher.

fn write_u32(self: &mut Self, i: u32)

Writes a single u32 into this hasher.

fn write_u64(self: &mut Self, i: u64)

Writes a single u64 into this hasher.

fn write_u128(self: &mut Self, i: u128)

Writes a single u128 into this hasher.

fn write_usize(self: &mut Self, i: usize)

Writes a single usize into this hasher.

fn write_i8(self: &mut Self, i: i8)

Writes a single i8 into this hasher.

fn write_i16(self: &mut Self, i: i16)

Writes a single i16 into this hasher.

fn write_i32(self: &mut Self, i: i32)

Writes a single i32 into this hasher.

fn write_i64(self: &mut Self, i: i64)

Writes a single i64 into this hasher.

fn write_i128(self: &mut Self, i: i128)

Writes a single i128 into this hasher.

fn write_isize(self: &mut Self, i: isize)

Writes a single isize into this hasher.

fn write_length_prefix(self: &mut Self, len: usize)

Writes a length prefix into this hasher, as part of being prefix-free.

If you're implementing Hash for a custom collection, call this before writing its contents to this Hasher. That way (collection![1, 2, 3], collection![4, 5]) and (collection![1, 2], collection![3, 4, 5]) will provide different sequences of values to the Hasher

The impl<T> Hash for [T] includes a call to this method, so if you're hashing a slice (or array or vector) via its Hash::hash method, you should not call this yourself.

This method is only for providing domain separation. If you want to hash a usize that represents part of the data, then it's important that you pass it to Hasher::write_usize instead of to this method.

Examples

#![feature(hasher_prefixfree_extras)]
# // Stubs to make the `impl` below pass the compiler
# #![allow(non_local_definitions)]
# struct MyCollection<T>(Option<T>);
# impl<T> MyCollection<T> {
#     fn len(&self) -> usize { todo!() }
# }
# impl<'a, T> IntoIterator for &'a MyCollection<T> {
#     type Item = T;
#     type IntoIter = std::iter::Empty<T>;
#     fn into_iter(self) -> Self::IntoIter { todo!() }
# }

use std::hash::{Hash, Hasher};
impl<T: Hash> Hash for MyCollection<T> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        state.write_length_prefix(self.len());
        for elt in self {
            elt.hash(state);
        }
    }
}

Note to Implementers

If you've decided that your Hasher is willing to be susceptible to Hash-DoS attacks, then you might consider skipping hashing some or all of the len provided in the name of increased performance.

fn write_str(self: &mut Self, s: &str)

Writes a single str into this hasher.

If you're implementing Hash, you generally do not need to call this, as the impl Hash for str does, so you should prefer that instead.

This includes the domain separator for prefix-freedom, so you should not call Self::write_length_prefix before calling this.

Note to Implementers

There are at least two reasonable default ways to implement this. Which one will be the default is not yet decided, so for now you probably want to override it specifically.

The general answer

It's always correct to implement this with a length prefix:

# #![feature(hasher_prefixfree_extras)]
# struct Foo;
# impl std::hash::Hasher for Foo {
# fn finish(&self) -> u64 { unimplemented!() }
# fn write(&mut self, _bytes: &[u8]) { unimplemented!() }
fn write_str(&mut self, s: &str) {
    self.write_length_prefix(s.len());
    self.write(s.as_bytes());
}
# }

And, if your Hasher works in usize chunks, this is likely a very efficient way to do it, as anything more complicated may well end up slower than just running the round with the length.

If your Hasher works byte-wise

One nice thing about str being UTF-8 is that the b'\xFF' byte never happens. That means that you can append that to the byte stream being hashed and maintain prefix-freedom:

# #![feature(hasher_prefixfree_extras)]
# struct Foo;
# impl std::hash::Hasher for Foo {
# fn finish(&self) -> u64 { unimplemented!() }
# fn write(&mut self, _bytes: &[u8]) { unimplemented!() }
fn write_str(&mut self, s: &str) {
    self.write(s.as_bytes());
    self.write_u8(0xff);
}
# }

This does require that your implementation not add extra padding, and thus generally requires that you maintain a buffer, running a round only once that buffer is full (or finish is called).

That's because if write pads data out to a fixed chunk size, it's likely that it does it in such a way that "a" and "a\x00" would end up hashing the same sequence of things, introducing conflicts.

Implementors