maphash

maphash provides a seeded 64-bit byte-stream hash for hash-table use. It is not cryptographically secure and does not guarantee resistance to deliberate collision attacks. Its API is inspired by Go's hash/maphash; hash values are not compatible with Go.

import hash.maphash

seed := maphash.make_seed()
mut h := maphash.new_hasher(seed)
h.write_string('hello')
println(h.sum64())

Seeds and state

Use a fresh make_seed() for each independent hash table and reuse that seed for all keys in the table. Seeds are opaque, immutable values and can be shared between threads. make_seed obtains bytes from the operating system, does not consume or depend on the global rand generator, and may be called concurrently. It panics if the operating system cannot provide random bytes.

Seed{} is a valid deterministic zero seed. A default Hasher{} behaves like new_hasher(Seed{}); call new_hasher(make_seed()) to select a randomized seed. reset discards the input and keeps the original seed, including for a default hasher. A hasher is mutable and must not be written or reset concurrently. Separate hashers can safely use the same seed.

Stream behavior

Only the seed and byte sequence determine the result. Splitting input across several write or write_string calls produces the same hash as one concatenated write. Strings are hashed as raw bytes, including NUL and invalid UTF-8. write_u64 writes exactly eight bytes in big-endian order. Empty writes have no effect.

sum64 observes the current hash without changing it; further writes continue the same stream. Callers hashing multiple fields should encode their boundaries when needed: writing ab then c is equivalent to writing a then bc.

Hash values are not a persistent identifier or file format. The implementation may change between versions, even for the same seed and input.

fn make_seed() Seed

make_seed returns a seed from the operating system's random source. It does not use the global rand generator and may be called concurrently. It panics if the operating system cannot provide random bytes.

fn new_hasher(seed Seed) Hasher

new_hasher returns a Hasher initialized with seed, including the valid zero Seed{}.

struct Hasher {
mut:
	seed    Seed
	state   u64 = 0x9e3779b97f4a7c15
	written u64
}

Hasher is a hash function seeded with a Seed, suitable for use in hash tables. It is not cryptographically secure. A default Hasher uses the deterministic zero seed. Use new_hasher(make_seed()) for a randomized seed. A Hasher must not be mutated concurrently.

fn (mut h Hasher) write(data []u8)

write adds data to the hash.

fn (mut h Hasher) write_string(s string)

write_string adds the raw bytes of s to the hash, including NUL and invalid UTF-8.

fn (mut h Hasher) write_u64(v u64)

write_u64 adds the eight big-endian bytes of v to the hash.

fn (h Hasher) sum64() u64

sum64 returns the current 64-bit hash value without changing the state. Hash values are not guaranteed to remain the same across library versions.

fn (mut h Hasher) reset()

reset resets the hasher to its initial state with the same seed.

struct Seed {
	s0 u64
	s1 u64
}

Seed is an opaque seed value used to initialize a Hasher.