hamap

Documentation

Overview

package hamap provides a collision-safe hashmap implementation which is more efficient than Go's native map for small datasets and allows allocation-free reseting efficiently reusing memory. Allocations are made only in case of rare hash collisions. Any custom hasher can be provided during initialization. By default, XXH3 from github.com/zeebo/xxh3 is used with seed 0. On an Apple M1 Max machine the efficiency breaking point compared to Go's native map is at around 192 items.

Index

• type Hasher
• type HasherXXH3
  • func (h *HasherXXH3[K]) Hash(k K) uint64
• type KeyInterface
• type Map
  • func New[K KeyInterface, V any](capacity int, hasher Hasher[K]) *Map[K, V]
  • func (m *Map[K, V]) Delete(key K)
  • func (m *Map[K, V]) Equal(mm *Map[K, V]) bool
  • func (m *Map[K, V]) Get(key K) (value V, ok bool)
  • func (m *Map[K, V]) GetFn(key K, fn func(*V)) (ok bool)
  • func (m *Map[K, V]) Len() int
  • func (m *Map[K, V]) Reset()
  • func (m *Map[K, V]) Set(key K, value V)
  • func (m *Map[K, V]) SetFn(key K, fn func(*V) V)
  • func (m *Map[K, V]) Values() (values []V)
  • func (m *Map[K, V]) Visit(fn func(key K, value V) (stop bool))
  • func (m *Map[K, V]) VisitAll(fn func(key K, value V))
• type Pair

Types

type Hasher

type Hasher[K KeyInterface] interface{ Hash(K) uint64 }

type HasherXXH3

type HasherXXH3[K KeyInterface] struct {
	Seed uint64
}

HasherXXH3 can be used to provide custom seeds during initialization.

func (*HasherXXH3[K]) Hash

func (h *HasherXXH3[K]) Hash(k K) uint64

Hash hashes k to a 64-bit hash value.

type KeyInterface

type KeyInterface interface{ string | []byte }

type Map

type Map[K KeyInterface, V any] struct {
	// contains filtered or unexported fields
}

Map is backed by a slice and utilizes binary search.

WARNING: In case of []byte typed keys the keys will be aliased and must remain immutable until the map is reset!

func New

func New[K KeyInterface, V any](
	capacity int,
	hasher Hasher[K],
) *Map[K, V]

New creates a new map instance.

func (*Map[K, V]) Delete

func (m *Map[K, V]) Delete(key K)

Delete deletes the key if it exists. Noop if the key doesn't exist.

func (*Map[K, V]) Equal

func (m *Map[K, V]) Equal(mm *Map[K, V]) bool

func (*Map[K, V]) Get

func (m *Map[K, V]) Get(key K) (value V, ok bool)

Get returns (value, true) if key exists, otherwise returns (zeroValue, false).

func (*Map[K, V]) GetFn

func (m *Map[K, V]) GetFn(key K, fn func(*V)) (ok bool)

GetFn calls fn providing a pointer to the value and returns true if key exists, otherwise calls fn providing nil and returns false.

func (*Map[K, V]) Len

func (m *Map[K, V]) Len() int

Len returns the number of stored key-value pairs.

func (*Map[K, V]) Reset

func (m *Map[K, V]) Reset()

Reset resets the map

func (*Map[K, V]) Set

func (m *Map[K, V]) Set(key K, value V)

Set associates key with value overwriting any existing associations.

WARNING: In case of []byte typed keys the map will alias keys! Make sure key remains immutable during the life-time of the map or until the map is reset.

func (*Map[K, V]) SetFn

func (m *Map[K, V]) SetFn(key K, fn func(*V) V)

SetFn calls fn(nil) if the key doesn't exist yet and associates the value returned by fn with the key. If the key already exists then fn is passed a pointer to the value already associated with the key.

WARNING: In case of []byte typed keys the map will alias keys! Make sure key remains immutable during the life-time of the map or until the map is reset.

func (*Map[K, V]) Values

func (m *Map[K, V]) Values() (values []V)

Values returns all map values

func (*Map[K, V]) Visit

func (m *Map[K, V]) Visit(fn func(key K, value V) (stop bool))

Visit calls fn for every stored key-value pair. Returns immediately if fn returns true.

func (*Map[K, V]) VisitAll

func (m *Map[K, V]) VisitAll(fn func(key K, value V))

VisitAll calls fn for every stored key-value pair.

type Pair

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

Pair is a key-value pair.