feat: complete and qualify hash variant APIs - #13
Merged
Conversation
MurmurHash3 defines separate x86_128 and x64_128 algorithms, so describing the architecture-qualified function as merely an alias hides important disambiguation. Present x64_128 as the implemented variant, identify murmur3_128 as the shorter equivalent name, and state that x86_128 is not implemented.
The 0.1 API exposed module-level one-shot functions alongside state-associated forwarding methods, and also retained alternate names for MurmurHash3 x64_128, the XXH3-64 state, and 128-bit digests. Those paths describe the same operations and make the capability map look larger than the implementation really is.\n\nKeep the reference-qualified MurmurHash3 names, Xxh3 for the conventional 64-bit state, digest for every state result, and module-level functions for complete input. Rustdoc aliases preserve discovery of the retired spellings without keeping duplicate compile-time APIs.
The existing 128-bit helper names did not identify whether they implemented the x86 or x64 MurmurHash3 variant. That ambiguity becomes error-prone once both algorithms live in the same module.\n\nQualify the constants, lane mixers, block consumer, and finalizer as x64_128 before adding the separate x86_128 path. This is a naming-only change with no public API or behavior change.
Rache exposed x86_32 and x64_128 but omitted the third algorithm in the original MurmurHash3 family. That gap made the architecture-qualified names harder to explain and prevented interoperability with x86_128 digests.\n\nAdd allocation-free one-shot and streaming APIs under the unique murmur3_x86_128 and Murmur3X86_128 names. Share the common 16-byte streaming buffer path with x64_128, cover the new variant through the existing reference, partition, I/O, and benchmark matrices, and keep both 128-bit algorithms distinct in the capability documentation.
The renamed crate is being presented as a fresh release, so preserving vocabulary from the old crate in rustdoc search would add ambiguity without serving a supported migration path.
The x64_128 documentation still claimed x86_128 was unavailable after that variant was implemented. Directly link the two distinct algorithms so callers can choose deliberately.
Rache exposes separate streaming states for the 64-bit and 128-bit XXH3 algorithms, so an unqualified Xxh3 name incorrectly suggests a shared or default state. Match xxh3_64 with Xxh3_64 and make the output width discoverable without relying on convention.
Both builders construct only Xxh3_64 states because BuildHasher returns u64. Naming them Xxh3_64Builder and Xxh3_64SecretBuilder keeps the algorithm width explicit and matches the state they build.
The completed MurmurHash3 family exposes three distinct reference variants. Naming the 32-bit API murmur3_x86_32, Murmur3X86_32, and Murmur3X86_32Builder removes the only variant-name exception and makes all three mappings predictable.
The explicit XXH3 and MurmurHash3 names change rustfmt line wrapping and lexical import order. Apply only those mechanical adjustments so the naming commits remain easy to inspect.
tisonkun
marked this pull request as ready for review
September 2, 2026 09:39
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
update,digest, and integration traits.Design Notes
MurmurHash3 now maps directly to the three names defined by the reference implementation:
murmur3_x86_32Murmur3X86_32Murmur3X86_32Buildermurmur3_x86_128Murmur3X86_128murmur3_x64_128Murmur3X64_128The x86 and x64 labels select incompatible digest algorithms rather than restricting the Rust implementation to those target architectures; all three implementations are portable. The new x86_128 implementation follows the reference four-lane block, tail, and finalization order. Its one-shot and streaming results are checked against
murmur30.5.2 across every length through 2 KiB, randomized inputs through 128 KiB, arbitrary streaming chunks, every two-way split through 257 bytes, and multiple seeds.XXH3 likewise exposes
xxh3_64/Xxh3_64andxxh3_128/Xxh3_128.Xxh3_64BuilderandXxh3_64SecretBuilderare width-qualified becauseBuildHasherconstructs only the 64-bit state.Xxh3Kernel,Xxh3SecretTooShort, and the secret constants remain unqualified because they are genuinely shared by both output widths.Why remove associated one-shot methods?
A complete byte slice has one entry point: the corresponding module-level function. The removed state-associated methods were one-line forwarding wrappers with no state, configuration, validation, or behavior of their own. Keeping both forms made the API appear to offer two hashing modes and doubled the places users had to compare in rustdoc.
For FNV-1a specifically:
Fnv1a32::oneshot(input)is covered byfnv1a_32(input).Fnv1a32::oneshot_with_offset_basis(input, basis)is covered byfnv1a_32_with_offset_basis(input, basis).Fnv1a64::oneshot(input)is covered byfnv1a_64(input).Fnv1a64::oneshot_with_offset_basis(input, basis)is covered byfnv1a_64_with_offset_basis(input, basis).The state constructors, custom offset bases,
update,digest,reset, builders,Hasher, andstd::io::Writeremain because they represent distinct configuration or integration capabilities. The same rule is applied consistently to MurmurHash3 and xxHash state-associated one-shot forwarding methods.Validation
cargo x lintcargo x checkcargo x testmurmur3reference path 4.47 / 4.56 GB/s on the development host