orderedmap

README

orderedmap

A generic, thread-safe ordered map for Go that preserves insertion order using container/list.

Installation

go get github.com/winebarrel/orderedmap

Requires Go 1.23+.

Usage

package main

import (
	"fmt"
	"slices"

	"github.com/winebarrel/orderedmap"
)

func main() {
	om := orderedmap.New[string, any]()

	om.Set("foo", "bar")
	om.Set("zoo", 100)
	om.Set("baz", true)

	fmt.Println(om)
	//=> *orderedmap.Map[string,interface {}][foo:bar zoo:100 baz:true]

	// Get a value
	fmt.Println(om.Get("foo"))
	//=> bar

	// Get a value with existence check
	v, ok := om.GetOk("foo")
	fmt.Println(v, ok)
	//=> bar true

	// Iterate over key-value pairs in insertion order
	for k, v := range om.All() {
		fmt.Println(k, v)
	}
	//=> foo bar
	//   zoo 100
	//   baz true

	// Iterate over keys
	for k := range om.Keys() {
		fmt.Println(k)
	}

	// Iterate over values
	for v := range om.Values() {
		fmt.Println(v)
	}

	// Push moves an existing key to the back
	om.Push("foo", "new_bar")
	for k, v := range om.All() {
		fmt.Println(k, v)
	}
	//=> zoo 100
	//   baz true
	//   foo new_bar

	// Get all key-value pairs as a slice
	pairs := om.Entries()
	fmt.Println(pairs)
	//=> [{zoo 100} {baz true} {foo new_bar}]

	// Delete a key
	om.Delete("zoo")

	// Get the number of entries
	fmt.Println(om.Len())
	//=> 2

	// Clear all entries
	om.Clear()

	// Create from an iterator
	om2 := orderedmap.From(slices.All([]string{"foo", "bar", "baz"}))
	fmt.Println(om2)
	//=> *orderedmap.Map[int,string][0:foo 1:bar 2:baz]

	// Sort by key
	om3 := orderedmap.New[string, int]()
	om3.Set("banana", 2)
	om3.Set("apple", 1)
	om3.Set("cherry", 3)
	orderedmap.SortByKey(om3)
	for k, v := range om3.All() {
		fmt.Println(k, v)
	}
	//=> apple 1
	//   banana 2
	//   cherry 3
}

JSON Marshal / Unmarshal

package main

import (
	"encoding/json"
	"fmt"

	"github.com/winebarrel/orderedmap"
)

func main() {
	// Marshal: preserves insertion order
	om := orderedmap.New[string, any]()
	om.Set("z", 3)
	om.Set("a", 1)
	om.Set("m", 2)

	b, _ := json.Marshal(om)
	fmt.Println(string(b))
	//=> {"z":3,"a":1,"m":2}

	// Unmarshal: preserves key order from JSON
	om2 := orderedmap.New[string, any]()
	json.Unmarshal([]byte(`{"z":3,"a":1,"m":2}`), om2)

	for k, v := range om2.All() {
		fmt.Println(k, v)
	}
	//=> z 3
	//   a 1
	//   m 2
}

Documentation

Index

• func SortByKey[K cmp.Ordered, V any](om *Map[K, V])
• func SortByValue[K comparable, V cmp.Ordered](om *Map[K, V])
• func SortFunc[K comparable, V any](om *Map[K, V], cmpFn func(a, b Pair[K, V]) int)
• type Map
  • func From[K comparable, V any](seq iter.Seq2[K, V]) *Map[K, V]
  • func New[K comparable, V any]() *Map[K, V]
  • func SortedByKey[K cmp.Ordered, V any](om *Map[K, V]) *Map[K, V]
  • func SortedByValue[K comparable, V cmp.Ordered](om *Map[K, V]) *Map[K, V]
  • func SortedFunc[K comparable, V any](om *Map[K, V], cmpFn func(Pair[K, V], Pair[K, V]) int) *Map[K, V]
  • func (om *Map[K, V]) All() iter.Seq2[K, V]
  • func (om *Map[K, V]) Clear()
  • func (om *Map[K, V]) Clone() *Map[K, V]
  • func (om *Map[K, V]) Delete(k K) V
  • func (om *Map[K, V]) DeleteOk(k K) (V, bool)
  • func (om *Map[K, V]) Entries() []Pair[K, V]
  • func (om *Map[K, V]) Get(k K) V
  • func (om *Map[K, V]) GetOk(k K) (V, bool)
  • func (om *Map[K, V]) Keys() iter.Seq[K]
  • func (om *Map[K, V]) Len() int
  • func (om *Map[K, V]) MarshalJSON() ([]byte, error)
  • func (om *Map[K, V]) Push(k K, v V)
  • func (om *Map[K, V]) Set(k K, v V)
  • func (om *Map[K, V]) String() string
  • func (om *Map[K, V]) UnmarshalJSON(data []byte) error
  • func (om *Map[K, V]) Values() iter.Seq[V]
• type Pair

Functions

func SortByKey

func SortByKey[K cmp.Ordered, V any](om *Map[K, V])

func SortByValue

func SortByValue[K comparable, V cmp.Ordered](om *Map[K, V])

func SortFunc

func SortFunc[K comparable, V any](om *Map[K, V], cmpFn func(a, b Pair[K, V]) int)

Types

type Map

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

func From

func From[K comparable, V any](seq iter.Seq2[K, V]) *Map[K, V]

func New

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

func SortedByKey

func SortedByKey[K cmp.Ordered, V any](om *Map[K, V]) *Map[K, V]

func SortedByValue

func SortedByValue[K comparable, V cmp.Ordered](om *Map[K, V]) *Map[K, V]

func SortedFunc

func SortedFunc[K comparable, V any](om *Map[K, V], cmpFn func(Pair[K, V], Pair[K, V]) int) *Map[K, V]

func (*Map[K, V]) All

func (om *Map[K, V]) All() iter.Seq2[K, V]

func (*Map[K, V]) Clear

func (om *Map[K, V]) Clear()

func (*Map[K, V]) Clone

func (om *Map[K, V]) Clone() *Map[K, V]

func (*Map[K, V]) Delete

func (om *Map[K, V]) Delete(k K) V

func (*Map[K, V]) DeleteOk

func (om *Map[K, V]) DeleteOk(k K) (V, bool)

func (*Map[K, V]) Entries

func (om *Map[K, V]) Entries() []Pair[K, V]

func (*Map[K, V]) Get

func (om *Map[K, V]) Get(k K) V

func (*Map[K, V]) GetOk

func (om *Map[K, V]) GetOk(k K) (V, bool)

func (*Map[K, V]) Keys

func (om *Map[K, V]) Keys() iter.Seq[K]

func (*Map[K, V]) Len

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

func (*Map[K, V]) MarshalJSON

func (om *Map[K, V]) MarshalJSON() ([]byte, error)

func (*Map[K, V]) Push

func (om *Map[K, V]) Push(k K, v V)

func (*Map[K, V]) Set

func (om *Map[K, V]) Set(k K, v V)

func (*Map[K, V]) String

func (om *Map[K, V]) String() string

func (*Map[K, V]) UnmarshalJSON

func (om *Map[K, V]) UnmarshalJSON(data []byte) error

func (*Map[K, V]) Values

func (om *Map[K, V]) Values() iter.Seq[V]

type Pair

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