Ordered Map

ordmap is a Go package that provides a generic ordered map implementation, primarily designed for JSON v2 marshalling and unmarshalling.

An ordered map maintains the order of keys based on insertion, allowing you to iterate over the map in the order in which entries were added. This can be particularly useful for applications where the order of elements is important, such as in JSON serialization or when maintaining the sequence of operations.

Features

• Seamless JSON v2 Integration: Directly integrates with the JSON v2 library for efficient and order-preserving marshalling and unmarshalling.
• Custom Ordered Maps: Provides robust helper functions to easily define your own custom ordered maps with minimal boilerplate code.
• Pre-Defined Ordered Map Alias: Simplifies usage by offering a pre-defined ordered map type that can be conveniently aliased for specific key and value types.
• Efficient Ordered Operations: Ensures efficient insertion, retrieval, and iteration while maintaining the order of elements, making it ideal for use cases where order matters.
• Ordered Iteration: Leverages the ByIndex method to iterate over the map in an ordered manner based on the insertion sequence.

Installation

To install the library, use the following command:

go get github.com/MarkRosemaker/ordmap

Usage

Custom Ordered Map

To create your own custom ordered map, you can utilize helper functions to define its methods:

package main
import (
"encoding/json/v2""encoding/json/jsontext""iter""github.com/MarkRosemaker/ordmap"
)
typeMyOrderedMapmap[string]*ValueWithIndextypeValueWithIndexstruct {
Foostring`json:"foo"`Barint`json:"bar"`idxint// to order a map of this type
}
funcgetIndex(v*ValueWithIndex) int { returnv.idx }
funcsetIndex(v*ValueWithIndex, iint) *ValueWithIndex { v.idx=i; returnv }
// ByIndex returns a sequence of key-value pairs ordered by index.func (omMyOrderedMap) ByIndex() iter.Seq2[string, *ValueWithIndex] {
returnordmap.ByIndex(om, getIndex)
}
// Sort sorts the map by key and sets the indices accordingly.func (omMyOrderedMap) Sort() {
ordmap.Sort(om, setIndex)
}
// Set sets a value in the map, adding it at the end of the order.func (om*MyOrderedMap) Set(keystring, v*ValueWithIndex) {
ordmap.Set(om, key, v, getIndex, setIndex)
}
// MarshalJSONTo marshals the key-value pairs in order.func (om*MyOrderedMap) MarshalJSONTo(enc*jsontext.Encoder, opts json.Options) error {
returnordmap.MarshalJSONTo(om, enc, opts)
}
// UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.func (om*MyOrderedMap) UnmarshalJSONFrom(dec*jsontext.Decoder, opts json.Options) error {
returnordmap.UnmarshalJSONFrom(om, dec, opts, setIndex)
}

If you prefer the map values to be non-pointer types, you can adjust the implementation as follows:

typeMyOrderedMapmap[string]ValueWithIndexfuncgetIndex(vValueWithIndex) int { returnv.idx }
funcsetIndex(vValueWithIndex, iint) ValueWithIndex { v.idx=i; returnv }
func (omMyOrderedMap) ByIndex() iter.Seq2[string, ValueWithIndex] {
returnordmap.ByIndex(om, getIndex)
}
func (om*MyOrderedMap) Set(keystring, vValueWithIndex) {
ordmap.Set(om, key, v, getIndex, setIndex)
}

Using The Pre-Defined Ordered Map

For simplicity, an ordered map type is already defined for you. You only need to specify the key and value types:

package main
import (
"github.com/MarkRosemaker/ordmap"
)
typeMyOrderedMap= ordmap.OrderedMap[string, *MyValue]
typeMyValuestruct {
Foostring`json:"foo"`Barint`json:"bar"`
}

Contributing

If you have any contributions to make, please submit a pull request or open an issue on the GitHub repository.

License

This project is licensed under the MIT License. See the LICENSE file for details.