package anyunique

import "cuelang.org/go/internal/anyunique"

Package anyunique provides canonicalization of values under a caller-defined equivalence relation.

A Store holds a set of unique values of a specific type T. Calling Store.Make with two values that are equivalent according to the provided Hasher returns Handle values that are identical. Handle is a lightweight wrapper around the canonical value; use [U.Get] to obtain the underlying T.

The zero Handle represents the zero value of T. Make returns the zero Handle when called with the zero value of T: it will never try to hash the zero value.

Store.WriteHash writes a short representation of a canonicalized value to a maphash.Hash. It is useful when hashing structures that themselves contain canonicalized values, avoiding re-hashing the full value graph.

NOTE this package assumes that T values are treated as immutable. That is, after calling Store.Make a value must not change.

Index ¶

• type Handle
• func (u Handle[T]) Value() T
• type Hasher
• type Store
• func New[T comparable, H Hasher[T]](h H) *Store[T, H]
• func (s *Store[T, H]) Make(x T) Handle[T]
• func (s *Store[T, H]) WriteHash(h *maphash.Hash, x Handle[T])

Types ¶

type Handle ¶

type Handle[T comparable] struct {
	// contains filtered or unexported fields
}

Handle represents a unique value of type T. If two values of type Handle[T] originating from the same Store compare equal, they are guaranteed to be equal according to the equality criteria that the store was created with.

func (Handle[T]) Value ¶

func (u Handle[T]) Value() T

Value returns the actual value held in u.

type Hasher ¶

type Hasher[T any] interface {
	Hash(*maphash.Hash, T)
	Equal(x, y T) bool
}

A Hasher defines a hash function and an equivalence relation over values of type T.

Hash must write a hash of its argument to the provided *maphash.Hash, and Equal must report whether two values are equivalent. Hash and Equal must be consistent: if Equal(x, y) is true then Hash must produce the same output for x and y.

Note: this is an exact copy of the proposed new Hasher interface for the Go API. See https://go-review.googlesource.com/c/go/+/657296/11/src/hash/maphash/hasher.go

TODO alias this to maphash.Hasher when the above CL lands.

type Store ¶

type Store[T comparable, H Hasher[T]] struct {
	// contains filtered or unexported fields
}

Store holds a set of unique values of type T.

func New ¶

func New[T comparable, H Hasher[T]](h H) *Store[T, H]

New returns a new store holding a set of unique values of type T, using h to determine whether values are the same.

The equivalence relation and hash are supplied by the given Hasher.

func (*Store[T, H]) Make ¶

func (s *Store[T, H]) Make(x T) Handle[T]

Make returns a unique value u such that u.Get() is equal to x according to the equality criteria defined by the store.

It is assumed that values will not change after passing to Make: the caller must take care to preserve immutability.

func (*Store[T, H]) WriteHash ¶

func (s *Store[T, H]) WriteHash(h *maphash.Hash, x Handle[T])

WriteHash writes a short representation of x to h. This allows callers to avoid hashing an tree of values when hashing a value that itself contains other Handle[T] items.

Source Files ¶

unique.go