stablemap

README

Stable Map

Stable Map is a map that provides ordered, deterministic iteration of key-value pairs. It's concurrency safe. Insertion order of key-value pairs is preserved. It marshals and unmarshals itself into deterministic bytes, using MessagePack.

Stable Map is especially useful for equality comparison.

Getting Started

package main

import (
	"fmt"

	smap "github.com/sean9999/go-stable-map"
)

func main() {

	m := smap.New[string, string]()

	m.Set("foo", "bar")
	m.Set("bing", "bat")

	//	dump the map 10 times. See that the order is always the same
	for range 10 {
		for k, v := range m.Entries() {
			fmt.Printf("%s:\t%s\n", k, v)
		}
		
		//	see that the binary representation is always the same
		bin, _ := m.MarshalBinary()
		fmt.Printf("hex:\t%x\n\n", bin)
	}

}

Documentation

Index

• type ActiveMap
  • func NewActiveMap[K comparable, V any]() *ActiveMap[K, V]
  • func (am *ActiveMap[K, V]) Delete(k K) error
  • func (am *ActiveMap[K, V]) Set(k K, v V) error
• type Result
• type StableMap
  • func From[K comparable, V any](m map[K]V) *StableMap[K, V]
  • func New[K comparable, V any]() *StableMap[K, V]
  • func (sm *StableMap[K, V]) AsMap() map[K]V
  • func (sm *StableMap[K, V]) Clone() *StableMap[K, V]
  • func (sm *StableMap[K, V]) Delete(k K) error
  • func (sm *StableMap[K, V]) DeleteAt(i int)
  • func (sm *StableMap[K, V]) Entries() iter.Seq2[K, V]
  • func (sm *StableMap[K, V]) Get(k K) (V, bool)
  • func (sm *StableMap[K, V]) GetAt(i int) V
  • func (sm *StableMap[K, V]) Import(b *StableMap[K, V])
  • func (sm *StableMap[K, V]) Incorporate(m map[K]V)
  • func (sm *StableMap[K, V]) IndexOf(key K) int
  • func (sm *StableMap[K, V]) Length() int
  • func (sm *StableMap[K, V]) MarshalBinary() ([]byte, error)
  • func (sm StableMap[K, V]) MarshalJSON() ([]byte, error)
  • func (sm *StableMap[K, V]) Set(key K, val V) error
  • func (sm *StableMap[K, V]) UnmarshalBinary(p []byte) error
  • func (sm *StableMap[K, V]) UnmarshalJSON(b []byte) error
  • func (sm *StableMap[K, V]) Unshift(key K, val V)

Types

type ActiveMap

type ActiveMap[K comparable, V any] struct {
	*StableMap[K, V]
	Events chan Result[K, V]
}

ActiveMap is a StableMap that emits events when it mutates.

func NewActiveMap

func NewActiveMap[K comparable, V any]() *ActiveMap[K, V]

NewActiveMap instantiates a new ActiveMap

func (*ActiveMap[K, V]) Delete

func (am *ActiveMap[K, V]) Delete(k K) error

func (*ActiveMap[K, V]) Set

func (am *ActiveMap[K, V]) Set(k K, v V) error

type Result

type Result[K comparable, V any] struct {
	Action string
	Key    K
	OldVal V
	NewVal V
	Msg    string
}

A Result is emitted whenever an ActiveMap mutates

type StableMap

type StableMap[K comparable, V any] struct {
	*sync.RWMutex
	// contains filtered or unexported fields
}

StableMap is a map whose keys are ordered, and whose operations are concurrency safe and which marshals itself into predictable, deterministic bytes.

func From

func From[K comparable, V any](m map[K]V) *StableMap[K, V]

func New

func New[K comparable, V any]() *StableMap[K, V]

func (*StableMap[K, V]) AsMap

func (sm *StableMap[K, V]) AsMap() map[K]V

func (*StableMap[K, V]) Clone

func (sm *StableMap[K, V]) Clone() *StableMap[K, V]

Clone performs a safe clone

func (*StableMap[K, V]) Delete

func (sm *StableMap[K, V]) Delete(k K) error

Delete deletes an element by key

func (*StableMap[K, V]) DeleteAt

func (sm *StableMap[K, V]) DeleteAt(i int)

delete the element at a specific index, or panic

func (*StableMap[K, V]) Entries

func (sm *StableMap[K, V]) Entries() iter.Seq2[K, V]

Entries provides stable "range over" iteration

func (*StableMap[K, V]) Get

func (sm *StableMap[K, V]) Get(k K) (V, bool)

get a value and a bolean indicating if there actually was something there

func (*StableMap[K, V]) GetAt

func (sm *StableMap[K, V]) GetAt(i int) V

get the element at a particular index, or panic

func (*StableMap[K, V]) Import

func (sm *StableMap[K, V]) Import(b *StableMap[K, V])

Import imports another StableMap

func (*StableMap[K, V]) Incorporate

func (sm *StableMap[K, V]) Incorporate(m map[K]V)

Incorporate incoporates a map, merging it with existing entries

func (*StableMap[K, V]) IndexOf

func (sm *StableMap[K, V]) IndexOf(key K) int

get the index value of a particular key

func (*StableMap[K, V]) Length

func (sm *StableMap[K, V]) Length() int

func (*StableMap[K, V]) MarshalBinary

func (sm *StableMap[K, V]) MarshalBinary() ([]byte, error)

func (StableMap[K, V]) MarshalJSON

func (sm StableMap[K, V]) MarshalJSON() ([]byte, error)

func (*StableMap[K, V]) Set

func (sm *StableMap[K, V]) Set(key K, val V) error

Set adds or updates an element in a thread-safe manner

func (*StableMap[K, V]) UnmarshalBinary

func (sm *StableMap[K, V]) UnmarshalBinary(p []byte) error

func (*StableMap[K, V]) UnmarshalJSON

func (sm *StableMap[K, V]) UnmarshalJSON(b []byte) error

func (*StableMap[K, V]) Unshift

func (sm *StableMap[K, V]) Unshift(key K, val V)

place this pair at the head