Struct RandomState

pub struct RandomState {
    pub(crate) k0: u64,
    pub(crate) k1: u64,
    pub(crate) k2: u64,
    pub(crate) k3: u64,
}

Provides a Hasher factory. This is typically used (e.g. by HashMap) to create [AHasher]s in order to hash the keys of the map. See build_hasher below.

There are multiple constructors each is documented in more detail below:

Constructor	Dynamically random?	Seed
new	Each instance unique	[RandomSource]
generate_with	Each instance unique	u64 x 4 + [RandomSource]
with_seed	Fixed per process	u64 + static random number
with_seeds	Fixed	u64 x 4

Fields

k0: u64

k1: u64

k2: u64

k3: u64

Implementations

impl RandomState

pub fn new() -> RandomState

Create a new RandomState BuildHasher using random keys.

Each instance will have a unique set of keys derived from [RandomSource].

pub fn generate_with(k0: u64, k1: u64, k2: u64, k3: u64) -> RandomState

Create a new RandomState BuildHasher based on the provided seeds, but in such a way that each time it is called the resulting state will be different and of high quality. This allows fixed constant or poor quality seeds to be provided without the problem of different BuildHashers being identical or weak.

This is done via permuting the provided values with the value of a static counter and memory address. (This makes this method somewhat more expensive than with_seeds below which does not do this).

The provided values (k0-k3) do not need to be of high quality but they should not all be the same value.

pub fn with_seed(key: usize) -> RandomState

Build a RandomState from a single key. The provided key does not need to be of high quality, but all RandomStates created from the same key will produce identical hashers. (In contrast to generate_with above)

This allows for explicitly setting the seed to be used.

Note: This method does not require the provided seed to be strong.

pub const fn with_seeds(k0: u64, k1: u64, k2: u64, k3: u64) -> RandomState

Allows for explicitly setting the seeds to used. All RandomStates created with the same set of keys key will produce identical hashers. (In contrast to generate_with above)

Note: If DOS resistance is desired one of these should be a decent quality random number. If 4 high quality random number are not cheaply available this method is robust against 0s being passed for one or more of the parameters or the same value being passed for more than one parameter. It is recommended to pass numbers in order from highest to lowest quality (if there is any difference).

pub fn hash_one<T>(&self, x: T) -> u64

where T: Hash, RandomState: Sized,

Calculates the hash of a single value. This provides a more convenient (and faster) way to obtain a hash: For example:

Examples

    use std::hash::BuildHasher;
    use ahash::RandomState;

    let hash_builder = RandomState::new();
    let hash = hash_builder.hash_one("Some Data");

This is similar to:

Examples

    use std::hash::{BuildHasher, Hash, Hasher};
    use ahash::RandomState;

    let hash_builder = RandomState::new();
    let mut hasher = hash_builder.build_hasher();
    "Some Data".hash(&mut hasher);
    let hash = hasher.finish();

(Note that these two ways to get a hash may not produce the same value for the same data)

This is intended as a convenience for code which consumes hashes, such as the implementation of a hash table or in unit tests that check whether a custom Hash implementation behaves as expected.

This must not be used in any code which creates hashes, such as in an implementation of Hash. The way to create a combined hash of multiple values is to call Hash::hash multiple times using the same Hasher, not to call this method repeatedly and combine the results.

Trait Implementations

impl BuildHasher for RandomState

fn build_hasher(&self) -> AHasher

Constructs a new [AHasher] with keys based on this RandomState object. This means that two different RandomStates will will generate [AHasher]s that will return different hashcodes, but Hashers created from the same BuildHasher will generate the same hashes for the same input data.

Examples

        use ahash::{AHasher, RandomState};
        use std::hash::{Hasher, BuildHasher};
    
        let build_hasher = RandomState::new();
        let mut hasher_1 = build_hasher.build_hasher();
        let mut hasher_2 = build_hasher.build_hasher();
    
        hasher_1.write_u32(1234);
        hasher_2.write_u32(1234);
    
        assert_eq!(hasher_1.finish(), hasher_2.finish());
    
        let other_build_hasher = RandomState::new();
        let mut different_hasher = other_build_hasher.build_hasher();
        different_hasher.write_u32(1234);
        assert_ne!(different_hasher.finish(), hasher_1.finish());

fn hash_one<T>(&self, x: T) -> u64

where T: Hash,

Calculates the hash of a single value. This provides a more convenient (and faster) way to obtain a hash: For example:

Examples

    use std::hash::BuildHasher;
    use ahash::RandomState;

    let hash_builder = RandomState::new();
    let hash = hash_builder.hash_one("Some Data");

This is similar to:

Examples

    use std::hash::{BuildHasher, Hash, Hasher};
    use ahash::RandomState;

    let hash_builder = RandomState::new();
    let mut hasher = hash_builder.build_hasher();
    "Some Data".hash(&mut hasher);
    let hash = hasher.finish();

(Note that these two ways to get a hash may not produce the same value for the same data)

This is intended as a convenience for code which consumes hashes, such as the implementation of a hash table or in unit tests that check whether a custom Hash implementation behaves as expected.

This must not be used in any code which creates hashes, such as in an implementation of Hash. The way to create a combined hash of multiple values is to call Hash::hash multiple times using the same Hasher, not to call this method repeatedly and combine the results.

type Hasher = AHasher

Type of the hasher that will be created.

impl Clone for RandomState

fn clone(&self) -> RandomState

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for RandomState

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

Formats the value using the given formatter.

impl Default for RandomState

Creates an instance of RandomState using keys obtained from the random number generator. Each instance created in this way will have a unique set of keys. (But the resulting instance can be used to create many hashers each or which will have the same keys.)

This is the same as RandomState::new()

NOTE: For safety this trait impl is only available available if either of the flags runtime-rng (on by default) or compile-time-rng are enabled. This is to prevent weakly keyed maps from being accidentally created. Instead one of constructors for RandomState must be used.

fn default() -> RandomState

Returns the “default value” for a type.