XXH3

https://github.com/zeebo/xxh3
Admin
This package is a Go port of the xxh3 hashing library, matching the output of the upstream v0.8.0...
Tokens:25,612
Snippets:220
Trust Score:9.7
License:BSD-2-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Hasher.Size usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Example showing how to allocate a buffer based on the Hasher size.

```go
digest := make([]byte, h.Size())
copy(digest, h.Sum(nil)) // 8 bytes, big-endian
```

--------------------------------

### Sum64 usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Example of writing data to the hasher and retrieving the final checksum.

```go
h := xxh3.New()
h.Write(header)
h.Write(body)
checksum := h.Sum64()
```

--------------------------------

### Hasher.Write usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Example of writing multiple data chunks to the hasher.

```go
h.Write([]byte("part one"))
h.Write([]byte("part two"))
// n == 8, err == nil after each call
```

--------------------------------

### Hasher.Sum usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Demonstrates calculating the hash and appending it to a buffer.

```go
h.Write(data)
sum := h.Sum(nil) // 8 bytes big-endian
// or accumulate into a larger buffer
full := h.Sum([]byte("prefix:"))
```

--------------------------------

### WriteString method usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Example of calling WriteString with two lines. Empty strings are a no-op.

```go
h.WriteString("line one\n")
h.WriteString("line two\n")
```

--------------------------------

### Write method usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Example of calling Write on a Hasher128 instance. The error is always nil, so the check is unreachable.

```go
n, err := h.Write(someBytes)
if err != nil {
	// unreachable for xxh3
}
```

--------------------------------

### BlockSize Usage Example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Shows how to use the BlockSize method to allocate a buffer for efficient writing.

```go
buf := make([]byte, h.BlockSize())
n, _ := h.Write(buf) // n == 64
```

--------------------------------

### BlockSize usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Shows how to create a buffered writer sized to the block size, flushing on defer.

```go
w := bufio.NewWriterSize(dst, h.BlockSize())
defer w.Flush()
```

--------------------------------

### ResetSeed Usage Example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Demonstrates resetting a hasher with a new seed and writing data to it.

```go
h := xxh3.New()
h.Write(data1)
h.ResetSeed(7) // now behaves like NewSeed(7)
h.Write(data2)
d := h.Sum64() // == xxh3.HashSeed(append(data1, data2...)... conceptually
```

--------------------------------

### HashSeed usage examples

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hash64.md

Demonstrates using a namespace-based salt and comparing digests with different seeds.

```go
func digestWithSalt(namespace string, payload []byte) uint64 {
	return xxh3.HashSeed(payload, xxh3.HashString(namespace))
}
```

```go
a := xxh3.HashSeed(data, 1)
b := xxh3.HashSeed(data, 2)
// a != b in general
```

--------------------------------

### Sum128 usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Demonstrates how to write data to the hasher and retrieve the 128-bit digest.

```go
h := xxh3.New()
h.Write(payload)
d := h.Sum128()
fmt.Println(d.Hi, d.Lo) // or d.Bytes() for 16 big-endian bytes
```

--------------------------------

### HashString usage

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hash64.md

Examples of hashing a string directly and using it to generate a lookup key.

```go
h := xxh3.HashString("streaming-key-in-config")
```

```go
func bucketFor(key string, numBuckets uint64) uint64 {
	return xxh3.HashString(key) % numBuckets
}
```

--------------------------------

### Size usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Allocates a byte slice of the correct size and copies the digest into it.

```go
digest := make([]byte, h.Size()) // 16 bytes
copy(digest, h.Sum(nil))
```

--------------------------------

### Example: create and reset Hasher

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Creates a new Hasher and defers Reset to allow reuse. The comment notes that Reset can be called to reuse the hasher.

```go
h := xxh3.New()
defer h.Reset() // or reuse via h.Reset()

```

--------------------------------

### WriteString usage examples

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Basic usage of WriteString to add multiple strings to the hasher.

```go
h.WriteString("config")
h.WriteString("section")
```

--------------------------------

### Sum128 method usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Example of using Sum128 after writing data via io.Copy. The hash is printed as two 64-bit hex values.

```go
h := xxh3.New128()
io.Copy(h, file) // h is an io.Writer
d := h.Sum128()
fmt.Printf("%016x%016x\n", d.Hi, d.Lo)
```

--------------------------------

### HashString128Seed usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hash128.md

Example of using HashString128Seed to compute a shard key from a shard number and a string key.

```go
func shardKey(shard uint32, key string) xxh3.Uint128 {
	return xxh3.HashString128Seed(key, uint64(shard))
}
```

--------------------------------

### HashStringSeed usage

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hash64.md

Example of generating a signed digest using a tenant-specific salt.

```go
func tenantDigest(tenantID uint64, value string) uint64 {
	return xxh3.HashStringSeed(value, tenantID)
}
```

--------------------------------

### HashString128 usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hash128.md

Example of hashing a string key directly without a byte conversion, and folding the result to 64 bits.

```go
d := xxh3.HashString128("primary-key")
_ = d.Hi ^ d.Lo // fold to 64 bits if needed
```

--------------------------------

### Hash checksum and verification

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hash64.md

Example of using Hash to generate a checksum and verify data integrity.

```go
func checksum(data []byte) uint64 {
	return xxh3.Hash(data)
}

func verify(data []byte, want uint64) bool {
	return xxh3.Hash(data) == want
}
```

--------------------------------

### Sum usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Writes data to the hasher and obtains the 16-byte canonical big-endian digest.

```go
h.Write(data)
wire := h.Sum(nil) // 16 bytes, canonical big-endian
```

--------------------------------

### Hash128Seed usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hash128.md

Example of using Hash128Seed to create a deduplication ID based on environment and body.

```go
func dedupeID(env string, body []byte) xxh3.Uint128 {
	return xxh3.Hash128Seed(body, xxh3.HashString(env))
}
```

--------------------------------

### New constructor for Hasher

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

New returns a zero-value Hasher. The default key and accumulator state are installed lazily on the first Write/WriteString/Sum64/Sum128 call.

```go
// New returns a new Hasher that implements the hash.Hash interface.
func New() *Hasher

```

--------------------------------

### Hasher.Write error handling convention

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Example of the standard error-handling pattern for io.Writer, though errors are unreachable for xxh3.

```go
n, err := h.Write(chunk)
if err != nil {
	return err // unreachable for xxh3, but satisfies io.Writer use
}
```

--------------------------------

### Reset usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Shows that after Reset, the seed (5) remains active, so writing b produces a seeded digest.

```go
h := xxh3.NewSeed128(5)
h.Write(a)
h.Reset() // seed 5 still active
h.Write(b) // seeded digest of b
```

--------------------------------

### NewSeed128 usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Creates a seeded Hasher128 with seed 99, writes a string, and computes the 128-bit digest.

```go
h := xxh3.NewSeed128(99)
h.WriteString("indexed-document")
digest := h.Sum128()
```

--------------------------------

### WriteString allocation-free hashing

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Example of using WriteString with a long string to avoid unnecessary byte copies.

```go
h := xxh3.New()
h.WriteString(bigText) // string path avoids a byte-copy where possible
sum := h.Sum64()
```

--------------------------------

### Hash128 basic usage and byte serialization

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hash128.md

Example of hashing a byte slice and printing the result as a hex string, plus storing the digest in a 16-byte array using Uint128.Bytes().

```go
package main

import (
	"fmt"

	"github.com/zeebo/xxh3"
)

func main() {
	d := xxh3.Hash128([]byte("hello world"))
	fmt.Printf("%016x%016x\n", d.Hi, d.Lo)

	var key [16]byte = d.Bytes() // canonical big-endian form
	_ = key
}
```

--------------------------------

### ResetSeed usage example

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Switches the seed mid-stream between reuse cycles: after writing part1, ResetSeed(11) changes the seed, and subsequent Reset calls keep it.

```go
h := xxh3.New128()
h.Write(part1)
h.ResetSeed(11) // switch salt mid-stream between reuse cycles
h.Write(part2)
```

--------------------------------

### Hash basic usage

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hash64.md

Demonstrates hashing a byte slice and handling empty input.

```go
package main

import (
	"fmt"

	"github.com/zeebo/xxh3"
)

func main() {
	h := xxh3.Hash([]byte("hello world"))
	fmt.Printf("%016x\n", h) // deterministic 64-bit digest

	empty := xxh3.Hash(nil)
	fmt.Printf("%016x\n", empty) // 0x2d06800538d394c2
}
```

--------------------------------

### Hasher io.Writer interface compliance

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Demonstrates that Hasher satisfies the io.Writer interface.

```go
var _ io.Writer = xxh3.New()
```

--------------------------------

### Reset Hasher State

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Demonstrates the internal state reset logic for the Hasher.

```go
h.acc = [8]u64{
	prime32_3, prime64_1, prime64_2, prime64_3,
	prime64_4, prime32_2, prime64_5, prime32_1,
}
h.blk = 0
h.len = 0
```

--------------------------------

### Import the xxh3 package

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/overview.md

The package is imported from the root path without sub-package dependencies.

```go
import "github.com/zeebo/xxh3"
```

--------------------------------

### Reuse Hasher with Reset

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Shows how to efficiently reuse a single hasher instance for multiple values by calling Reset.

```go
h := xxh3.New()
for _, v := range values {
	h.Reset()
	h.Write(v)
	_ = h.Sum64()
}
```

--------------------------------

### Initialize Hasher with NewSeed

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Creates a new Hasher instance with a specific seed value.

```go
h := xxh3.NewSeed(42)
h.Write(data)
digest := h.Sum64()
```

--------------------------------

### New

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Returns a new Hasher that implements the hash.Hash interface. The hasher is initialized lazily on first use, and a zero-value Hasher is also usable.

```APIDOC
## New

### Description
Returns a new Hasher that implements the hash.Hash interface. The hasher is initialized lazily on first use, and a zero-value Hasher is also usable.

### Method
New

### Endpoint
func New() *Hasher

### Parameters
None.

### Return Type
*Hasher — a zero-value hasher. The default key and accumulator state are installed lazily on the first Write/WriteString/Sum64/Sum128. A bare zero-value Hasher value is also usable without calling New.

### Errors
None.

### Examples
```go
h := xxh3.New()
defer h.Reset() // or reuse via h.Reset()
```
```

--------------------------------

### Construction with positional and keyed fields

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/uint128.md

Shows two ways to create a Uint128 value. Positional and keyed forms must agree; field order is Hi, Lo.

```go
a := xxh3.Uint128{Hi: 1, Lo: 2}
b := xxh3.Uint128{1, 2} // same value: Hi=1, Lo=2
```

--------------------------------

### Basic usage of Bytes with Hash128

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/uint128.md

Shows capturing a 128-bit digest, converting to bytes, printing hex, and reconstructing the value from bytes.

```go
package main

import (
	"fmt"

	"github.com/zeebo/xxh3"
)

func main() {
	d := xxh3.Hash128([]byte("hello world"))
	b := d.Bytes()
	fmt.Printf("%x\n", b[:]) // 16-byte big-endian hex

	// Reconstructing the value from bytes:
	hi := uint64(b[0])<<56 | uint64(b[1])<<48 | uint64(b[2])<<40 | uint64(b[3])<<32 |
		uint64(b[4])<<24 | uint64(b[5])<<16 | uint64(b[6])<<8 | uint64(b[7])
	lo := uint64(b[8])<<56 | uint64(b[9])<<48 | uint64(b[10])<<40 | uint64(b[11])<<32 |
		uint64(b[12])<<24 | uint64(b[13])<<16 | uint64(b[14])<<8 | uint64(b[15])
	fmt.Println(xxh3.Uint128{Hi: hi, Lo: lo} == d) // true
}
```

--------------------------------

### BlockSize method implementation

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Returns the hash's underlying block size, always 64. Writes are most efficient when total length is a multiple of 1024, but any amount is accepted.

```go
// BlockSize returns the hash's underlying block size.
// The Write method will accept any amount of data, but
// it may operate more efficiently if all writes are a
// multiple of the block size.
func (h *Hasher128) BlockSize() int { return _stripe }
```

--------------------------------

### Write

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Adds more data to the running hash. It never returns an error and always returns the length of the input buffer and a nil error.

```APIDOC
## Write

### Description
Adds more data to the running hash. It never returns an error.

### Method
Write

### Endpoint
func (h *Hasher128) Write(buf []byte) (int, error)

### Parameters
#### Parameter
- **buf** ([]byte) - Required - Bytes to fold into the running hash

### Return type
`(int, error)` - always `(len(buf), nil)`.

### Errors
Never returns a non-nil error (satisfies the `hash.Hash` contract; `Hasher128` can serve as an `io.Writer`).

### Examples
```go
n, err := h.Write(someBytes)
if err != nil {
	// unreachable for xxh3
}
```
```

--------------------------------

### Size method implementation

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Returns the number of bytes Sum will return, always 16.

```go
// Size returns the number of bytes Sum will return.
func (h *Hasher128) Size() int { return 16 }
```

--------------------------------

### Using New128 to hash a stream

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Creates a new Hasher128, writes data, and computes the 128-bit hash as a xxh3.Uint128.

```go
h := xxh3.New128()
h.Write([]byte("stream"))
d := h.Sum128() // xxh3.Uint128
```

--------------------------------

### New128 constructor

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Returns a new 128-bit Hasher that implements the hash.Hash interface. The zero value is usable without a constructor.

```go
// New128 returns a new 128 bit Hasher that implements the hash.Hash interface.
func New128() *Hasher128
```

--------------------------------

### Hasher.Write implementation

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

The Write method adds data to the running hash and always returns the length of the input as the number of bytes written.

```go
// Write adds more data to the running hash.
// It never returns an error.
func (h *Hasher) Write(buf []byte) (int, error)
```

--------------------------------

### Hasher.Size implementation

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

The Size method returns the number of bytes the Sum method will return, which is always 8.

```go
// Size returns the number of bytes Sum will return.
func (h *Hasher) Size() int { return 8 }
```

--------------------------------

### BlockSize Method Definition

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Returns the underlying block size of the hash, which is useful for optimizing write operations.

```go
// BlockSize returns the hash's underlying block size.
// The Write method will accept any amount of data, but
// it may operate more efficiently if all writes are a
// multiple of the block size.
func (h *Hasher) BlockSize() int { return _stripe }
```

--------------------------------

### Hasher128 implements hash.Hash

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/types.md

Compile-time assertion that Hasher128 implements the hash.Hash interface. hash.Hash64 is not implemented because Size() is 16 and there is no Sum64.

```go
var (
	_ hash.Hash = (*Hasher128)(nil)
)
```

--------------------------------

### SIMD Selection Logic

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/overview.md

The SIMD selection logic determines which accumulation routine to execute based on available CPU features like AVX-512, AVX2, SSE2, or NEON, falling back to a scalar implementation if no SIMD instructions are supported.

```go
if hasAVX512 && l >= avx512Switch {
    accumAVX512(&accs, p, key, u64(l))
} else if hasAVX2 {
    accumAVX2(&accs, p, key, u64(l))
} else if hasSSE2 {
    accumSSE(&accs, p, key, u64(l))
} else if hasNEON {
    accumNEON(&accs, p, key, u64(l))
} else {
    accumScalar(&accs, p, key, u64(l))
}
```

--------------------------------

### New128

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Constructor for a new 128-bit Hasher that implements the hash.Hash interface.

```APIDOC
## New128

### Description
Returns a new 128-bit Hasher that implements the hash.Hash interface.

### Method
Constructor

### Signature
func New128() *Hasher128

### Parameters
None.

### Return Type
*Hasher128 — a zero-value 128-bit hasher; default key and state installed lazily on first use.

### Errors
None.

### Example
```go
h := xxh3.New128()
h.Write([]byte("stream"))
d := h.Sum128() // xxh3.Uint128
```
```

--------------------------------

### New128

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/types.md

Creates a new Hasher128 instance with a zero seed.

```APIDOC
## New128

### Description
Creates a new Hasher128 instance with a zero seed.

### Signature
func New128() *Hasher128

### Returns
- *Hasher128 - A new Hasher128 instance.
```

--------------------------------

### Reset

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/types.md

Resets the hasher to its initial state with a zero seed.

```APIDOC
## Reset

### Description
Resets the hasher to its initial state with a zero seed.

### Signature
func (h *Hasher128) Reset()
```

--------------------------------

### Uint128 Construction

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/uint128.md

Describes how to construct Uint128 values using composite literals, either with keyed fields or positional fields in the order Hi, Lo.

```APIDOC
## Construction

### Description
Uint128 can be constructed using composite literals with either keyed or positional fields. The field order is Hi first, then Lo.

### Examples
```go
a := xxh3.Uint128{Hi: 1, Lo: 2}
b := xxh3.Uint128{1, 2} // same value: Hi=1, Lo=2
```

The zero value Uint128{} is meaningful as a neutral comparison value but is not a valid digest of any input.
```

--------------------------------

### Write

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/types.md

Writes data to the hasher and returns the number of bytes written. The error is always nil.

```APIDOC
## Write

### Description
Writes data to the hasher and returns the number of bytes written. The error is always nil.

### Signature
func (h *Hasher128) Write(buf []byte) (int, error)

### Parameters
- buf ([]byte) - Required - The data to write.

### Returns
- int - The number of bytes written.
- error - Always nil.
```

--------------------------------

### Sum64 method signature

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

The signature for the Sum64 method which returns the 64-bit hash of the written data.

```go
// Sum64 returns the 64-bit hash of the written data.
func (h *Hasher) Sum64() uint64
```

--------------------------------

### Size

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/types.md

Returns the size of the hash output in bytes, which is 16.

```APIDOC
## Size

### Description
Returns the size of the hash output in bytes, which is 16.

### Signature
func (h *Hasher128) Size() int

### Returns
- int - The size of the hash output (16).
```

--------------------------------

### Sum method implementation

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher128.md

Appends the current hash to b and returns the resulting slice. Does not change the underlying hash state. The digest is the 16-byte big-endian canonical form, Hi first.

```go
// Sum appends the current hash to b and returns the resulting slice.
// It does not change the underlying hash state.
func (h *Hasher128) Sum(b []byte) []byte
```

```go
sum := h.h.Sum128().Bytes()
return append(b, sum[:]...)
```

--------------------------------

### Sum64

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

Returns the 64-bit hash of the written data. The hasher state is unchanged, so Sum64 may be called repeatedly.

```APIDOC
## Sum64

### Description
Returns the 64-bit hash of the written data. The hasher state is unchanged, so Sum64 may be called repeatedly.

### Method
Sum64

### Signature
func (h *Hasher) Sum64() uint64

### Parameters
None.

### Return type
uint64 - the final 64-bit digest of everything written so far, equal to Hash(allWrittenBytes) (or HashSeed(allWrittenBytes, seed) for a seeded hasher).

### Behavior highlights
- With zero full blocks written (h.blk == 0) it delegates to the one-shot Hash/HashSeed over the buffered bytes.
- Otherwise it accumulates the residual partial block into a copy of the 8-lane accumulator using accumAVX2/accumSSE/accumNEON/accumScalar (AVX-512 is intentionally not used for this single partial block), then merges the lanes with the default key words (key64_011 ... key64_067) or, when seeded, with the derived secret, and finally avalanches via xxh3Avalanche.
- Lazy initialization: calling Sum64 on a never-written hasher installs the default key and resets first.

### Errors
None.

### Examples
```go
h := xxh3.New()
h.Write(header)
h.Write(body)
checksum := h.Sum64()
```
```

--------------------------------

### Hasher.Sum implementation

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/hasher.md

The Sum method appends the current hash to the provided slice and returns the resulting slice without modifying the internal state.

```go
// Sum appends the current hash to b and returns the resulting slice.
// It does not change the underlying hash state.
func (h *Hasher) Sum(b []byte) []byte
```

--------------------------------

### Round-tripping through a wire format

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/api-reference/uint128.md

Shows using Bytes to store a digest in a struct field for serialization.

```go
type Record struct {
	Key    [16]byte
	Length uint64
}

func (r *Record) Digest(data []byte) {
	r.Key = xxh3.HashString128(string(data)).Bytes()
}
```

--------------------------------

### Hasher

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/types.md

A streaming 64-bit hasher that implements the hash.Hash and hash.Hash64 interfaces. It provides constructors, reset methods, and methods to write data and obtain the hash.

```APIDOC
## Hasher

### Description
A streaming 64-bit hasher implementing hash.Hash and hash.Hash64. A zero-value Hasher is fully usable without calling a constructor.

### Constructors
- **New** `func New() *Hasher` - Creates a new Hasher with default seed.
- **NewSeed** `func NewSeed(seed uint64) *Hasher` - Creates a new Hasher with the given seed.

### Methods
- **Reset** `func (h *Hasher) Reset()` - Resets the hasher to its initial state.
- **ResetSeed** `func (h *Hasher) ResetSeed(seed uint64)` - Resets the hasher with a new seed.
- **BlockSize** `func (h *Hasher) BlockSize() int` - Returns the block size (64).
- **Size** `func (h *Hasher) Size() int` - Returns the hash size (8).
- **Sum** `func (h *Hasher) Sum(b []byte) []byte` - Appends the current hash to b and returns the resulting slice.
- **Write** `func (h *Hasher) Write(buf []byte) (int, error)` - Writes data to the hasher. Error is always nil.
- **WriteString** `func (h *Hasher) WriteString(buf string) (int, error)` - Writes a string to the hasher. Error is always nil.
- **Sum64** `func (h *Hasher) Sum64() uint64` - Returns the 64-bit hash value.
- **Sum128** `func (h *Hasher) Sum128() Uint128` - Returns the 128-bit hash value.
```

--------------------------------

### WriteString

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/types.md

Writes a string to the hasher and returns the number of bytes written. The error is always nil.

```APIDOC
## WriteString

### Description
Writes a string to the hasher and returns the number of bytes written. The error is always nil.

### Signature
func (h *Hasher128) WriteString(buf string) (int, error)

### Parameters
- buf (string) - Required - The string to write.

### Returns
- int - The number of bytes written.
- error - Always nil.
```

--------------------------------

### NewSeed128

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/types.md

Creates a new Hasher128 instance with a specified seed.

```APIDOC
## NewSeed128

### Description
Creates a new Hasher128 instance with a specified seed.

### Signature
func NewSeed128(seed uint64) *Hasher128

### Parameters
- seed (uint64) - Required - The seed value for the hasher.

### Returns
- *Hasher128 - A new Hasher128 instance.
```

--------------------------------

### Hasher interface assertions

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/types.md

Compile-time assertions that *Hasher implements both hash.Hash and hash.Hash64 interfaces.

```go
var (
	_ hash.Hash   = (*Hasher)(nil)
	_ hash.Hash64 = (*Hasher)(nil)
)
```

--------------------------------

### Internal helper aliases and str struct in utils.go

Source: https://github.com/zeebo/xxh3/blob/master/_autodocs/types.md

Internal helper aliases and the str struct used by the one-shot kernels. These types are not importable; they are defined in utils.go and used internally for pointer/length views.

```go
type (
	ptr = unsafe.Pointer
	ui  = uintptr

	u8   = uint8
	u32  = uint32
	u64  = uint64
	u128 = Uint128
)

type str struct {
	p ptr
	l uint
}
```
Tokens:
Raw