Module hash
Hashing — the Hasher implementations behind the prelude's Hash trait
(plans/archive/STD_API_AUDIT.md D3.9, plans/reference/HASHER_REDESIGN.md).
The split is Rust's: a type's Hash impl says WHICH bytes make up its
identity (hash(self, hasher) feeds them in), and a Hasher says how those
bytes become a u64 (write/write_u* accumulate, finish reads out).
Any Hash value can therefore be hashed by any algorithm, and one hasher
can consume a whole sequence of values (a tuple, a struct's fields, a
collection's elements).
SipHasher13— SipHash-1-3, keyed, the algorithmHashMap/HashSetdrive (as in Rust). With the default keys it is deterministic across runs; a map built withwith_keysis keyed per instance.Fnv1aHasher— FNV-1a, unkeyed and tiny; for short identifiers where speed beats collision resistance.DefaultHasher— the aliasHashMapuses (SipHasher13).hash_one(value)— the one-liner: hash a single value with the default hasher and default keys.
Stability
stable — the Hash/Hasher split is Rust's and the algorithm is real
SipHash-1-3 with a 128-bit key, verified against reference vectors in
tests/hash.test.yo. The one live question near this module —
plans/STD_API_STABILIZATION.md §5, whether to ship a
HashMap.with_random_keys() beside today's deterministic new() — is
answered with a NEW function over the new_with_keys this module already
exports, so it is additive; the fixed DEFAULT_KEY_0/DEFAULT_KEY_1 are
load-bearing for the compiler's own byte-identical-output fixpoint gate
and are not going to change. Further hashers would be additive too.
Types
SipHash-1-3 (one compression round per 8-byte block, three finalization rounds) with a 128-bit key, streaming: bytes may arrive in any grouping and the result depends only on their concatenation.
finish may be called at any point and does not reset the state.
Fields
| Name | Type | Description |
|---|---|---|
k0 | u64 | First half of the 128-bit key. Kept so |
k1 | u64 | Second half of the 128-bit key. |
v0 | u64 | SipHash internal state word 0, initialized to |
v1 | u64 | SipHash internal state word 1, initialized to |
v2 | u64 | SipHash internal state word 2, initialized to |
v3 | u64 | SipHash internal state word 3, initialized to |
tail | u64 | Up to 7 pending bytes, little-endian packed. |
ntail | usize | How many bytes |
length | usize | Total bytes written. |
Trait Implementations
impl(SipHasher13, ...)
new : (SipHasher13) fn() -> SipHasher13A hasher at FNV-1a's 64-bit offset basis (14695981039346656037). There is no keyed variant — FNV-1a has no key.
Returns: SipHasher13
new_with_keys : (SipHasher13) fn(k0 : u64, k1 : u64) -> SipHasher13A hasher keyed by k0, k1.
Parameters
| Name | Type | Notes | Description |
|---|---|---|---|
k0 | u64 | First half of the 128-bit key. Kept so | |
k1 | u64 | Second half of the 128-bit key. |
Returns: SipHasher13
reset : (SipHasher13) fn(self : SipHasher13) -> unitForget everything written so far, keeping the keys.
Parameters
| Name | Type | Notes |
|---|---|---|
self | SipHasher13 |
Returns: unit
_round : (SipHasher13) fn(self : SipHasher13) -> unit_compress : (SipHasher13) fn(self : SipHasher13, m : u64) -> unitAbsorb one full 8-byte block (little-endian value m).
Parameters
| Name | Type | Notes |
|---|---|---|
self | SipHasher13 | |
m | u64 |
Returns: unit
_push_byte : (SipHasher13) fn(self : SipHasher13, b : u8) -> unitimpl(SipHasher13, Hasher(...))
write : (SipHasher13) fn(self : SipHasher13, buf : *(u8), size : usize) -> unitFeed size bytes starting at buf.
Parameters
| Name | Type | Notes |
|---|---|---|
self | SipHasher13 | |
buf | *(u8) | |
size | usize |
Returns: unit
write_u64 : (SipHasher13) fn(self : SipHasher13, v : u64) -> unitwrite_u8 : (SipHasher13) fn(self : SipHasher13, v : u8) -> unitwrite_u16 : (SipHasher13) fn(self : SipHasher13, v : u16) -> unitwrite_u32 : (SipHasher13) fn(self : SipHasher13, v : u32) -> unitwrite_usize : (SipHasher13) fn(self : SipHasher13, v : usize) -> unitwrite_i8 : (SipHasher13) fn(self : SipHasher13, v : i8) -> unitwrite_i16 : (SipHasher13) fn(self : SipHasher13, v : i16) -> unitwrite_i32 : (SipHasher13) fn(self : SipHasher13, v : i32) -> unitwrite_i64 : (SipHasher13) fn(self : SipHasher13, v : i64) -> unitwrite_isize : (SipHasher13) fn(self : SipHasher13, v : isize) -> unitfinish : (SipHasher13) fn(self : SipHasher13) -> u64impl(SipHasher13, Default(...))
default : (SipHasher13) fn() -> SipHasher13The default value of the type.
Returns: SipHasher13
FNV-1a over the written bytes: 64-bit offset basis, prime
1099511628211. Unkeyed and fast; not collision-resistant against an
adversary — pick SipHasher13 for anything an attacker can feed.
Fields
| Name | Type | Description |
|---|---|---|
state | u64 |
Trait Implementations
impl(Fnv1aHasher, ...)
new : (Fnv1aHasher) fn() -> Fnv1aHasherA hasher at FNV-1a's 64-bit offset basis (14695981039346656037). There is no keyed variant — FNV-1a has no key.
Returns: Fnv1aHasher
impl(Fnv1aHasher, Hasher(...))
write : (Fnv1aHasher) fn(self : Fnv1aHasher, buf : *(u8), size : usize) -> unitFeed size bytes starting at buf.
Parameters
| Name | Type | Notes |
|---|---|---|
self | Fnv1aHasher | |
buf | *(u8) | |
size | usize |
Returns: unit
finish : (Fnv1aHasher) fn(self : Fnv1aHasher) -> u64impl(Fnv1aHasher, Default(...))
default : (Fnv1aHasher) fn() -> Fnv1aHasherThe default value of the type.
Returns: Fnv1aHasher
Methods
write_u8 : (Fnv1aHasher) fn(self : Fnv1aHasher, v : u8) -> unitwrite_u16 : (Fnv1aHasher) fn(self : Fnv1aHasher, v : u16) -> unitwrite_u32 : (Fnv1aHasher) fn(self : Fnv1aHasher, v : u32) -> unitwrite_u64 : (Fnv1aHasher) fn(self : Fnv1aHasher, v : u64) -> unitwrite_usize : (Fnv1aHasher) fn(self : Fnv1aHasher, v : usize) -> unitwrite_i8 : (Fnv1aHasher) fn(self : Fnv1aHasher, v : i8) -> unitwrite_i16 : (Fnv1aHasher) fn(self : Fnv1aHasher, v : i16) -> unitwrite_i32 : (Fnv1aHasher) fn(self : Fnv1aHasher, v : i32) -> unitwrite_i64 : (Fnv1aHasher) fn(self : Fnv1aHasher, v : i64) -> unitwrite_isize : (Fnv1aHasher) fn(self : Fnv1aHasher, v : isize) -> unitThe hasher HashMap/HashSet/hash_one use.
Fields
| Name | Type | Description |
|---|---|---|
k0 | u64 | First half of the 128-bit key. Kept so |
k1 | u64 | Second half of the 128-bit key. |
v0 | u64 | SipHash internal state word 0, initialized to |
v1 | u64 | SipHash internal state word 1, initialized to |
v2 | u64 | SipHash internal state word 2, initialized to |
v3 | u64 | SipHash internal state word 3, initialized to |
tail | u64 | Up to 7 pending bytes, little-endian packed. |
ntail | usize | How many bytes |
length | usize | Total bytes written. |
Methods
new_with_keys : (DefaultHasher) fn(k0 : u64, k1 : u64) -> SipHasher13A hasher keyed by k0, k1.
Parameters
| Name | Type | Notes | Description |
|---|---|---|---|
k0 | u64 | First half of the 128-bit key. Kept so | |
k1 | u64 | Second half of the 128-bit key. |
Returns: SipHasher13
new : (DefaultHasher) fn() -> SipHasher13A hasher at FNV-1a's 64-bit offset basis (14695981039346656037). There is no keyed variant — FNV-1a has no key.
Returns: SipHasher13
reset : (DefaultHasher) fn(self : SipHasher13) -> unitForget everything written so far, keeping the keys.
Parameters
| Name | Type | Notes |
|---|---|---|
self | SipHasher13 |
Returns: unit
_round : (DefaultHasher) fn(self : SipHasher13) -> unit_compress : (DefaultHasher) fn(self : SipHasher13, m : u64) -> unitAbsorb one full 8-byte block (little-endian value m).
Parameters
| Name | Type | Notes |
|---|---|---|
self | SipHasher13 | |
m | u64 |
Returns: unit
_push_byte : (DefaultHasher) fn(self : SipHasher13, b : u8) -> unitwrite : (DefaultHasher) fn(self : SipHasher13, buf : *(u8), size : usize) -> unitwrite_u64 : (DefaultHasher) fn(self : SipHasher13, v : u64) -> unitwrite_u8 : (DefaultHasher) fn(self : SipHasher13, v : u8) -> unitwrite_u16 : (DefaultHasher) fn(self : SipHasher13, v : u16) -> unitwrite_u32 : (DefaultHasher) fn(self : SipHasher13, v : u32) -> unitwrite_usize : (DefaultHasher) fn(self : SipHasher13, v : usize) -> unitwrite_i8 : (DefaultHasher) fn(self : SipHasher13, v : i8) -> unitwrite_i16 : (DefaultHasher) fn(self : SipHasher13, v : i16) -> unitwrite_i32 : (DefaultHasher) fn(self : SipHasher13, v : i32) -> unitwrite_i64 : (DefaultHasher) fn(self : SipHasher13, v : i64) -> unitwrite_isize : (DefaultHasher) fn(self : SipHasher13, v : isize) -> unitfinish : (DefaultHasher) fn(self : SipHasher13) -> u64default : (DefaultHasher) fn() -> SipHasher13Returns: SipHasher13
Functions
Hash one value with DefaultHasher and the default keys.
h := hash_one(String.from("key"));
assert(hash_one(i32(1)) == hash_one(i32(1)), "deterministic");
Type Parameters
| Name | Type | Notes |
|---|---|---|
T | Type | comptime |
Parameters
| Name | Type | Notes |
|---|---|---|
value | T |
Returns: u64
Hash one value with DefaultHasher keyed by k0, k1 — what a
HashMap.with_keys(k0, k1) computes for its keys.
Type Parameters
| Name | Type | Notes |
|---|---|---|
T | Type | comptime |
Parameters
| Name | Type | Notes | Description |
|---|---|---|---|
value | T | ||
k0 | u64 | First half of the 128-bit key. Kept so | |
k1 | u64 | Second half of the 128-bit key. |
Returns: u64
Constants
The keys SipHasher13.new() (and therefore HashMap.new(),
HashSet.new() and hash_one) start from. Fixed rather than random so a
program's hash values — and the iteration order of its maps — are the same
on every run; HashMap.with_keys opts a map into per-instance keys.
Value: 0
The second half of that fixed 128-bit key — see DEFAULT_KEY_0.
Value: 0