README
¶
hypermap-go provides hypermap.Map: a compact, generic, insertion-ordered map for Go.
[!TIP] Use
hypermap.New[K, V](capacity)when the maximum live entry count is known; it reserves storage for steadier write performance.
Install
go get -u github.com/colduction/hypermap-go@latest
Usage
package main
import (
"fmt"
"github.com/colduction/hypermap-go"
)
func main() {
m := hypermap.New[string, int](3)
m.Set("b", 2)
m.Set("a", 1)
m.Set("c", 3)
m.MoveToFront("c")
for key, value := range m.Range() {
fmt.Println(key, value)
}
}
URL query encoding
hypermap.QueryMap is a Map[string, []string] with an Encode method that
renders the entries as a URL query string in the current key order. It embeds
Map, so every map method (Set, Get, MoveToFront, Range, …) is
available on it as well.
m := hypermap.NewQueryMap(3)
m.Set("name", []string{"ada lovelace"})
m.Set("tags", []string{"math", "code"})
fmt.Println(m.Encode()) // name=ada+lovelace&tags=math&tags=code
Encode allocates once: a nil or empty map returns "", and keys with no
values are skipped.
Features
| Capability | Behavior |
|---|---|
| Zero value | Ready to use without initialization. |
| Ordering | Preserves insertion order; replacing a value keeps the key in place. |
| Lookup and mutation | O(1) average for lookup, insert, delete, movement, and front/back access. |
| Iteration | Supports for key, value := range m.Range() with iter.Seq2. |
| Storage reuse | Clear keeps allocated storage, while Reset releases it. |
| Query encoding | QueryMap.Encode renders string/[]string entries as a query string. |
[!IMPORTANT]
Mapdoes not synchronize access. Share a map across goroutines only with external synchronization, or shard independent maps by key or worker for write-heavy services.
License
This project is released under the MIT License. See LICENSE.
Documentation
¶
Overview ¶
Package hypermap provides compact, generic insertion-ordered maps for allocation-conscious Go services.
Index ¶
- type Map
- func (m *Map[T, T2]) Back() (T, T2, bool)
- func (m *Map[T, T2]) Cap() int
- func (m *Map[T, T2]) Clear()
- func (m *Map[T, T2]) Delete(key T) (T2, bool)
- func (m *Map[T, T2]) Front() (T, T2, bool)
- func (m *Map[T, T2]) Get(key T) (T2, bool)
- func (m *Map[T, T2]) Has(key T) bool
- func (m *Map[T, T2]) Init(capacity int)
- func (m *Map[T, T2]) Len() int
- func (m *Map[T, T2]) MoveToBack(key T) bool
- func (m *Map[T, T2]) MoveToFront(key T) bool
- func (m *Map[T, T2]) Next(key T) (T, T2, bool)
- func (m *Map[T, T2]) PopBack() (T, T2, bool)
- func (m *Map[T, T2]) PopFront() (T, T2, bool)
- func (m *Map[T, T2]) Prev(key T) (T, T2, bool)
- func (m *Map[T, T2]) Range() iter.Seq2[T, T2]
- func (m *Map[T, T2]) Reset()
- func (m *Map[T, T2]) Set(key T, value T2) (T2, bool)
- type QueryMap
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Map ¶
type Map[T comparable, T2 any] orderedMap[T, T2]
Map is an insertion-ordered hash map.
The zero value is ready to use. Single-key lookup, insertion, deletion, movement, and front/back access are O(1) average. Use New or Map.Init with the maximum live entry count to keep steady-state writes within existing storage. Do not copy a Map after first use. Map does not synchronize access; callers that share a Map across goroutines need external synchronization. Use independent Map values per shard or worker when write contention is expected.
func New ¶
func New[T comparable, T2 any](capacity int) Map[T, T2]
New returns an initialized Map with storage reserved for up to capacity live entries.
func (*Map[T, T2]) Back ¶
Back returns the last key and value in insertion order and reports whether m is non-empty.
func (*Map[T, T2]) Cap ¶
Cap reports the maximum live entries m can hold before growing its slot slice.
func (*Map[T, T2]) Clear ¶
func (m *Map[T, T2]) Clear()
Clear removes all entries while keeping allocated storage for reuse.
func (*Map[T, T2]) Front ¶
Front returns the first key and value in insertion order and reports whether m is non-empty.
func (*Map[T, T2]) MoveToBack ¶
MoveToBack moves key to the back of m when key is present.
func (*Map[T, T2]) MoveToFront ¶
MoveToFront moves key to the front of m when key is present.
func (*Map[T, T2]) Next ¶
Next returns the key and value after key in insertion order and reports whether key has a successor.
func (*Map[T, T2]) PopBack ¶
PopBack removes and returns the last key and value in insertion order and reports whether an entry is removed.
func (*Map[T, T2]) PopFront ¶
PopFront removes and returns the first key and value in insertion order and reports whether an entry is removed.
func (*Map[T, T2]) Prev ¶
Prev returns the key and value before key in insertion order and reports whether key has a predecessor.
func (*Map[T, T2]) Range ¶
Range returns an iter.Seq2 over each key and value in insertion order. Range leaves remaining iteration behavior unspecified when yield mutates m.
type QueryMap ¶
QueryMap is a Map specialized for URL query parameters. It maps string keys to repeated string values and adds QueryMap.Encode. Every Map method is promoted for ordered string keys and []string values.
func NewQueryMap ¶
NewQueryMap returns an initialized QueryMap with storage reserved for up to capacity live entries.
Source Files