deephash

Documentation

Overview

Package deephash hashes a Go value recursively, in a predictable order, without looping. The hash is only valid within the lifetime of a program. Users should not store the hash on disk or send it over the network. The hash is sufficiently strong and unique such that Hash(&x) == Hash(&y) is an appropriate replacement for x == y.

The definition of equality is identical to reflect.DeepEqual except:

• Floating-point values are compared based on the raw bits, which means that NaNs (with the same bit pattern) are treated as equal.
• time.Time are compared based on whether they are the same instant in time and also in the same zone offset. Monotonic measurements and zone names are ignored as part of the hash.
• netip.Addr are compared based on a shallow comparison of the struct.

WARNING: This package, like most of the tailscale.com Go module, should be considered Tailscale-internal; we make no API promises.

Index

• func HasherForType[T any](opts ...Option) func(*T) Sum
• func Update[T any](last *Sum, v *T) (changed bool)
• type Option
  • func ExcludeFields[T any](fields ...string) Option
  • func IncludeFields[T any](fields ...string) Option
• type Sum
  • func Hash[T any](v *T) Sum
  • func (s Sum) AppendTo(b []byte) []byte
  • func (s Sum) String() string

Functions

func HasherForType

func HasherForType[T any](opts ...Option) func(*T) Sum

HasherForType returns a hash that is specialized for the provided type.

HasherForType panics if the opts are invalid for the provided type.

Currently, at most one option can be provided (IncludeFields or ExcludeFields) and its type must match the type of T. Those restrictions may be removed in the future, along with documentation about their precedence when combined.

func Update

func Update[T any](last *Sum, v *T) (changed bool)

Update sets last to the hash of v and reports whether its value changed.

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option is an optional argument to HasherForType.

func ExcludeFields

func ExcludeFields[T any](fields ...string) Option

ExcludeFields returns an option that modifies the hashing for T to include all struct fields of T except those provided in fields.

T must be a struct type, and must match the type of the value passed to HasherForType.

func IncludeFields

func IncludeFields[T any](fields ...string) Option

IncludeFields returns an option that modifies the hashing for T to only include the named struct fields.

T must be a struct type, and must match the type of the value passed to HasherForType.

type Sum

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

Sum is an opaque checksum type that is comparable.

func Hash

func Hash[T any](v *T) Sum

Hash returns the hash of v.

func (Sum) AppendTo

func (s Sum) AppendTo(b []byte) []byte

AppendTo appends the string encoding of this sum (as returned by the String method) to the provided byte slice and returns the extended buffer.

func (Sum) String

func (s Sum) String() string