cespare/xxhash

xxhash is a Go implementation of the XXH64 algorithm. It is designed to be significantly faster than the hashing algorithms available in the Go standard library.

It provides two main ways to use it:

1. One-shot hashing: Use Sum64 or Sum64String for immediate results from a byte slice or string.
2. Streaming hashing: Use the Digest type to implement the hash.Hash64 interface, allowing you to incrementally write data before computing the final hash.

// One-shot examples
func Sum64(b []byte) uint64
func Sum64String(s string) uint64

// Streaming example using Digest
type Digest struct{ ... }
    func New() *Digest

By default, xxhash uses optimized assembly implementations for amd64 and arm64 architectures to achieve maximum performance.

If you need to force the use of the pure Go implementation (for example, to avoid assembly or for specific testing requirements), use the purego build tag during your build or test commands.

To hash data incrementally (e.g., when reading from a stream or building a hash from multiple parts), use the Digest type. Digest implements the standard hash.Hash64 interface.

Key methods:

• New(): Creates a new Digest instance.
• Write([]byte) (int, error): Writes bytes to the digest.
• WriteString(string) (int, error): Writes a string to the digest.
• Sum64() uint64: Returns the final 64-bit hash.

The Digest type implements encoding.BinaryMarshaler and encoding.BinaryUnmarshaler. This allows you to save the current state of a hash calculation (including the seed, internal accumulators, and any buffered partial blocks) to a byte slice and resume it later.

• MarshalBinary() ([]byte, error): Returns a byte slice containing the marshaled state.
• UnmarshalBinary(b []byte) error: Restores the digest state from the provided byte slice.

The Digest type implements the standard library's hash.Hash64 interface, allowing it to be used wherever a 64-bit hash is required. It provides the following methods:

• Write(b []byte) (n int, err error): Adds data to the digest.
• Sum64() uint64: Returns the current 64-bit hash.
• Sum(b []byte) []byte: Appends the current hash to the provided slice b and returns the resulting slice.
• Reset(): Clears the state using a zero seed.
• ResetWithSeed(seed uint64): Clears the state using a specific seed.
• Size() int: Returns 8.
• BlockSize() int: Returns 32.

To create a new hash state, use New() for a zero-seeded digest or NewWithSeed(seed uint64) to provide a custom seed.

Note: A zero-valued Digest struct is not ready to receive writes. Always use New() or NewWithSeed(), or call Reset() on an existing instance before calling Write.