Documentation ¶
Overview ¶
Package orderedmap implements an ordered map, i.e. a map that also keeps track of the order in which keys were inserted.
All operations are constant-time.
Github repo: https://github.com/wk8/go-ordered-map
Example ¶
om := orderedmap.New[string, string](3) om.Set("foo", "bar") om.Set("bar", "baz") om.Set("coucou", "toi") fmt.Println("## Get operations: ##") fmt.Println(om.Get("foo")) fmt.Println(om.Get("i dont exist")) fmt.Println(om.Value("coucou")) fmt.Println("## Iterating over pairs from oldest to newest: ##") for pair := om.Oldest(); pair != nil; pair = pair.Next() { fmt.Printf("%s => %s\n", pair.Key, pair.Value) } fmt.Println("## Iterating over the 2 newest pairs: ##") i := 0 for pair := om.Newest(); pair != nil; pair = pair.Prev() { fmt.Printf("%s => %s\n", pair.Key, pair.Value) i++ if i >= 2 { break } } fmt.Println("## JSON serialization: ##") data, err := json.Marshal(om) if err != nil { panic(err) } fmt.Println(string(data)) fmt.Println("## JSON deserialization: ##") om2 := orderedmap.New[string, string]() if err := json.Unmarshal(data, &om2); err != nil { panic(err) } fmt.Println(om2.Oldest().Key)
Output: ## Get operations: ## bar true false toi ## Iterating over pairs from oldest to newest: ## foo => bar bar => baz coucou => toi ## Iterating over the 2 newest pairs: ## coucou => toi bar => baz ## JSON serialization: ## {"foo":"bar","bar":"baz","coucou":"toi"} ## JSON deserialization: ## foo
Index ¶
- type InitOption
- type KeyNotFoundError
- type OrderedMap
- func (om *OrderedMap[K, V]) AddPairs(pairs ...Pair[K, V])
- func (om *OrderedMap[K, V]) Delete(key K) (val V, present bool)
- func (om *OrderedMap[K, V]) Get(key K) (val V, present bool)
- func (om *OrderedMap[K, V]) GetAndMoveToBack(key K) (val V, err error)
- func (om *OrderedMap[K, V]) GetAndMoveToFront(key K) (val V, err error)
- func (om *OrderedMap[K, V]) GetPair(key K) *Pair[K, V]
- func (om *OrderedMap[K, V]) Len() int
- func (om *OrderedMap[K, V]) Load(key K) (V, bool)
- func (om *OrderedMap[K, V]) MarshalJSON() ([]byte, error)
- func (om *OrderedMap[K, V]) MarshalYAML() (interface{}, error)
- func (om *OrderedMap[K, V]) MoveAfter(key, markKey K) error
- func (om *OrderedMap[K, V]) MoveBefore(key, markKey K) error
- func (om *OrderedMap[K, V]) MoveToBack(key K) error
- func (om *OrderedMap[K, V]) MoveToFront(key K) error
- func (om *OrderedMap[K, V]) Newest() *Pair[K, V]
- func (om *OrderedMap[K, V]) Oldest() *Pair[K, V]
- func (om *OrderedMap[K, V]) Set(key K, value V) (val V, present bool)
- func (om *OrderedMap[K, V]) Store(key K, value V) (V, bool)
- func (om *OrderedMap[K, V]) UnmarshalJSON(data []byte) error
- func (om *OrderedMap[K, V]) UnmarshalYAML(value *yaml.Node) error
- func (om *OrderedMap[K, V]) Value(key K) (val V)
- type Pair
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type InitOption ¶ added in v2.1.2
type InitOption[K comparable, V any] func(config *initConfig[K, V])
func WithCapacity ¶ added in v2.1.2
func WithCapacity[K comparable, V any](capacity int) InitOption[K, V]
WithCapacity allows giving a capacity hint for the map, akin to the standard make(map[K]V, capacity).
func WithInitialData ¶ added in v2.1.2
func WithInitialData[K comparable, V any](initialData ...Pair[K, V]) InitOption[K, V]
WithInitialData allows passing in initial data for the map.
type KeyNotFoundError ¶
type KeyNotFoundError[K comparable] struct { MissingKey K }
KeyNotFoundError may be returned by functions in this package when they're called with keys that are not present in the map.
func (*KeyNotFoundError[K]) Error ¶
func (e *KeyNotFoundError[K]) Error() string
type OrderedMap ¶
type OrderedMap[K comparable, V any] struct { // contains filtered or unexported fields }
func New ¶
func New[K comparable, V any](options ...any) *OrderedMap[K, V]
New creates a new OrderedMap. options can either be one or several InitOption[K, V], or a single integer, which is then interpreted as a capacity hint, à la make(map[K]V, capacity).
func (*OrderedMap[K, V]) AddPairs ¶ added in v2.1.2
func (om *OrderedMap[K, V]) AddPairs(pairs ...Pair[K, V])
AddPairs allows setting multiple pairs at a time. It's equivalent to calling Set on each pair sequentially.
func (*OrderedMap[K, V]) Delete ¶
func (om *OrderedMap[K, V]) Delete(key K) (val V, present bool)
Delete removes the key-value pair, and returns what `Get` would have returned on that key prior to the call to `Delete`.
func (*OrderedMap[K, V]) Get ¶
func (om *OrderedMap[K, V]) Get(key K) (val V, present bool)
Get looks for the given key, and returns the value associated with it, or V's nil value if not found. The boolean it returns says whether the key is present in the map.
func (*OrderedMap[K, V]) GetAndMoveToBack ¶ added in v2.1.6
func (om *OrderedMap[K, V]) GetAndMoveToBack(key K) (val V, err error)
GetAndMoveToBack combines Get and MoveToBack in the same call. If an error is returned, it will be a KeyNotFoundError.
func (*OrderedMap[K, V]) GetAndMoveToFront ¶ added in v2.1.6
func (om *OrderedMap[K, V]) GetAndMoveToFront(key K) (val V, err error)
GetAndMoveToFront combines Get and MoveToFront in the same call. If an error is returned, it will be a KeyNotFoundError.
func (*OrderedMap[K, V]) GetPair ¶
func (om *OrderedMap[K, V]) GetPair(key K) *Pair[K, V]
GetPair looks for the given key, and returns the pair associated with it, or nil if not found. The Pair struct can then be used to iterate over the ordered map from that point, either forward or backward.
func (*OrderedMap[K, V]) Len ¶
func (om *OrderedMap[K, V]) Len() int
Len returns the length of the ordered map.
func (*OrderedMap[K, V]) Load ¶
func (om *OrderedMap[K, V]) Load(key K) (V, bool)
Load is an alias for Get, mostly to present an API similar to `sync.Map`'s.
func (*OrderedMap[K, V]) MarshalJSON ¶ added in v2.1.0
func (om *OrderedMap[K, V]) MarshalJSON() ([]byte, error)
MarshalJSON implements the json.Marshaler interface.
func (*OrderedMap[K, V]) MarshalYAML ¶ added in v2.1.8
func (om *OrderedMap[K, V]) MarshalYAML() (interface{}, error)
MarshalYAML implements the yaml.Marshaler interface.
func (*OrderedMap[K, V]) MoveAfter ¶
func (om *OrderedMap[K, V]) MoveAfter(key, markKey K) error
MoveAfter moves the value associated with key to its new position after the one associated with markKey. Returns an error iff key or markKey are not present in the map. If an error is returned, it will be a KeyNotFoundError.
func (*OrderedMap[K, V]) MoveBefore ¶
func (om *OrderedMap[K, V]) MoveBefore(key, markKey K) error
MoveBefore moves the value associated with key to its new position before the one associated with markKey. Returns an error iff key or markKey are not present in the map. If an error is returned, it will be a KeyNotFoundError.
func (*OrderedMap[K, V]) MoveToBack ¶
func (om *OrderedMap[K, V]) MoveToBack(key K) error
MoveToBack moves the value associated with key to the back of the ordered map, i.e. makes it the newest pair in the map. Returns an error iff key is not present in the map. If an error is returned, it will be a KeyNotFoundError.
func (*OrderedMap[K, V]) MoveToFront ¶
func (om *OrderedMap[K, V]) MoveToFront(key K) error
MoveToFront moves the value associated with key to the front of the ordered map, i.e. makes it the oldest pair in the map. Returns an error iff key is not present in the map. If an error is returned, it will be a KeyNotFoundError.
func (*OrderedMap[K, V]) Newest ¶
func (om *OrderedMap[K, V]) Newest() *Pair[K, V]
Newest returns a pointer to the newest pair. It's meant to be used to iterate on the ordered map's pairs from the newest to the oldest, e.g.: for pair := orderedMap.Oldest(); pair != nil; pair = pair.Next() { fmt.Printf("%v => %v\n", pair.Key, pair.Value) }
func (*OrderedMap[K, V]) Oldest ¶
func (om *OrderedMap[K, V]) Oldest() *Pair[K, V]
Oldest returns a pointer to the oldest pair. It's meant to be used to iterate on the ordered map's pairs from the oldest to the newest, e.g.: for pair := orderedMap.Oldest(); pair != nil; pair = pair.Next() { fmt.Printf("%v => %v\n", pair.Key, pair.Value) }
func (*OrderedMap[K, V]) Set ¶
func (om *OrderedMap[K, V]) Set(key K, value V) (val V, present bool)
Set sets the key-value pair, and returns what `Get` would have returned on that key prior to the call to `Set`.
func (*OrderedMap[K, V]) Store ¶
func (om *OrderedMap[K, V]) Store(key K, value V) (V, bool)
Store is an alias for Set, mostly to present an API similar to `sync.Map`'s.
func (*OrderedMap[K, V]) UnmarshalJSON ¶ added in v2.1.0
func (om *OrderedMap[K, V]) UnmarshalJSON(data []byte) error
UnmarshalJSON implements the json.Unmarshaler interface.
func (*OrderedMap[K, V]) UnmarshalYAML ¶ added in v2.1.8
func (om *OrderedMap[K, V]) UnmarshalYAML(value *yaml.Node) error
UnmarshalYAML implements the yaml.Unmarshaler interface.
func (*OrderedMap[K, V]) Value ¶ added in v2.1.5
func (om *OrderedMap[K, V]) Value(key K) (val V)
Value returns the value associated with the given key or the zero value.