omap

Documentation

Overview

Package omap defines a generic-based type for creating ordered maps. It exports a "Sorter" interface, allowing the creation of ordered maps with custom key and value types.

Specifically, omap supports ordered maps with keys of type string or asset.Pair and values of any type. See impl.go for examples.

## Motivation

Ensuring deterministic behavior is crucial in blockchain systems, as all nodes must reach a consensus on the state of the blockchain. Every action, given the same input, should consistently yield the same result. A divergence in state could impede the ability of nodes to validate a block, prohibiting the addition of the block to the chain, which could lead to chain halts.

Index

• type OrderedMap
  • func OrderedMap_Pair[V any](data map[asset.Pair]V) OrderedMap[asset.Pair, V]
  • func OrderedMap_String[V any](data map[string]V) OrderedMap[string, V]
  • func (om OrderedMap[K, V]) BuildFrom(data map[K]V, sorter Sorter[K]) OrderedMap[K, V]
  • func (om *OrderedMap[K, V]) Delete(key K)
  • func (om OrderedMap[K, V]) Has(key K) bool
  • func (om *OrderedMap[K, V]) Keys() []K
  • func (om OrderedMap[K, V]) Len() int
  • func (om OrderedMap[K, V]) Range() <-chan (K)
  • func (om *OrderedMap[K, V]) Set(key K, val V)
• type Sorter

Types

type OrderedMap

type OrderedMap[K comparable, V any] struct {
	Data map[K]V
	// contains filtered or unexported fields
}

OrderedMap is a wrapper struct around the built-in map that has guarantees about order because it sorts its keys with a custom sorter. It has a public API that mirrors that functionality of `map`. OrderedMap is built with generics, so it can hold various combinations of key-value types.

func OrderedMap_Pair

func OrderedMap_Pair[V any](
	data map[asset.Pair]V,
) OrderedMap[asset.Pair, V]

func OrderedMap_String

func OrderedMap_String[V any](data map[string]V) OrderedMap[string, V]

func (OrderedMap[K, V]) BuildFrom

func (om OrderedMap[K, V]) BuildFrom(
	data map[K]V, sorter Sorter[K],
) OrderedMap[K, V]

BuildFrom is a method that builds an OrderedMap from a given map and a sorter for the keys. This function is useful for creating new OrderedMap types with typed keys.

func (*OrderedMap[K, V]) Delete

func (om *OrderedMap[K, V]) Delete(key K)

Delete removes a key-value pair from the map if the key exists.

func (OrderedMap[K, V]) Has

func (om OrderedMap[K, V]) Has(key K) bool

Has checks whether a key exists in the map.

func (*OrderedMap[K, V]) Keys

func (om *OrderedMap[K, V]) Keys() []K

Keys returns a slice of the keys in their sorted order.

func (OrderedMap[K, V]) Len

func (om OrderedMap[K, V]) Len() int

Len returns the number of items in the map.

func (OrderedMap[K, V]) Range

func (om OrderedMap[K, V]) Range() <-chan (K)

Range returns a channel of keys in their sorted order. This allows you to iterate over the map in a deterministic order. Using a channel here makes it so that the iteration is done lazily rather loading the entire map (OrderedMap.data) into memory and then iterating.

func (*OrderedMap[K, V]) Set

func (om *OrderedMap[K, V]) Set(key K, val V)

Set adds a key-value pair to the map, or updates the value if the key already exists. It ensures the keys are ordered after the operation.

type Sorter

type Sorter[K any] interface {
	// Returns true if 'a' is less than 'b' Less needs to be defined for the
	// key type, K, to provide a comparison operation.
	Less(a K, b K) bool
}

Sorter is an interface used for ordering the keys in the OrderedMap.