Struct SeedableState 

pub struct SeedableState<'s, const AVALANCHE: bool, const SPONGE: bool, const COMPACT: bool = false, const PROTECTED: bool = false> { /* private fields */ }

A [std::hash::BuildHasher] that initializes a RapidHasher with a user-provided seed and secrets.

SeedableState should rarely be used as providing DoS resistance requires a randomized seed and secrets. Users should instead prefer either:

• crate::inner::GlobalState, which uses a global random seed and secrets initialized once at program start.
• crate::inner::RandomState, which uses a random seed per instance and global random secrets.

The lifetime 's is for the reference to the secrets. When using SeedableState::random or SeedableState::fixed secrets, this lifetime will be 'static.

Example

use std::collections::HashMap;
use std::hash::Hasher;

use rapidhash::quality::SeedableState;

let mut map = HashMap::with_hasher(SeedableState::default());
map.insert(42, "the answer");

Implementations

impl<'s, const AVALANCHE: bool, const SPONGE: bool, const COMPACT: bool, const PROTECTED: bool> SeedableState<'s, AVALANCHE, SPONGE, COMPACT, PROTECTED>

pub fn new(seed: u64) -> Self

Create a new seedable state with a custom seed and automatically generated secrets.

The seed will be pre-mixed to improve entropy. The global secrets are randomly generated once at program start, and then will be re-used for all subsequent calls to this function.

Example

use core::hash::BuildHasher;
use rapidhash::quality::SeedableState;

let state = SeedableState::new(0);

let hash: u64 = state.hash_one(b"hello");
println!("hash: {hash}");

pub fn random() -> Self

Create a new seedable state with a random seed.

This is slower than using crate::inner::RandomState, please use that instead.

pub fn fixed() -> Self

Create a new seedable state with the default seed and secrets.

Using the default secrets does not offer HashDoS resistance, but they will be fixed between different runs of the program.

Please note that fast::RapidHasher and quality::RapidHasher are not guaranteed to produce the same hash outputs between different crate versions, compiler versions, or platforms.

Also see [GlobalState] for a faster zero-sized alternative that uses global secrets that are fixed only for the lifetime of the program.

pub fn custom(seed: u64, secrets: &'s [u64; 7]) -> Self

Create a new seedable state with a custom seed and secrets.

Warning

This constructor uses the provided seed and secrets as the initial state without any pre-mixing or validation. Supplying low-entropy or structured values (e.g., 0, all-zero arrays, counters, timestamps) can produce degenerate hashing (high collision rates or identical outputs).

Requirements

• seed and secrets must not be zero; avoid any all-zero/near-zero state.
• Generate seed and secrets with a cryptographically secure PRNG and treat them as independent for each hasher instance.
• Do not derive successive seeds from predictable data (time, PID/TID, memory addresses) or by simple incrementation.

Recommendation

If you cannot pre-mix the seed yourself, use SeedableState::new instead.

Example (secure generation)

use core::hash::BuildHasher;
use rapidhash::quality::SeedableState;

// randomly generate secrets
let seed: u64 = rand::random();
let secrets: [u64; 7] = rand::random();

// create the state
let state = SeedableState::custom(seed, &secrets);

// hash using the state
let hash: u64 = state.hash_one(b"hello");
println!("hash: {hash}");

pub fn with_seed(seed: u64, secrets: &'s [u64; 7]) -> Self

👎Deprecated since 4.1.0:

Use custom() or new() instead.

Deprecated and renamed to SeedableState::custom.

Trait Implementations

impl<'s, const AVALANCHE: bool, const SPONGE: bool, const COMPACT: bool, const PROTECTED: bool> BuildHasher for SeedableState<'s, AVALANCHE, SPONGE, COMPACT, PROTECTED>

type Hasher = RapidHasher<'s, AVALANCHE, SPONGE, COMPACT, PROTECTED>

Type of the hasher that will be created.

fn build_hasher(&self) -> Self::Hasher

Creates a new hasher.

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

where T: Hash, Self: Sized, Self::Hasher: Hasher,

Calculates the hash of a single value.

impl<'s, const AVALANCHE: bool, const SPONGE: bool, const COMPACT: bool, const PROTECTED: bool> Clone for SeedableState<'s, AVALANCHE, SPONGE, COMPACT, PROTECTED>

fn clone(&self) -> SeedableState<'s, AVALANCHE, SPONGE, COMPACT, PROTECTED>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'s, const AVALANCHE: bool, const SPONGE: bool, const COMPACT: bool, const PROTECTED: bool> Copy for SeedableState<'s, AVALANCHE, SPONGE, COMPACT, PROTECTED>

impl<'s, const AVALANCHE: bool, const SPONGE: bool, const COMPACT: bool, const PROTECTED: bool> Debug for SeedableState<'s, AVALANCHE, SPONGE, COMPACT, PROTECTED>

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

Formats the value using the given formatter.

impl<'s, const AVALANCHE: bool, const SPONGE: bool, const COMPACT: bool, const PROTECTED: bool> Default for SeedableState<'s, AVALANCHE, SPONGE, COMPACT, PROTECTED>

fn default() -> Self

Create a new SeedableState with a random seed. See SeedableState::random for more details.

impl<'s, const AVALANCHE: bool, const SPONGE: bool, const COMPACT: bool, const PROTECTED: bool> Eq for SeedableState<'s, AVALANCHE, SPONGE, COMPACT, PROTECTED>

impl<'s, const AVALANCHE: bool, const SPONGE: bool, const COMPACT: bool, const PROTECTED: bool> PartialEq for SeedableState<'s, AVALANCHE, SPONGE, COMPACT, PROTECTED>

fn eq( &self, other: &SeedableState<'s, AVALANCHE, SPONGE, COMPACT, PROTECTED>, ) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'s, const AVALANCHE: bool, const SPONGE: bool, const COMPACT: bool, const PROTECTED: bool> StructuralPartialEq for SeedableState<'s, AVALANCHE, SPONGE, COMPACT, PROTECTED>