README
¶
ordered 
Package ordered implements data structures which maintain consistent ordering
of inserted elements.
Note
This package is an experiment to handle use cases where regular Go maps are beneficial, but deterministic iteration order is also desired. No guarantees are made about the stability or performance characteristics of this package.
Documentation
¶
Overview ¶
Package ordered implements data structures which maintain consistent ordering of inserted elements.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Less ¶
func Less[K constraints.Ordered](a, b K) bool
Less is a comparison function for key types which are ordered. It is a convenience function for comparing primitive types with NewMap.
Types ¶
type KeyValue ¶
type KeyValue[K comparable, V any] struct { Key K Value V }
A KeyValue is a key/value pair produced by a MapIterator or Map.Range call.
type Map ¶
type Map[K comparable, V any] struct { // contains filtered or unexported fields }
A Map is like a map[K]V, but offers deterministic iteration order by applying a comparison function against all keys. A Map must be constructed using NewMap or its methods will panic.
Maps are not safe for concurrent use.
Example ¶
package main
import (
"fmt"
"github.com/mdlayher/ordered"
)
func main() {
// Create a map of string keys and integer elements, ordered by lexical
// comparison of the string keys.
m := ordered.NewMap[string, int](ordered.Less[string])
m.Set("foo", 1)
m.Set("bar", 2)
m.Set("baz", 3)
// Modify some elements of the map.
m.Set("foo", 10)
m.Delete("bar")
// Look up an element that does not exist.
if v, ok := m.TryGet("notfound"); ok {
fmt.Printf("found notfound: %d!\n", v)
}
// Iterate over the elements of the map, in order. Read-only accesses are
// permitted while an iterator is open, but writes will result in a panic
// until mi.Close is called. For more basic iteration, see Map.Range.
mi := m.Iter()
defer mi.Close()
fmt.Println("length:", m.Len())
for kv := mi.Next(); kv != nil; kv = mi.Next() {
fmt.Printf("- %s: %d\n", kv.Key, kv.Value)
}
}
Output: length: 2 - baz: 3 - foo: 10
func NewMap ¶
func NewMap[K comparable, V any](less func(a, b K) bool) *Map[K, V]
NewMap creates a *Map[K, V] which uses the comparison function less to order the keys in the map. less must not be nil or NewMap will panic. For primitive types, Less can be used as a comparison function.
func (*Map[K, V]) Delete ¶
func (m *Map[K, V]) Delete(k K)
Delete deletes the value for a given key K.
func (*Map[K, V]) Get ¶
func (m *Map[K, V]) Get(k K) V
Get gets the value V for a given key K, returning the zero value of V if K is not found.
func (*Map[K, V]) Iter ¶
func (m *Map[K, V]) Iter() *MapIterator[K, V]
Iter produces a MapIterator which allows fine-grained iteration over a Map.
func (*Map[K, V]) Range ¶
Range produces a slice of all KeyValue pairs from Map for use in a for range loop. See Map.Iter for more fine-grained iteration control.
func (*Map[K, V]) Reset ¶
func (m *Map[K, V]) Reset()
Reset clears the underlying storage for a Map by removing all elements, enabling the allocated capacity to be reused.
type MapIterator ¶
type MapIterator[K comparable, V any] struct { // contains filtered or unexported fields }
A MapIterator is an iteration cursor over a Map. A MapIterator must be constructed using Map.Iter or its methods will panic.
When a MapIterator is created, any methods which write to a Map (Delete, Reset, Set) will panic. Reads during iteration are permitted. To complete iteration and permit further writes, call MapIterator.Close. Multiple MapIterators can be used at once over the same Map, but write methods will panic until all MapIterators are closed. After a call to Close, the MapIterator can no longer be used.
For more basic iteration use cases, see Map.Range.
func (*MapIterator[K, V]) Close ¶
func (mi *MapIterator[K, V]) Close()
Close releases a MapIterator's resources, enabling further writes to a Map.
func (*MapIterator[K, V]) Next ¶
func (mi *MapIterator[K, V]) Next() *KeyValue[K, V]
Next returns the next KeyValue pair from a Map. If Next returns nil, no more KeyValue pairs are present. Next is intended to be used in a for loop, in the format:
mi := m.Iter()
defer mi.Close()
for kv := mi.Next(); kv != nil; kv = mi.Next() {
// use kv
}
Source Files