cmap

Documentation

Overview

Package cmap contains an implementation of a canonicalizing map.

Index

• func Comparator[C comparable]() func(C, C) bool
• func Equal[K, V any](a, b Map[K, V], comparator func(V, V) bool) bool
• type Entry
• type Map
  • func New[K any, C comparable, V any](mapper Mapper[K, C]) Map[K, V]
  • func NewIdentity[K comparable, V any]() Map[K, V]
  • func NewOf[K any, C comparable, V any](mapper Mapper[K, C], args ...any) Map[K, V]
• type Mapper

Functions

func Comparator

func Comparator[C comparable]() func(C, C) bool

Comparator returns a comparator for comparable types.

func Equal

func Equal[K, V any](a, b Map[K, V], comparator func(V, V) bool) bool

Equal returns true if the two maps have an identical canonical keyset and the comparator function returns true for each pairwise key-value mapping between the two maps.

Types

type Entry

type Entry[K, V any] struct {
	Key   K
	Value V
}

An Entry in a Map. Note that the Key type is not necessarily comparable.

type Map

type Map[K any, V any] interface {
	// CopyInto populates the destination with the contents of the map.
	CopyInto(dest Map[K, V])

	// Delete removes a key from the map.
	Delete(key K)

	// Entries returns the entries of the map as a slice. Note that
	// the iteration order is not stable.
	Entries() []Entry[K, V]

	// Get returns the value associated with the canonical form of the
	// key.
	Get(key K) (_ V, ok bool)

	// GetZero returns the value associated with the canonical form of
	// the key or returns a zero value.
	GetZero(key K) V

	// Len returns the number of entries in the Map.
	Len() int

	// Match is similar to Get, except that it returns the original key
	// used to insert the entry. This can be used by callers to
	// determine if the requested and original keys are an exact match.
	Match(key K) (_ K, _ V, ok bool)

	// Put adds a new mapping. Any error returned by the Mapper will be
	// returned.
	Put(key K, value V)

	// Range invokes the callback for each entry in the Map. Range will
	// stop at the first error returned by the callback. If the callback
	// never returns an error, neither will Range.
	Range(func(k K, v V) error) error
}

The Map type uses a canonical representation of a key when storing or retrieving values. This allows key types which are not comparable to be used.

A Map is not internally synchronized.

func New

func New[K any, C comparable, V any](mapper Mapper[K, C]) Map[K, V]

New constructs a canonicalizing Map. The K type must implement TextKey if the MarshalJSON or UnmarshalJSON methods are to be called.

func NewIdentity

func NewIdentity[K comparable, V any]() Map[K, V]

NewIdentity returns a Map for comparable keys. A basic map type is recommended unless compatibility with the Map interface is necessary.

func NewOf

func NewOf[K any, C comparable, V any](mapper Mapper[K, C], args ...any) Map[K, V]

NewOf is a helper for testing. It requires an even number of varargs of alternating key and value types. This function will panic, so it is not suitable for production code.

type Mapper

type Mapper[K, C any] func(K) C

A Mapper provider a canonical mapping from an arbitrary type to a comparable value.