Struct Params

pub struct Params(/* private fields */);

A Params stores a set of hashing parameters that define a specific UMASH function.

By default, each Params is generated independently with unique pseudorandom parameters. Call Params::derive to generate repeatable parameters that will compute the same hash and fingerprint values across processes, programs, architectures, and UMASH versions.

While the derivation algorithm and the UMASH hash functions are fully defined independently of the platform, the std::hash::Hash functions may not be. When computing hash or fingerprint values that will be persisted or compared in different processes (or programs, or machines), it is safest to directly pass &[u8] bytes to Hasher::write or Fingerprinter::write or to their std::io::Write implementation.

This struct consists of 38 u64 parameters, so although Params do not own any resource, they should be passed by reference rather than copied, as much as possible.

Params implement std::hash::BuildHasher: pass a &'static Params to, e.g., std::collections::HashMap::with_hasher, and the hash values will be computed with as the primary UMASH value for these Params, for seed = 0.

Implementations

impl Params

pub fn new() -> Self

Returns a new pseudo-unique Params value.

pub fn derive(bits: u64, key: &[u8]) -> Self

Returns a fresh set of Params derived deterministically from bits and the first 32 bytes in key.

The UMASH function defined by the resulting Params will remain the same for all versions of UMASH and umash-rs.

Examples found in repository

examples/umash.rs (line 11)

fn main() {
    let args: Vec<String> = std::env::args().collect();
    let input = args
        .get(1)
        .cloned()
        .unwrap_or_else(|| "default input".to_string());
    let seed = 42u64;
    let my_params = umash::Params::derive(0, "hello example.c".as_bytes());
    let fprint = my_params
        .fingerprinter(seed)
        .write(input.as_bytes())
        .digest();

    println!("Input: {}", input);
    println!("Fingerprint: {:x}, {:x}", fprint.hash[0], fprint.hash[1]);
    println!(
        "Hash 0: {:x}",
        my_params.hasher(seed).write(input.as_bytes()).digest()
    );
    println!(
        "Hash 1: {:x}",
        my_params
            .secondary_hasher(seed)
            .write(input.as_bytes())
            .digest()
    );

    let mut h: umash::Hasher = (&my_params).into();
    h.write(input.as_bytes());
    println!("Hash: {:x}", h.finish());
}

pub fn hasher(&self, seed: u64) -> Hasher<'_>

Returns a Hasher for the primary UMASH function.

The seed tweaks the hash value without any proven impact on collision rates for different seed values.

Examples found in repository

examples/umash.rs (line 21)

fn main() {
    let args: Vec<String> = std::env::args().collect();
    let input = args
        .get(1)
        .cloned()
        .unwrap_or_else(|| "default input".to_string());
    let seed = 42u64;
    let my_params = umash::Params::derive(0, "hello example.c".as_bytes());
    let fprint = my_params
        .fingerprinter(seed)
        .write(input.as_bytes())
        .digest();

    println!("Input: {}", input);
    println!("Fingerprint: {:x}, {:x}", fprint.hash[0], fprint.hash[1]);
    println!(
        "Hash 0: {:x}",
        my_params.hasher(seed).write(input.as_bytes()).digest()
    );
    println!(
        "Hash 1: {:x}",
        my_params
            .secondary_hasher(seed)
            .write(input.as_bytes())
            .digest()
    );

    let mut h: umash::Hasher = (&my_params).into();
    h.write(input.as_bytes());
    println!("Hash: {:x}", h.finish());
}

pub fn secondary_hasher(&self, seed: u64) -> Hasher<'_>

Returns a Hasher for the secondary UMASH function.

The seed tweaks the hash value without any proven impact on collision rates for different seed values.

Examples found in repository

examples/umash.rs (line 26)

fn main() {
    let args: Vec<String> = std::env::args().collect();
    let input = args
        .get(1)
        .cloned()
        .unwrap_or_else(|| "default input".to_string());
    let seed = 42u64;
    let my_params = umash::Params::derive(0, "hello example.c".as_bytes());
    let fprint = my_params
        .fingerprinter(seed)
        .write(input.as_bytes())
        .digest();

    println!("Input: {}", input);
    println!("Fingerprint: {:x}, {:x}", fprint.hash[0], fprint.hash[1]);
    println!(
        "Hash 0: {:x}",
        my_params.hasher(seed).write(input.as_bytes()).digest()
    );
    println!(
        "Hash 1: {:x}",
        my_params
            .secondary_hasher(seed)
            .write(input.as_bytes())
            .digest()
    );

    let mut h: umash::Hasher = (&my_params).into();
    h.write(input.as_bytes());
    println!("Hash: {:x}", h.finish());
}

pub fn component_hasher(&self, seed: u64, which: UmashComponent) -> Hasher<'_>

Returns a Hasher for the desired UMASH component (primary hash or secondary function).

The seed tweaks the hash value without any proven impact on collision rates for different seed values.

pub fn fingerprinter(&self, seed: u64) -> Fingerprinter<'_>

Returns a Fingerprinter for the UMASH function.

The seed tweaks the hash value without any proven impact on collision rates for different seed values.

Examples found in repository

examples/umash.rs (line 13)

fn main() {
    let args: Vec<String> = std::env::args().collect();
    let input = args
        .get(1)
        .cloned()
        .unwrap_or_else(|| "default input".to_string());
    let seed = 42u64;
    let my_params = umash::Params::derive(0, "hello example.c".as_bytes());
    let fprint = my_params
        .fingerprinter(seed)
        .write(input.as_bytes())
        .digest();

    println!("Input: {}", input);
    println!("Fingerprint: {:x}, {:x}", fprint.hash[0], fprint.hash[1]);
    println!(
        "Hash 0: {:x}",
        my_params.hasher(seed).write(input.as_bytes()).digest()
    );
    println!(
        "Hash 1: {:x}",
        my_params
            .secondary_hasher(seed)
            .write(input.as_bytes())
            .digest()
    );

    let mut h: umash::Hasher = (&my_params).into();
    h.write(input.as_bytes());
    println!("Hash: {:x}", h.finish());
}

pub fn hash(&self, object: impl Hash) -> u64

Computes the UmashComponent::Hash value defined by this set of UMASH params for object and seed = 0.

UMASH’s collision probability bounds only hold if different objects feed different byte streams to the hasher. The standard Rust [std::Hash::hash] implementations (and automatically generated ones) satisfy this requirement for values of the same type.

pub fn secondary(&self, object: impl Hash) -> u64

Computes the UmashComponent::Secondary hash value defined by this set of UMASH params for object and seed = 0.

UMASH’s collision probability bounds only hold if different objects feed different byte streams to the hasher. The standard Rust [std::Hash::hash] implementations (and automatically generated ones) satisfy this requirement for values of the same type.

pub fn fingerprint(&self, object: impl Hash) -> Fingerprint

Computes the fingerprint value defined by this set of UMASH params for object and seed = 0.

UMASH’s collision probability bounds only hold if different objects feed different byte streams to the fingerprinter. The standard Rust [std::Hash::hash] implementations (and automatically generated ones) satisfy this requirement for values of the same type.

Trait Implementations

impl<'params> BuildHasher for &'params Params

A reference to a Params struct may be passed to hashed collections. The collection will use hashers derived from that static set of parameters (with seed = 0).

Unfortunately, due to lifetime complications, it’s not clear how to make each hashed collection generate a new Default Params: we want a guarantee that hashers will never outlive their parent builder.

type Hasher = Hasher<'params>

Type of the hasher that will be created.

fn build_hasher(&self) -> Hasher<'params>

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 Clone for Params

fn clone(&self) -> Params

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for Params

The default constructor for Params returns a fresh unique set of parameters.

fn default() -> Self

Returns the “default value” for a type.

impl<'params> From<&'params Params> for Fingerprinter<'params>

Converts a &Params to Fingerprinter by constructing a fresh Fingerprinter for these Params and seed = 0.

fn from(params: &'params Params) -> Fingerprinter<'params>

Converts to this type from the input type.

impl<'params> From<&'params Params> for Hasher<'params>

Converts a &Params to Hasher by constructing a fresh Hasher for these Params and seed = 0.

fn from(params: &'params Params) -> Hasher<'params>

Converts to this type from the input type.