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]
}

Transform

package main

import (
	"fmt"

	"github.com/winebarrel/orderedmap"
)

func main() {
	om := orderedmap.New[string, int]()
	om.Set("foo", 1)
	om.Set("bar", 2)
	om.Set("baz", 3)

	// Transform returns an iterator of transformed values
	for s := range orderedmap.Transform(om, func(k string, v int) string {
		return fmt.Sprintf("%s=%d", k, v)
	}) {
		fmt.Println(s)
	}
	//=> foo=1
	//   bar=2
	//   baz=3

	// TransformSlice returns a slice of transformed values
	ss := orderedmap.TransformSlice(om, func(k string, v int) string {
		return fmt.Sprintf("%s=%d", k, v)
	})
	fmt.Println(ss)
	//=> [foo=1 bar=2 baz=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 Transform[K comparable, V any, R any](om *Map[K, V], f func(k K, v V) R) iter.Seq[R]
• func TransformSlice[K comparable, V any, R any](om *Map[K, V], f func(k K, v V) R) []R
• 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 (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]) CollectKeys() []K
  • func (om *Map[K, V]) CollectValues() []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 Transform

func Transform[K comparable, V any, R any](om *Map[K, V], f func(k K, v V) R) iter.Seq[R]

func TransformSlice

func TransformSlice[K comparable, V any, R any](om *Map[K, V], f func(k K, v V) R) []R

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 (*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]) CollectKeys

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

func (*Map[K, V]) CollectValues

func (om *Map[K, V]) CollectValues() []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
}