komap

README

KOMap

Document

KOMap is short for KeepOrderMap, it provide a generic map which keeps insert order of item.

When unmarshal from JSON string, the order is determined by their occurrence in the original string.

And of cause, it will use the order too, when marshal back to JSON string.

Highly inspired by iancoleman/orderedmap, with serval differences:

• Generics support.
• GetByIndex series API.
• Have a different strategy when a duplicate key is encountered while parsing a JSON object.

Status: Still WIP, API may not be the final version. Works in simple case, but not fully tested.

Usage

import (
    "fmt"

    "github.com/7sDream/komap"
)

func main() {
    ko = komap.New[string, int]()
    ko.Set("one", 1)
    ko.Set("three", 2)
    ko.Set("two", 2)
    ko.Set("three", 3) // do not change order of key "three", it will keep ordered before two.

    for i := 0; i < ko.Len(); i++ {
        pair := ko.GetByIndex(i)
        fmt.Printf("%s: %d\n", pair.Key, pair.Value)
    }

    data, _ := json.Marshal(ko)
    fmt.Printf("marshal result: %s", string(data))

   // Output:
   // one: 1
   // three: 3
   // two: 2
   // marshal result: {"one":1,"three":3,"two":2}
}

For all API, see document.

LICENSE

MIT. See LICENSE file.

Documentation

Index

• type KeepOrderMap
  • func New[K comparable, V any]() *KeepOrderMap[K, V]
  • func (ko *KeepOrderMap[K, V]) Delete(key K)
  • func (ko *KeepOrderMap[K, V]) Get(key K) (V, bool)
  • func (ko *KeepOrderMap[K, V]) GetByIndex(index int) Pair[K, V]
  • func (ko *KeepOrderMap[K, V]) GetKeyByIndex(index int) K
  • func (ko *KeepOrderMap[K, V]) GetOrZeroValue(key K) V
  • func (ko *KeepOrderMap[K, V]) GetValueByIndex(index int) V
  • func (ko *KeepOrderMap[K, V]) Keys() []K
  • func (ko *KeepOrderMap[K, V]) Len() int
  • func (ko KeepOrderMap[string, V]) MarshalJSON() ([]byte, error)
  • func (ko *KeepOrderMap[K, V]) Pairs() []Pair[K, V]
  • func (ko *KeepOrderMap[K, V]) Set(key K, value V)
  • func (ko *KeepOrderMap[K, V]) SetEscapeHTML(escape bool)
  • func (ko *KeepOrderMap[K, V]) Sort(lessFunc PairLessFunc[K, V])
  • func (om *KeepOrderMap[string, V]) UnmarshalJSON(data []byte) error
• type Pair
• type PairLessFunc

Examples

• KeepOrderMap.GetByIndex

Types

type KeepOrderMap

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

KeepOrderMap is a map, its kv pair keeps insert order. In JSON Unmarshal and marshal, it will use the order of keys appear in JSON string and output as is.

func New

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

New creates a new empty ordered map

func (*KeepOrderMap[K, V]) Delete

func (ko *KeepOrderMap[K, V]) Delete(key K)

Delete a value by key.

func (*KeepOrderMap[K, V]) Get

func (ko *KeepOrderMap[K, V]) Get(key K) (V, bool)

Get a value by key. the second return value is true if the key exists, otherwise false.

func (*KeepOrderMap[K, V]) GetByIndex

func (ko *KeepOrderMap[K, V]) GetByIndex(index int) Pair[K, V]

GetByIndex get the key and value by index of key order. You should make sure 0 <= i < Len(OrderedMap), panic if out of bound.

Example

Use is to iterate over the map.

package main

import (
	"encoding/json"
	"fmt"

	"github.com/7sDream/komap"
)

func main() {
	ko := komap.New[string, int]()
	ko.Set("one", 1)
	ko.Set("three", 2)
	ko.Set("two", 2)
	ko.Set("three", 3) // do not change order of key "three", it will stay ahead of "two".

	for i := 0; i < ko.Len(); i++ {
		pair := ko.GetByIndex(i)
		fmt.Printf("%s: %d\n", pair.Key, pair.Value)
	}

	data, _ := json.Marshal(ko)
	fmt.Printf("marshal result: %s", string(data))
}

Output:

one: 1
three: 3
two: 2
marshal result: {"one":1,"three":3,"two":2}

func (*KeepOrderMap[K, V]) GetKeyByIndex

func (ko *KeepOrderMap[K, V]) GetKeyByIndex(index int) K

GetKeyByIndex get key by it's index in order. You should make sure 0 <= i < Len(OrderedMap), panic if out of bound.

func (*KeepOrderMap[K, V]) GetOrZeroValue

func (ko *KeepOrderMap[K, V]) GetOrZeroValue(key K) V

GetOrZeroValue return stored value by key, or te zero value of value type if key not exist.

func (*KeepOrderMap[K, V]) GetValueByIndex

func (ko *KeepOrderMap[K, V]) GetValueByIndex(index int) V

GetValueByIndex get the value by index of key order. You should make sure 0 <= i < Len(OrderedMap), panic if out of bound.

func (*KeepOrderMap[K, V]) Keys

func (ko *KeepOrderMap[K, V]) Keys() []K

Keys returns the keys of ordered map, in current order. This will copy all keys, so you can modify it if you wish. If you want iterate over the map, maybe Len + GetByIndex is a better choice.

func (*KeepOrderMap[K, V]) Len

func (ko *KeepOrderMap[K, V]) Len() int

Len returns the size of map.

func (KeepOrderMap[string, V]) MarshalJSON

func (ko KeepOrderMap[string, V]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface. You should not call this directly, use json.Marshal(om) instead.

func (*KeepOrderMap[K, V]) Pairs

func (ko *KeepOrderMap[K, V]) Pairs() []Pair[K, V]

Paris gives you all data the map stored as a list of KV pair, in current order.

func (*KeepOrderMap[K, V]) Set

func (ko *KeepOrderMap[K, V]) Set(key K, value V)

Set a value by key. Called with an already exist key will not change it's order. If you want move it to the end, call Delete before Set.

func (*KeepOrderMap[K, V]) SetEscapeHTML

func (ko *KeepOrderMap[K, V]) SetEscapeHTML(escape bool)

SetEscapeHTML enable or disables escape HTML chars '<' '>' '&' in marshal json result. The default value is true.

func (*KeepOrderMap[K, V]) Sort

func (ko *KeepOrderMap[K, V]) Sort(lessFunc PairLessFunc[K, V])

Sort will reorder the map using the given less function.

func (*KeepOrderMap[string, V]) UnmarshalJSON

func (om *KeepOrderMap[string, V]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler interface. You shouldn't call this directly, use json.Unmarshal(ko) instead.

type Pair

type Pair[K, V any] struct {
	Key   K `json:"key"`
	Value V `json:"value"`
}

Pair is k v pair.

type PairLessFunc

type PairLessFunc[K, V any] func(a, b *Pair[K, V]) bool

PairLessFunc is the less func to sort a pair list.