Documentation
¶
Overview ¶
Package omap implements a map-like collection on ordered keys.
Basic Operations ¶
Create an empty map with New or NewFunc. A zero-valued Map is ready for use as a read-only empty map, but it will panic if modified.
m := omap.New[string, int]()
Add items using Set and remove items using Delete:
m.Set("apple", 1)
m.Delete("pear")
Look up items using Get and GetOK:
v := m.Get(key) // returns a zero value if key not found v, ok := m.GetOK(key) // ok indicates whether key was found
Report the number of elements in the map using Len.
Iterating in Order ¶
The elements of a map can be traversed in order using an iterator. Construct an iterator for m by calling First or Last. The IsValid method reports whether the iterator has an element available, and the Next and Prev methods advance or retract the iterator:
for it := m.First(); it.IsValid(); it.Next() {
doThingsWith(it.Key(), it.Value())
}
Use the Seek method to seek to a particular point in the order. Seek returns an iterator at the first item greater than or equal to the specified key:
for it := m.Seek("cherry"); it.IsValid(); it.Next() {
doThingsWith(it.Key(), it.Value())
}
Note that it is not safe to modify the map while iterating it. If you modify a map while iterating it, you will need to re-synchronize any iterators after the edits, e.g.,
for it := m.First(); it.IsValid(); {
if key := it.Key(); shouldDelete(key) {
m.Delete(key)
it.Seek(key) // update the iterator
} else {
it.Next()
}
}
Index ¶
- type Iter
- type Map
- func (m Map[T, U]) Clear()
- func (m Map[T, U]) Delete(key T) bool
- func (m Map[T, U]) First() *Iter[T, U]
- func (m Map[T, U]) Get(key T) U
- func (m Map[T, U]) GetOK(key T) (U, bool)
- func (m Map[T, U]) Keys() []T
- func (m Map[T, U]) Last() *Iter[T, U]
- func (m Map[T, U]) Len() int
- func (m Map[T, U]) Seek(key T) *Iter[T, U]
- func (m Map[T, U]) Set(key T, value U) bool
- func (m Map[T, U]) String() string
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Iter ¶
type Iter[T, U any] struct { // contains filtered or unexported fields }
An Iter is an iterator for a Map.
func (*Iter[T, U]) Key ¶
func (it *Iter[T, U]) Key() T
Key returns the current key, or a zero key if it is invalid.
type Map ¶
type Map[T, U any] struct { // contains filtered or unexported fields }
A Map represents a mapping over arbitrary key and value types. It supports efficient insertion, deletion and lookup, and also allows keys to be traversed in order.
A zero Map behaves as an empty read-only map, and Clear, Delete, Get, Keys, Len, First, and Last will work without error; however, calling Set on a zero Map will panic.
Example ¶
package main
import (
"cmp"
"fmt"
"strings"
"github.com/creachadair/mds/omap"
)
const input = `
the thousand injuries of fortunato i had borne as i best could but when he
ventured upon insult i vowed revenge you who so well know the nature of my soul
will not suppose however that i gave utterance to a threat at length i would be
avenged this was a point definitely settled but the very definitiveness with
which it was resolved precluded the idea of risk i must not only punish but
punish with impunity a wrong is unredressed when retribution overtakes its
redresser it is equally unredressed when the avenger fails to make himself felt
as such to him who has done the wrong it must be understood that neither by
word nor deed had i given fortunato cause to doubt my good will i continued as
was my wont to smile in his face and he did not perceive that my smile now was
at the thought of his immolation
`
func main() {
// Construct a map on a naturally ordered key (string).
m := omap.New[string, int]()
for _, w := range strings.Fields(input) {
m.Set(w, m.Get(w)+1)
}
// Construct a map with an explicit ordering function.
c := omap.NewFunc[int, string](cmp.Compare)
// Traverse a map in key order.
for it := m.First(); it.IsValid(); it.Next() {
c.Set(it.Value(), it.Key())
}
// Traverse a map in reverse order.
for it := c.Last(); it.IsValid(); it.Prev() {
fmt.Println(it.Value(), it.Key())
if it.Key() <= 3 {
break
}
}
}
Output: i 8 the 7 to 5 was 4 when 3
func New ¶
New constructs a new empty Map using the natural comparison order for an ordered key type. Copies of the map share storage.
func NewFunc ¶
NewFunc constructs a new empty Map using cf to compare keys. If cf == nil, NewFunc will panic. Copies of the map share storage.
func (Map[T, U]) Clear ¶
func (m Map[T, U]) Clear()
Clear deletes all the elements from m, leaving it empty.
This operation is constant-time.
func (Map[T, U]) Delete ¶
Delete deletes the specified key from m, and reports whether it was present.
This operation takes amortized O(lg n) time for a map with n elements.
func (Map[T, U]) Get ¶
func (m Map[T, U]) Get(key T) U
Get returns the value associated with key in m if it is present, or returns a zero value. To check for presence, use GetOK.
func (Map[T, U]) GetOK ¶
GetOK reports whether key is present in m, and if so returns the value associated with it, or otherwise a zero value.
This operation takes O(lg n) time for a map with n elements.
func (Map[T, U]) Keys ¶
func (m Map[T, U]) Keys() []T
Keys returns a slice of all the keys in m, in order.
func (Map[T, U]) Len ¶
Len reports the number of key-value pairs in m. This operation is constant-time.
func (Map[T, U]) Seek ¶
Seek returns an iterator to the first entry of the map whose key is greater than or equal to key, if any.
Source Files