xxh64

Documentation

Overview

Package xxh64 implements XXH64, the 64-bit hash from xxHash, with generated assembly kernels for amd64 and arm64.

XXH64 is the older, scalar member of the xxHash family: four 64-bit lanes, each a multiply, a rotate and another multiply per eight bytes of input. It is what most Go code that says "xxhash" computes today. The output is bit-identical to the reference implementation, including seeds, and is checked against vectors taken from the C code.

For the newer, faster XXH3, see the parent package.

Choosing an entry point

Sum64 and Sum64String hash a whole slice or string in one call; Sum64Seed and Sum64SeedString key the hash with a seed at no extra cost. For input arriving in pieces, New and NewSeed return a Digest, which implements hash.Hash64 and can be marshalled mid-stream.

Backends

On amd64 and arm64 the whole hash of any input runs in one call into a generated assembly kernel; the arm64 kernel has the lane round in two forms, chosen by core (see Backend). Every other architecture, and a "purego" build, uses the portable implementation in this package, which is also what the kernels are checked against.

Index

• func Backend() string
• func Sum64(b []byte) uint64
• func Sum64Seed(b []byte, seed uint64) uint64
• func Sum64SeedString(s string, seed uint64) uint64
• func Sum64String(s string) uint64
• func Sum64Uint32(v uint32) uint64
• func Sum64Uint32Seed(v uint32, seed uint64) uint64
• func Sum64Uint64(v uint64) uint64
• func Sum64Uint64Seed(v, seed uint64) uint64
• func Sum64Uint128(lo, hi uint64) uint64
• func Sum64Uint128Seed(lo, hi, seed uint64) uint64
• type Digest
  • func New() *Digest
  • func NewSeed(seed uint64) *Digest
  • func (d *Digest) BlockSize() int
  • func (d *Digest) MarshalBinary() ([]byte, error)
  • func (d *Digest) Reset()
  • func (d *Digest) Size() int
  • func (d *Digest) Sum(b []byte) []byte
  • func (d *Digest) Sum64() uint64
  • func (d *Digest) UnmarshalBinary(b []byte) error
  • func (d *Digest) Write(b []byte) (int, error)
  • func (d *Digest) WriteString(s string) (int, error)

Examples

• Sum64

Functions

func Backend

func Backend() string

Backend names the kernel in use, and which prime form it took.

func Sum64

func Sum64(b []byte) uint64

Sum64 returns the XXH64 hash of b.

Example

fmt.Printf("%#016x\n", Sum64([]byte("hello")))

Output:
0x26c7827d889f6da3

func Sum64Seed

func Sum64Seed(b []byte, seed uint64) uint64

Sum64Seed returns the XXH64 hash of b under seed. A seed of zero gives the same result as Sum64.

func Sum64SeedString

func Sum64SeedString(s string, seed uint64) uint64

Sum64SeedString returns the XXH64 hash of s under seed, without copying it.

func Sum64String

func Sum64String(s string) uint64

Sum64String returns the XXH64 hash of s, without copying it.

func Sum64Uint32

func Sum64Uint32(v uint32) uint64

Sum64Uint32 returns the XXH64 hash of v's four little-endian bytes.

func Sum64Uint32Seed

func Sum64Uint32Seed(v uint32, seed uint64) uint64

Sum64Uint32Seed returns the XXH64 hash of v's four little-endian bytes under seed.

func Sum64Uint64

func Sum64Uint64(v uint64) uint64

Sum64Uint64 returns the XXH64 hash of v's eight little-endian bytes.

func Sum64Uint64Seed

func Sum64Uint64Seed(v, seed uint64) uint64

Sum64Uint64Seed returns the XXH64 hash of v's eight little-endian bytes under seed.

func Sum64Uint128

func Sum64Uint128(lo, hi uint64) uint64

Sum64Uint128 returns the XXH64 hash of the sixteen little-endian bytes of lo followed by hi.

Its body is written out rather than calling the seeded form with a zero: this is the longest of the six, and the seed's add is what put it two nodes over the inliner's budget.

func Sum64Uint128Seed

func Sum64Uint128Seed(lo, hi, seed uint64) uint64

Sum64Uint128Seed returns the XXH64 hash of the sixteen little-endian bytes of lo followed by hi, under seed.

Types

type Digest

type Digest struct {
	// contains filtered or unexported fields
}

Digest is a streaming XXH64. It implements hash.Hash64, encoding.BinaryMarshaler and encoding.BinaryUnmarshaler; the zero value is not usable, use New or NewSeed.

Its state is the four lanes, the byte count, and up to a block of input not yet absorbed. Every whole block Write can reach goes straight from the caller's slice to the kernel; only the pieces that do not fill a block are staged.

func New

func New() *Digest

New returns a Digest computing the unseeded XXH64.

func NewSeed

func NewSeed(seed uint64) *Digest

NewSeed returns a Digest computing XXH64 under seed.

func (*Digest) BlockSize

func (d *Digest) BlockSize() int

BlockSize returns the input block length: 32.

func (*Digest) MarshalBinary

func (d *Digest) MarshalBinary() ([]byte, error)

MarshalBinary implements encoding.BinaryMarshaler: the lanes, the byte count, the staged bytes and their number, and the seed is not among them -- it is recoverable from nothing else, so it travels in the lanes' initial values, which is enough because Reset is the only thing that needs it and a restored Digest is reset by restoring it again.

func (*Digest) Reset

func (d *Digest) Reset()

Reset returns the Digest to its initial state, keeping its seed.

func (*Digest) Size

func (d *Digest) Size() int

Size returns the hash length in bytes: 8.

func (*Digest) Sum

func (d *Digest) Sum(b []byte) []byte

Sum appends the big-endian hash to b, as hash.Hash specifies.

func (*Digest) Sum64

func (d *Digest) Sum64() uint64

Sum64 returns the hash of everything written so far. It does not change the state; more can be written afterwards.

func (*Digest) UnmarshalBinary

func (d *Digest) UnmarshalBinary(b []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler. It accepts only what MarshalBinary produced.

func (*Digest) Write

func (d *Digest) Write(b []byte) (int, error)

Write absorbs b. It never fails.

func (*Digest) WriteString

func (d *Digest) WriteString(s string) (int, error)

WriteString absorbs s without copying it.