README
¶
go-rapidhash
A faithful, idiomatic Go port of rapidhash V3 - a very fast, high-quality, platform-independent hashing algorithm.
Based on 'wyhash' by Wang Yi, ported from Nicolas De Carli's C implementation.
Features
- Fast: 50+ GB/s throughput for large inputs (74% of C implementation speed)
- Zero allocations: No heap allocations in the hot path
- High quality: Excellent avalanche characteristics and distribution
- Three variants: Choose the right trade-off for your use case
Hash: General-purpose, optimized for all input sizesHashMicro: Smaller instruction cache footprint, good balance between speed and code sizeHashNano: Smallest code footprint, fastest for 64B inputs, slower for large inputs
- Simple API: Just bytes in, uint64 out
- Pure Go: No unsafe, no assembly - just fast, idiomatic Go
Installation
go get github.com/bpowers/go-rapidhash
Usage
package main
import (
"fmt"
"github.com/bpowers/go-rapidhash"
)
func main() {
data := []byte("Hello, World!")
// Basic hashing with seed 0
hash := rapidhash.Hash(data, 0)
fmt.Printf("Hash: 0x%x\n", hash)
// With a custom seed
seededHash := rapidhash.Hash(data, 12345)
fmt.Printf("Seeded: 0x%x\n", seededHash)
// Using the micro variant (optimized for small/medium inputs)
microHash := rapidhash.HashMicro(data, 0)
fmt.Printf("Micro: 0x%x\n", microHash)
// Using the nano variant (minimal code size)
nanoHash := rapidhash.HashNano(data, 0)
fmt.Printf("Nano: 0x%x\n", nanoHash)
}
Performance
Benchmarked on Apple M4 Max (go1.21):
Size Hash Micro Nano Allocs
16B 8.0 GB/s 8.1 GB/s 8.1 GB/s 0
64B 14.5 GB/s 14.8 GB/s 18.5 GB/s 0
256B 34.4 GB/s 36.2 GB/s 34.6 GB/s 0
1KB 49.5 GB/s 44.1 GB/s 39.9 GB/s 0
4KB 52.8 GB/s 50.2 GB/s 38.5 GB/s 0
Achieves 53 GB/s on 4KB inputs - 74% of C implementation performance (71 GB/s) using only safe, idiomatic Go.
Which Variant Should I Use?
- Hash: Default choice. Best for large inputs (>1KB). Achieves 53 GB/s on 4KB.
- HashMicro: Better iCache footprint, nearly as fast as Hash. Achieves 50 GB/s on 4KB.
- HashNano: Best for small inputs - fastest at 64B (18.5 GB/s), smallest code footprint.
All variants are fast - choose based on your typical input size. For inputs ≤16 bytes, all variants produce identical hash values and similar performance.
Testing
The implementation is validated against the original C implementation using extensive test vectors:
go test -v
(100% code coverage)
Run benchmarks:
go test -bench=. -benchmem
License
MIT - see LICENSE file for details.
Documentation
¶
Overview ¶
Package rapidhash implements rapidhash V3, a very fast, high-quality, platform-independent hashing algorithm.
This is a faithful port of the C implementation by Nicolas De Carli, based on 'wyhash' by Wang Yi.
Copyright (C) 2025 Bobby Powers ¶
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Original C implementation: https://github.com/Nicoshev/rapidhash
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Hash ¶
Hash computes a 64-bit hash of the input data using the given seed. This is the general-purpose rapidhash function optimized for all input sizes.
The hash is deterministic: the same input and seed will always produce the same output. Different seeds will produce different hash values.
func HashMicro ¶
HashMicro computes a 64-bit hash optimized for HPC and server applications. It is designed to minimize cache misses and compiles to approximately 140 instructions without stack usage. It is faster for sizes up to 512 bytes, and only 15-20% slower for inputs above 1KB.
Types ¶
This section is empty.
Source Files