silk/hash

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc.

Deterministic seeded hashing contracts for hash maps, hash sets, and user-defined key types.

When to use

Implement HashKey when a type will be stored as a hashed key. Use mix for the first integer field and combine for further fields, feeding every field that participates in equality. Word is the ready-made key for one u64.

Details

A HashSeed belongs to a collection, not to each key. The same seed, keys, and operations produce the same bucket presentation order on every supported target, independent of addresses or ambient state. Interface witnesses are selected during specialization and add no runtime dispatch.

Gotchas

Whenever HashKey.equals reports two values equal, HashKey.hash must return the same value for both under every seed. The collection cannot detect a witness that violates this rule; such a key may become unreachable.

Examples

Hash the fields of one key deterministically

import silk.hash { Hash }

import silk.u64

pub fn main() -> i32 {
  let seed = Hash.seed(17)
  let first = Hash.mix(&seed, 4)
    |> Hash.combine(9)
  let second = Hash.mix(&seed, 4)
    |> Hash.combine(9)
  if first != second {
    return 0
  }
  return u64.toI32(Hash.word(42).value)
}

Import as HashKey with import silk.hash { HashKey }.

Public declarations: 4.

`Hash`

pub struct Hash

The owner of the seed, mixing, and ready-made key operations.

Details

This struct carries no data and is never constructed by the library. Every operation is an inherent member declared in impl Hash, reached through import silk.hash { Hash }.

Associated function `Hash.seed`

pub fn seed(value: u64) -> HashSeed

Creates a deterministic hash seed from one u64 value.

Associated function `Hash.mix`

pub fn mix<'life0>(seed: &'life0 silk/hash.HashSeed, value: u64) -> u64

Mixes the first integer field of a key with one seed into a 64-bit hash.

When to use

Use this function to start a hash for an integer key or the first integer field of a key.

Details

The same seed and value return the same result on all supported targets. Use combine for each additional field that participates in equality.

Associated function `Hash.combine`

pub fn combine(hashed: u64, value: u64) -> u64

Continues a hash with one further value, so a key of several fields folds into one hash.

When to use

Use this function after mix for each additional integer field that participates in equality.

Associated function `Hash.word`

pub fn word(value: u64) -> Word

Creates a Word key from one u64 value.

`HashSeed`

pub struct HashSeed

A collection-wide value that changes deterministic hash and bucket results.

Details

The same seed, keys, and operation sequence produce the same bucket order on all supported targets. A seed does not use allocation addresses, clocks, or ambient entropy.

Field `value`

pub value: u64

The seed value handed to every hash the collection computes.

Implementation `Copy for HashSeed`

impl Copy for HashSeed

`HashKey`

pub interface HashKey

A compile-time equivalence and seeded-hash contract for hashed collection keys.

operator == fn equals<'life0, 'life1>(left: &'life0 Self, right: &'life1 Self) -> bool

Reports whether two keys name the same collection entry.

Gotchas

If this returns true, HashKey.hash must return equal hashes for both keys under each seed.

Operation `hash`

fn hash<'life0, 'life1>(value: &'life0 Self, seed: &'life1 silk/hash.HashSeed) -> u64

Computes the key's deterministic 64-bit hash under the collection seed.

Gotchas

Equivalent keys must return equal results for the same seed.

`Word`

pub struct Word

A ready-made HashKey that holds one u64 value.

Field `value`

pub value: u64

The integer this key stands for.

Implementation `Copy for Word`

impl Copy for Word

Implementation `HashKey for Word`

impl HashKey for Word

Operation `equals`

equals = Word.wordEquals

Operation `hash`

hash = Word.wordHash

On this page