Involved Source Files Package maphash provides hash functions on byte sequences and comparable values.
These hash functions are intended to be used to implement hash tables or
other data structures that need to map arbitrary strings or byte
sequences to a uniform distribution on unsigned 64-bit integers.
Each different instance of a hash table or data structure should use its own [Seed].
The hash functions are not cryptographically secure.
(See crypto/sha256 and crypto/sha512 for cryptographic use.)maphash_runtime.go
Code Examples
package main
import (
"fmt"
"hash/maphash"
)
func main() {
// The zero Hash value is valid and ready to use; setting an
// initial seed is not necessary.
var h maphash.Hash
// Add a string to the hash, and print the current hash value.
h.WriteString("hello, ")
fmt.Printf("%#x\n", h.Sum64())
// Append additional data (in the form of a byte array).
h.Write([]byte{'w', 'o', 'r', 'l', 'd'})
fmt.Printf("%#x\n", h.Sum64())
// Reset discards all data previously added to the Hash, without
// changing its seed.
h.Reset()
// Use SetSeed to create a new Hash h2 which will behave
// identically to h.
var h2 maphash.Hash
h2.SetSeed(h.Seed())
h.WriteString("same")
h2.WriteString("same")
fmt.Printf("%#x == %#x\n", h.Sum64(), h2.Sum64())
}
Package-Level Type Names (total 2, both are exported)
/* sort exporteds by: | */
A Hash computes a seeded hash of a byte sequence.
The zero Hash is a valid Hash ready to use.
A zero Hash chooses a random seed for itself during
the first call to a Reset, Write, Seed, or Sum64 method.
For control over the seed, use SetSeed.
The computed hash values depend only on the initial seed and
the sequence of bytes provided to the Hash object, not on the way
in which the bytes are provided. For example, the three sequences
h.Write([]byte{'f','o','o'})
h.WriteByte('f'); h.WriteByte('o'); h.WriteByte('o')
h.WriteString("foo")
all have the same effect.
Hashes are intended to be collision-resistant, even for situations
where an adversary controls the byte sequences being hashed.
A Hash is not safe for concurrent use by multiple goroutines, but a Seed is.
If multiple goroutines must compute the same seeded hash,
each can declare its own Hash and call SetSeed with a common Seed. // unflushed byte buffer // number of unflushed bytes // initial seed used for this hash // current hash of all flushed bytes BlockSize returns h's block size. Reset discards all bytes added to h.
(The seed remains the same.) Seed returns h's seed value. SetSeed sets h to use seed, which must have been returned by [MakeSeed]
or by another [Hash.Seed] method.
Two [Hash] objects with the same seed behave identically.
Two [Hash] objects with different seeds will very likely behave differently.
Any bytes added to h before this call will be discarded. Size returns h's hash value size, 8 bytes. Sum appends the hash's current 64-bit value to b.
It exists for implementing [hash.Hash].
For direct calls, it is more efficient to use [Hash.Sum64]. Sum64 returns h's current 64-bit value, which depends on
h's seed and the sequence of bytes added to h since the
last call to [Hash.Reset] or [Hash.SetSeed].
All bits of the Sum64 result are close to uniformly and
independently distributed, so it can be safely reduced
by using bit masking, shifting, or modular arithmetic. Write adds b to the sequence of bytes hashed by h.
It always writes all of b and never fails; the count and error result are for implementing [io.Writer]. WriteByte adds b to the sequence of bytes hashed by h.
It never fails; the error result is for implementing [io.ByteWriter]. WriteString adds the bytes of s to the sequence of bytes hashed by h.
It always writes all of s and never fails; the count and error result are for implementing [io.StringWriter].(*Hash) float64(f float64) precondition: buffer is full. initSeed seeds the hash if necessary.
initSeed is called lazily before any operation that actually uses h.seed/h.state.
Note that this does not include Write/WriteByte/WriteString in the case
where they only add to h.buf. (If they write too much, they call h.flush,
which does call h.initSeed.)
*Hash : hash.Hash
*Hash : hash.Hash64
*Hash : crypto/internal/fips140.Hash
*Hash : internal/bisect.Writer
*Hash : io.ByteWriter
*Hash : io.StringWriter
*Hash : io.Writer
*Hash : crypto/tls.transcriptHash
*Hash : golang.org/x/net/http2.stringWriter
*Hash : net/http.http2stringWriter
func WriteComparable[T](h *Hash, x T)
func writeComparable[T](h *Hash, v T)
A Seed is a random value that selects the specific hash function
computed by a [Hash]. If two Hashes use the same Seeds, they
will compute the same hash values for any given input.
If two Hashes use different Seeds, they are very likely to compute
distinct hash values for any given input.
A Seed must be initialized by calling [MakeSeed].
The zero seed is uninitialized and not valid for use with [Hash]'s SetSeed method.
Each Seed value is local to a single process and cannot be serialized
or otherwise recreated in a different process.suint64
func MakeSeed() Seed
func (*Hash).Seed() Seed
func Bytes(seed Seed, b []byte) uint64
func Comparable[T](seed Seed, v T) uint64
func String(seed Seed, s string) uint64
func (*Hash).SetSeed(seed Seed)
func comparableHash[T](v T, seed Seed) uint64
var golang.org/x/tools/go/types/typeutil.theSeed
Package-Level Functions (total 14, in which 5 are exported)
Bytes returns the hash of b with the given seed.
Bytes is equivalent to, but more convenient and efficient than:
var h Hash
h.SetSeed(seed)
h.Write(b)
return h.Sum64()
Type Parameters:
T: comparable Comparable returns the hash of comparable value v with the given seed
such that Comparable(s, v1) == Comparable(s, v2) if v1 == v2.
If v != v, then the resulting hash is randomly distributed.
MakeSeed returns a new random seed.
String returns the hash of s with the given seed.
String is equivalent to, but more convenient and efficient than:
var h Hash
h.SetSeed(seed)
h.WriteString(s)
return h.Sum64()
Type Parameters:
T: comparable WriteComparable adds x to the data hashed by h.
Type Parameters:
T: comparable escapeForHash forces v to be on the heap, if v contains a
non-string pointer. We cannot hash pointers to local variables,
as the address of the local variable might change on stack growth.
Strings are okay as the hash depends on only the content, not
the pointer.
This is essentially
if hasNonStringPointers(T) { abi.Escape(v) }
Implemented as a compiler intrinsic.
Package-Level Constants (total 2, neither is exported)
bufSize is the size of the Hash write buffer.
The buffer ensures that writes depend only on the sequence of bytes,
not the sequence of WriteByte/Write/WriteString calls,
by always calling rthash with a full buffer (except for the tail).