orderedmap
A generic, thread-safe ordered map for Go that preserves insertion order using linkedlist.
Installation
go get github.com/winebarrel/orderedmap/v2
Requires Go 1.27+.
Usage
package main
import (
"fmt"
"slices"
"github.com/winebarrel/orderedmap/v2"
)
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
// Check if a key exists
fmt.Println(om.Has("foo"))
//=> 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
// Len returns 0 for a nil map
var nilMap *orderedmap.Map[string, any]
fmt.Println(nilMap.Len())
//=> 0
// 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]
}
Filter
package main
import (
"fmt"
"github.com/winebarrel/orderedmap/v2"
)
func main() {
om := orderedmap.New[string, int]()
om.Set("foo", 1)
om.Set("bar", 2)
om.Set("baz", 3)
// Filter returns a new map containing only the entries that satisfy the predicate
om2 := om.Filter(func(k string, v int) bool {
return v != 2
})
fmt.Println(om2)
//=> *orderedmap.Map[string,int][foo:1 baz:3]
}
RenameKey
package main
import (
"fmt"
"github.com/winebarrel/orderedmap/v2"
)
func main() {
om := orderedmap.New[string, int]()
om.Set("foo", 1)
om.Set("bar", 2)
om.Set("baz", 3)
// RenameKey changes a key while keeping its position
ok := om.RenameKey("bar", "zoo")
fmt.Println(ok, om)
//=> true *orderedmap.Map[string,int][foo:1 zoo:2 baz:3]
// RenameKey returns false if the old key is missing or the new key already exists
ok = om.RenameKey("foo", "baz")
fmt.Println(ok, om)
//=> false *orderedmap.Map[string,int][foo:1 zoo:2 baz:3]
}
Transform
package main
import (
"fmt"
"strings"
"github.com/winebarrel/orderedmap/v2"
)
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 om.Transform(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 := om.TransformSlice(func(k string, v int) string {
return fmt.Sprintf("%s=%d", k, v)
})
fmt.Println(ss)
//=> [foo=1 bar=2 baz=3]
// TransformMap returns a new map with transformed keys and values
om2 := om.TransformMap(func(k string, v int) (string, string) {
return strings.ToUpper(k), fmt.Sprintf("%d", v*10)
})
fmt.Println(om2)
//=> *orderedmap.Map[string,string][FOO:10 BAR:20 BAZ:30]
// If keys collide, the result follows Set:
// the entry keeps the position of the first key and the value of the last one
om3 := om.TransformMap(func(k string, v int) (string, int) {
return k[:1], v
})
fmt.Println(om3)
//=> *orderedmap.Map[string,int][f:1 b:3]
}
JSON Marshal / Unmarshal
package main
import (
"encoding/json"
"fmt"
"github.com/winebarrel/orderedmap/v2"
)
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
}
encoding/json/v2
Map implements MarshalerTo and
UnmarshalerFrom, so encoding/json/v2
options (indentation, HTML escaping, ...) are honored.
package main
import (
"encoding/json/jsontext"
json "encoding/json/v2"
"fmt"
"github.com/winebarrel/orderedmap/v2"
)
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, jsontext.WithIndent(" "))
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
}