...
▽

Package immutable

import "github.com/benbjohnson/immutable"
Overview
Index
Examples

Overview ▾

Package immutable provides immutable collection types.

Introduction

Immutable collections provide an efficient, safe way to share collections of data while minimizing locks. The collections in this package provide List, Map, and SortedMap implementations. These act similarly to slices and maps, respectively, except that altering a collection returns a new copy of the collection with that change.

Because collections are unable to change, they are safe for multiple goroutines to read from at the same time without a mutex. However, these types of collections come with increased CPU & memory usage as compared with Go's built-in collection types so please evaluate for your specific use.

Collection Types

The List type provides an API similar to Go slices. They allow appending, prepending, and updating of elements. Elements can also be fetched by index or iterated over using a ListIterator.

The Map & SortedMap types provide an API similar to Go maps. They allow values to be assigned to unique keys and allow for the deletion of keys. Values can be fetched by key and key/value pairs can be iterated over using the appropriate iterator type. Both map types provide the same API. The SortedMap, however, provides iteration over sorted keys while the Map provides iteration over unsorted keys. Maps improved performance and memory usage as compared to SortedMaps.

Hashing and Sorting

Map types require the use of a Hasher implementation to calculate hashes for their keys and check for key equality. SortedMaps require the use of a Comparer implementation to sort keys in the map.

These collection types automatically provide built-in hasher and comparers for int, string, and byte slice keys. If you are using one of these key types then simply pass a nil into the constructor. Otherwise you will need to implement a custom Hasher or Comparer type. Please see the provided implementations for reference.

Index ▾

type Comparer
    func NewComparer[K any](key K) Comparer[K]
type Hasher
    func NewHasher[K any](key K) Hasher[K]
type List
    func NewList[T any](values ...T) *List[T]
    func (l *List[T]) Append(value T) *List[T]
    func (l *List[T]) Get(index int) T
    func (l *List[T]) Iterator() *ListIterator[T]
    func (l *List[T]) Len() int
    func (l *List[T]) Prepend(value T) *List[T]
    func (l *List[T]) Set(index int, value T) *List[T]
    func (l *List[T]) Slice(start, end int) *List[T]
type ListBuilder
    func NewListBuilder[T any]() *ListBuilder[T]
    func (b *ListBuilder[T]) Append(value T)
    func (b *ListBuilder[T]) Get(index int) T
    func (b *ListBuilder[T]) Iterator() *ListIterator[T]
    func (b *ListBuilder[T]) Len() int
    func (b *ListBuilder[T]) List() *List[T]
    func (b *ListBuilder[T]) Prepend(value T)
    func (b *ListBuilder[T]) Set(index int, value T)
    func (b *ListBuilder[T]) Slice(start, end int)
type ListIterator
    func (itr *ListIterator[T]) Done() bool
    func (itr *ListIterator[T]) First()
    func (itr *ListIterator[T]) Last()
    func (itr *ListIterator[T]) Next() (index int, value T)
    func (itr *ListIterator[T]) Prev() (index int, value T)
    func (itr *ListIterator[T]) Seek(index int)
type Map
    func NewMap[K, V any](hasher Hasher[K]) *Map[K, V]
    func NewMapOf[K comparable, V any](hasher Hasher[K], entries map[K]V) *Map[K, V]
    func (m *Map[K, V]) Delete(key K) *Map[K, V]
    func (m *Map[K, V]) Get(key K) (value V, ok bool)
    func (m *Map[K, V]) Iterator() *MapIterator[K, V]
    func (m *Map[K, V]) Len() int
    func (m *Map[K, V]) Set(key K, value V) *Map[K, V]
type MapBuilder
    func NewMapBuilder[K, V any](hasher Hasher[K]) *MapBuilder[K, V]
    func (b *MapBuilder[K, V]) Delete(key K)
    func (b *MapBuilder[K, V]) Get(key K) (value V, ok bool)
    func (b *MapBuilder[K, V]) Iterator() *MapIterator[K, V]
    func (b *MapBuilder[K, V]) Len() int
    func (b *MapBuilder[K, V]) Map() *Map[K, V]
    func (b *MapBuilder[K, V]) Set(key K, value V)
type MapIterator
    func (itr *MapIterator[K, V]) Done() bool
    func (itr *MapIterator[K, V]) First()
    func (itr *MapIterator[K, V]) Next() (key K, value V, ok bool)
type Set
    func NewSet[T any](hasher Hasher[T], values ...T) Set[T]
    func (s Set[T]) Add(value T) Set[T]
    func (s Set[T]) Delete(value T) Set[T]
    func (s Set[T]) Has(val T) bool
    func (s Set[T]) Items() []T
    func (s Set[T]) Iterator() *SetIterator[T]
    func (s Set[K]) Len() int
type SetBuilder
    func NewSetBuilder[T any](hasher Hasher[T]) *SetBuilder[T]
    func (s SetBuilder[T]) Delete(val T)
    func (s SetBuilder[T]) Has(val T) bool
    func (s SetBuilder[T]) Len() int
    func (s SetBuilder[T]) Set(val T)
type SetIterator
    func (itr *SetIterator[T]) Done() bool
    func (itr *SetIterator[T]) First()
    func (itr *SetIterator[T]) Next() (val T, ok bool)
type SortedMap
    func NewSortedMap[K, V any](comparer Comparer[K]) *SortedMap[K, V]
    func NewSortedMapOf[K comparable, V any](comparer Comparer[K], entries map[K]V) *SortedMap[K, V]
    func (m *SortedMap[K, V]) Delete(key K) *SortedMap[K, V]
    func (m *SortedMap[K, V]) Get(key K) (V, bool)
    func (m *SortedMap[K, V]) Iterator() *SortedMapIterator[K, V]
    func (m *SortedMap[K, V]) Len() int
    func (m *SortedMap[K, V]) Set(key K, value V) *SortedMap[K, V]
type SortedMapBuilder
    func NewSortedMapBuilder[K, V any](comparer Comparer[K]) *SortedMapBuilder[K, V]
    func (b *SortedMapBuilder[K, V]) Delete(key K)
    func (b *SortedMapBuilder[K, V]) Get(key K) (value V, ok bool)
    func (b *SortedMapBuilder[K, V]) Iterator() *SortedMapIterator[K, V]
    func (b *SortedMapBuilder[K, V]) Len() int
    func (b *SortedMapBuilder[K, V]) Map() *SortedMap[K, V]
    func (b *SortedMapBuilder[K, V]) Set(key K, value V)
type SortedMapIterator
    func (itr *SortedMapIterator[K, V]) Done() bool
    func (itr *SortedMapIterator[K, V]) First()
    func (itr *SortedMapIterator[K, V]) Last()
    func (itr *SortedMapIterator[K, V]) Next() (key K, value V, ok bool)
    func (itr *SortedMapIterator[K, V]) Prev() (key K, value V, ok bool)
    func (itr *SortedMapIterator[K, V]) Seek(key K)
type SortedSet
    func NewSortedSet[T any](comparer Comparer[T], values ...T) SortedSet[T]
    func (s SortedSet[T]) Add(value T) SortedSet[T]
    func (s SortedSet[T]) Delete(value T) SortedSet[T]
    func (s SortedSet[T]) Has(val T) bool
    func (s SortedSet[T]) Items() []T
    func (s SortedSet[T]) Iterator() *SortedSetIterator[T]
    func (s SortedSet[K]) Len() int
type SortedSetBuilder
    func NewSortedSetBuilder[T any](comparer Comparer[T]) *SortedSetBuilder[T]
    func (s SortedSetBuilder[T]) Delete(val T)
    func (s SortedSetBuilder[T]) Has(val T) bool
    func (s SortedSetBuilder[T]) Len() int
    func (s SortedSetBuilder[T]) Set(val T)
type SortedSetIterator
    func (itr *SortedSetIterator[T]) Done() bool
    func (itr *SortedSetIterator[T]) First()
    func (itr *SortedSetIterator[T]) Last()
    func (itr *SortedSetIterator[T]) Next() (val T, ok bool)
    func (itr *SortedSetIterator[T]) Prev() (val T, ok bool)
    func (itr *SortedSetIterator[T]) Seek(val T)

Package files

immutable.go sets.go

type Comparer

Comparer allows the comparison of two keys for the purpose of sorting. 

type Comparer[K any] interface {
    // Returns -1 if a is less than b, returns 1 if a is greater than b,
    // and returns 0 if a is equal to b.
    Compare(a, b K) int
}

func NewComparer 

func NewComparer[K any](key K) Comparer[K]

NewComparer returns the built-in comparer for a given key type. Note that only int-ish and string-ish types are supported, despite the 'comparable' constraint. Attempts to use other types will result in a panic - users should define their own Comparers for these cases.

type Hasher

Hasher hashes keys and checks them for equality. 

type Hasher[K any] interface {
    // Computes a hash for key.
    Hash(key K) uint32

    // Returns true if a and b are equal.
    Equal(a, b K) bool
}

func NewHasher 

func NewHasher[K any](key K) Hasher[K]

NewHasher returns the built-in hasher for a given key type.

type List

List is a dense, ordered, indexed collections. They are analogous to slices in Go. They can be updated by appending to the end of the list, prepending values to the beginning of the list, or updating existing indexes in the list. 

type List[T any] struct {
    // contains filtered or unexported fields
}

func NewList 

func NewList[T any](values ...T) *List[T]

NewList returns a new empty instance of List.

func (*List[T]) Append 

func (l *List[T]) Append(value T) *List[T]

Append returns a new list with value added to the end of the list.

▾ Example

Code:

l := NewList[string]()
l = l.Append("foo")
l = l.Append("bar")
l = l.Append("baz")

fmt.Println(l.Get(0))
fmt.Println(l.Get(1))
fmt.Println(l.Get(2))

Output:

foo
bar
baz

func (*List[T]) Get 

func (l *List[T]) Get(index int) T

Get returns the value at the given index. Similar to slices, this method will panic if index is below zero or is greater than or equal to the list size.

func (*List[T]) Iterator 

func (l *List[T]) Iterator() *ListIterator[T]

Iterator returns a new iterator for this list positioned at the first index.

▾ Example

Code:

l := NewList[string]()
l = l.Append("foo")
l = l.Append("bar")
l = l.Append("baz")

itr := l.Iterator()
for !itr.Done() {
    i, v := itr.Next()
    fmt.Println(i, v)
}

Output:

0 foo
1 bar
2 baz

▾ Example (Reverse)

Code:

l := NewList[string]()
l = l.Append("foo")
l = l.Append("bar")
l = l.Append("baz")

itr := l.Iterator()
itr.Last()
for !itr.Done() {
    i, v := itr.Prev()
    fmt.Println(i, v)
}

Output:

2 baz
1 bar
0 foo

func (*List[T]) Len 

func (l *List[T]) Len() int

Len returns the number of elements in the list.

func (*List[T]) Prepend 

func (l *List[T]) Prepend(value T) *List[T]

Prepend returns a new list with value(s) added to the beginning of the list.

▾ Example

Code:

l := NewList[string]()
l = l.Prepend("foo")
l = l.Prepend("bar")
l = l.Prepend("baz")

fmt.Println(l.Get(0))
fmt.Println(l.Get(1))
fmt.Println(l.Get(2))

Output:

baz
bar
foo

func (*List[T]) Set 

func (l *List[T]) Set(index int, value T) *List[T]

Set returns a new list with value set at index. Similar to slices, this method will panic if index is below zero or if the index is greater than or equal to the list size.

▾ Example

Code:

l := NewList[string]()
l = l.Append("foo")
l = l.Append("bar")
l = l.Set(1, "baz")

fmt.Println(l.Get(0))
fmt.Println(l.Get(1))

Output:

foo
baz

func (*List[T]) Slice 

func (l *List[T]) Slice(start, end int) *List[T]

Slice returns a new list of elements between start index and end index. Similar to slices, this method will panic if start or end are below zero or greater than the list size. A panic will also occur if start is greater than end.

Unlike Go slices, references to inaccessible elements will be automatically removed so they can be garbage collected.

▾ Example

Code:

l := NewList[string]()
l = l.Append("foo")
l = l.Append("bar")
l = l.Append("baz")
l = l.Slice(1, 3)

fmt.Println(l.Get(0))
fmt.Println(l.Get(1))

Output:

bar
baz

type ListBuilder

ListBuilder represents an efficient builder for creating new Lists. 

type ListBuilder[T any] struct {
    // contains filtered or unexported fields
}

func NewListBuilder 

func NewListBuilder[T any]() *ListBuilder[T]

NewListBuilder returns a new instance of ListBuilder.

func (*ListBuilder[T]) Append 

func (b *ListBuilder[T]) Append(value T)

Append adds value to the end of the list.

▾ Example

Code:

b := NewListBuilder[string]()
b.Append("foo")
b.Append("bar")
b.Append("baz")

l := b.List()
fmt.Println(l.Get(0))
fmt.Println(l.Get(1))
fmt.Println(l.Get(2))

Output:

foo
bar
baz

func (*ListBuilder[T]) Get 

func (b *ListBuilder[T]) Get(index int) T

Get returns the value at the given index. Similar to slices, this method will panic if index is below zero or is greater than or equal to the list size.

func (*ListBuilder[T]) Iterator 

func (b *ListBuilder[T]) Iterator() *ListIterator[T]

Iterator returns a new iterator for the underlying list.

func (*ListBuilder[T]) Len 

func (b *ListBuilder[T]) Len() int

Len returns the number of elements in the underlying list.

func (*ListBuilder[T]) List 

func (b *ListBuilder[T]) List() *List[T]

List returns the current copy of the list. The builder should not be used again after the list after this call.

func (*ListBuilder[T]) Prepend 

func (b *ListBuilder[T]) Prepend(value T)

Prepend adds value to the beginning of the list.

▾ Example

Code:

b := NewListBuilder[string]()
b.Prepend("foo")
b.Prepend("bar")
b.Prepend("baz")

l := b.List()
fmt.Println(l.Get(0))
fmt.Println(l.Get(1))
fmt.Println(l.Get(2))

Output:

baz
bar
foo

func (*ListBuilder[T]) Set 

func (b *ListBuilder[T]) Set(index int, value T)

Set updates the value at the given index. Similar to slices, this method will panic if index is below zero or if the index is greater than or equal to the list size.

▾ Example

Code:

b := NewListBuilder[string]()
b.Append("foo")
b.Append("bar")
b.Set(1, "baz")

l := b.List()
fmt.Println(l.Get(0))
fmt.Println(l.Get(1))

Output:

foo
baz

func (*ListBuilder[T]) Slice 

func (b *ListBuilder[T]) Slice(start, end int)

Slice updates the list with a sublist of elements between start and end index. See List.Slice() for more details.

▾ Example

Code:

b := NewListBuilder[string]()
b.Append("foo")
b.Append("bar")
b.Append("baz")
b.Slice(1, 3)

l := b.List()
fmt.Println(l.Get(0))
fmt.Println(l.Get(1))

Output:

bar
baz

type ListIterator

ListIterator represents an ordered iterator over a list. 

type ListIterator[T any] struct {
    // contains filtered or unexported fields
}

func (*ListIterator[T]) Done 

func (itr *ListIterator[T]) Done() bool

Done returns true if no more elements remain in the iterator.

func (*ListIterator[T]) First 

func (itr *ListIterator[T]) First()

First positions the iterator on the first index. If source list is empty then no change is made.

func (*ListIterator[T]) Last 

func (itr *ListIterator[T]) Last()

Last positions the iterator on the last index. If source list is empty then no change is made.

func (*ListIterator[T]) Next 

func (itr *ListIterator[T]) Next() (index int, value T)

Next returns the current index and its value & moves the iterator forward. Returns an index of -1 if the there are no more elements to return.

func (*ListIterator[T]) Prev 

func (itr *ListIterator[T]) Prev() (index int, value T)

Prev returns the current index and value and moves the iterator backward. Returns an index of -1 if the there are no more elements to return.

func (*ListIterator[T]) Seek 

func (itr *ListIterator[T]) Seek(index int)

Seek moves the iterator position to the given index in the list. Similar to Go slices, this method will panic if index is below zero or if the index is greater than or equal to the list size.

type Map

Map represents an immutable hash map implementation. The map uses a Hasher to generate hashes and check for equality of key values.

It is implemented as an Hash Array Mapped Trie. 

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

func NewMap 

func NewMap[K, V any](hasher Hasher[K]) *Map[K, V]

NewMap returns a new instance of Map. If hasher is nil, a default hasher implementation will automatically be chosen based on the first key added. Default hasher implementations only exist for int, string, and byte slice types.

func NewMapOf 

func NewMapOf[K comparable, V any](hasher Hasher[K], entries map[K]V) *Map[K, V]

NewMapOf returns a new instance of Map, containing a map of provided entries.

If hasher is nil, a default hasher implementation will automatically be chosen based on the first key added. Default hasher implementations only exist for int, string, and byte slice types.

func (*Map[K, V]) Delete 

func (m *Map[K, V]) Delete(key K) *Map[K, V]

Delete returns a map with the given key removed. Removing a non-existent key will cause this method to return the same map.

▾ Example

Code:

m := NewMap[string, any](nil)
m = m.Set("foo", "bar")
m = m.Set("baz", 100)
m = m.Delete("baz")

v, ok := m.Get("foo")
fmt.Println("foo", v, ok)

v, ok = m.Get("baz")
fmt.Println("baz", v, ok)

Output:

foo bar true
baz <nil> false

func (*Map[K, V]) Get 

func (m *Map[K, V]) Get(key K) (value V, ok bool)

Get returns the value for a given key and a flag indicating whether the key exists. This flag distinguishes a nil value set on a key versus a non-existent key in the map.

func (*Map[K, V]) Iterator 

func (m *Map[K, V]) Iterator() *MapIterator[K, V]

Iterator returns a new iterator for the map.

▾ Example

Code:

m := NewMap[string, int](nil)
m = m.Set("apple", 100)
m = m.Set("grape", 200)
m = m.Set("kiwi", 300)
m = m.Set("mango", 400)
m = m.Set("orange", 500)
m = m.Set("peach", 600)
m = m.Set("pear", 700)
m = m.Set("pineapple", 800)
m = m.Set("strawberry", 900)

itr := m.Iterator()
for !itr.Done() {
    k, v, _ := itr.Next()
    fmt.Println(k, v)
}

Output:

mango 400
pear 700
pineapple 800
grape 200
orange 500
strawberry 900
kiwi 300
peach 600
apple 100

func (*Map[K, V]) Len 

func (m *Map[K, V]) Len() int

Len returns the number of elements in the map.

func (*Map[K, V]) Set 

func (m *Map[K, V]) Set(key K, value V) *Map[K, V]

Set returns a map with the key set to the new value. A nil value is allowed.

This function will return a new map even if the updated value is the same as the existing value because Map does not track value equality.

▾ Example

Code:

m := NewMap[string, any](nil)
m = m.Set("foo", "bar")
m = m.Set("baz", 100)

v, ok := m.Get("foo")
fmt.Println("foo", v, ok)

v, ok = m.Get("baz")
fmt.Println("baz", v, ok)

v, ok = m.Get("bat") // does not exist
fmt.Println("bat", v, ok)

Output:

foo bar true
baz 100 true
bat <nil> false

type MapBuilder

MapBuilder represents an efficient builder for creating Maps. 

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

func NewMapBuilder 

func NewMapBuilder[K, V any](hasher Hasher[K]) *MapBuilder[K, V]

NewMapBuilder returns a new instance of MapBuilder.

func (*MapBuilder[K, V]) Delete 

func (b *MapBuilder[K, V]) Delete(key K)

Delete removes the given key. See Map.Delete() for additional details.

▾ Example

Code:

b := NewMapBuilder[string, any](nil)
b.Set("foo", "bar")
b.Set("baz", 100)
b.Delete("baz")

m := b.Map()
v, ok := m.Get("foo")
fmt.Println("foo", v, ok)

v, ok = m.Get("baz")
fmt.Println("baz", v, ok)

Output:

foo bar true
baz <nil> false

func (*MapBuilder[K, V]) Get 

func (b *MapBuilder[K, V]) Get(key K) (value V, ok bool)

Get returns the value for the given key.

func (*MapBuilder[K, V]) Iterator 

func (b *MapBuilder[K, V]) Iterator() *MapIterator[K, V]

Iterator returns a new iterator for the underlying map.

func (*MapBuilder[K, V]) Len 

func (b *MapBuilder[K, V]) Len() int

Len returns the number of elements in the underlying map.

func (*MapBuilder[K, V]) Map 

func (b *MapBuilder[K, V]) Map() *Map[K, V]

Map returns the underlying map. Only call once. Builder is invalid after call. Will panic on second invocation.

func (*MapBuilder[K, V]) Set 

func (b *MapBuilder[K, V]) Set(key K, value V)

Set sets the value of the given key. See Map.Set() for additional details.

▾ Example

Code:

b := NewMapBuilder[string, any](nil)
b.Set("foo", "bar")
b.Set("baz", 100)

m := b.Map()
v, ok := m.Get("foo")
fmt.Println("foo", v, ok)

v, ok = m.Get("baz")
fmt.Println("baz", v, ok)

v, ok = m.Get("bat") // does not exist
fmt.Println("bat", v, ok)

Output:

foo bar true
baz 100 true
bat <nil> false

type MapIterator

MapIterator represents an iterator over a map's key/value pairs. Although map keys are not sorted, the iterator's order is deterministic. 

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

func (*MapIterator[K, V]) Done 

func (itr *MapIterator[K, V]) Done() bool

Done returns true if no more elements remain in the iterator.

func (*MapIterator[K, V]) First 

func (itr *MapIterator[K, V]) First()

First resets the iterator to the first key/value pair.

func (*MapIterator[K, V]) Next 

func (itr *MapIterator[K, V]) Next() (key K, value V, ok bool)

Next returns the next key/value pair. Returns a nil key when no elements remain.

type Set

Set represents a collection of unique values. The set uses a Hasher to generate hashes and check for equality of key values.

Internally, the Set stores values as keys of a Map[T,struct{}] 

type Set[T any] struct {
    // contains filtered or unexported fields
}

func NewSet 

func NewSet[T any](hasher Hasher[T], values ...T) Set[T]

NewSet returns a new instance of Set.

If hasher is nil, a default hasher implementation will automatically be chosen based on the first key added. Default hasher implementations only exist for int, string, and byte slice types. NewSet can also take some initial values as varargs.

func (Set[T]) Add 

func (s Set[T]) Add(value T) Set[T]

Add returns a set containing the new value.

This function will return a new set even if the set already contains the value.

func (Set[T]) Delete 

func (s Set[T]) Delete(value T) Set[T]

Delete returns a set with the given key removed.

func (Set[T]) Has 

func (s Set[T]) Has(val T) bool

Has returns true when the set contains the given value

func (Set[T]) Items 

func (s Set[T]) Items() []T

Items returns a slice of the items inside the set

func (Set[T]) Iterator 

func (s Set[T]) Iterator() *SetIterator[T]

Iterator returns a new iterator for this set positioned at the first value.

func (Set[K]) Len 

func (s Set[K]) Len() int

Len returns the number of elements in the underlying map.

type SetBuilder 

type SetBuilder[T any] struct {
    // contains filtered or unexported fields
}

func NewSetBuilder 

func NewSetBuilder[T any](hasher Hasher[T]) *SetBuilder[T]

func (SetBuilder[T]) Delete 

func (s SetBuilder[T]) Delete(val T)

func (SetBuilder[T]) Has 

func (s SetBuilder[T]) Has(val T) bool

func (SetBuilder[T]) Len 

func (s SetBuilder[T]) Len() int

func (SetBuilder[T]) Set 

func (s SetBuilder[T]) Set(val T)

type SetIterator

SetIterator represents an iterator over a set. Iteration can occur in natural or reverse order based on use of Next() or Prev(). 

type SetIterator[T any] struct {
    // contains filtered or unexported fields
}

func (*SetIterator[T]) Done 

func (itr *SetIterator[T]) Done() bool

Done returns true if no more values remain in the iterator.

func (*SetIterator[T]) First 

func (itr *SetIterator[T]) First()

First moves the iterator to the first value.

func (*SetIterator[T]) Next 

func (itr *SetIterator[T]) Next() (val T, ok bool)

Next moves the iterator to the next value.

type SortedMap

SortedMap represents a map of key/value pairs sorted by key. The sort order is determined by the Comparer used by the map.

This map is implemented as a B+tree. 

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

func NewSortedMap 

func NewSortedMap[K, V any](comparer Comparer[K]) *SortedMap[K, V]

NewSortedMap returns a new instance of SortedMap. If comparer is nil then a default comparer is set after the first key is inserted. Default comparers exist for int, string, and byte slice keys.

func NewSortedMapOf 

func NewSortedMapOf[K comparable, V any](comparer Comparer[K], entries map[K]V) *SortedMap[K, V]

NewSortedMapOf returns a new instance of SortedMap, containing a map of provided entries.

If comparer is nil then a default comparer is set after the first key is inserted. Default comparers exist for int, string, and byte slice keys.

func (*SortedMap[K, V]) Delete 

func (m *SortedMap[K, V]) Delete(key K) *SortedMap[K, V]

Delete returns a copy of the map with the key removed. Returns the original map if key does not exist.

▾ Example

Code:

m := NewSortedMap[string, any](nil)
m = m.Set("foo", "bar")
m = m.Set("baz", 100)
m = m.Delete("baz")

v, ok := m.Get("foo")
fmt.Println("foo", v, ok)

v, ok = m.Get("baz")
fmt.Println("baz", v, ok)

Output:

foo bar true
baz <nil> false

func (*SortedMap[K, V]) Get 

func (m *SortedMap[K, V]) Get(key K) (V, bool)

Get returns the value for a given key and a flag indicating if the key is set. The flag can be used to distinguish between a nil-set key versus an unset key.

func (*SortedMap[K, V]) Iterator 

func (m *SortedMap[K, V]) Iterator() *SortedMapIterator[K, V]

Iterator returns a new iterator for this map positioned at the first key.

▾ Example

Code:

m := NewSortedMap[string, any](nil)
m = m.Set("strawberry", 900)
m = m.Set("kiwi", 300)
m = m.Set("apple", 100)
m = m.Set("pear", 700)
m = m.Set("pineapple", 800)
m = m.Set("peach", 600)
m = m.Set("orange", 500)
m = m.Set("grape", 200)
m = m.Set("mango", 400)

itr := m.Iterator()
for !itr.Done() {
    k, v, _ := itr.Next()
    fmt.Println(k, v)
}

Output:

apple 100
grape 200
kiwi 300
mango 400
orange 500
peach 600
pear 700
pineapple 800
strawberry 900

func (*SortedMap[K, V]) Len 

func (m *SortedMap[K, V]) Len() int

Len returns the number of elements in the sorted map.

func (*SortedMap[K, V]) Set 

func (m *SortedMap[K, V]) Set(key K, value V) *SortedMap[K, V]

Set returns a copy of the map with the key set to the given value.

▾ Example

Code:

m := NewSortedMap[string, any](nil)
m = m.Set("foo", "bar")
m = m.Set("baz", 100)

v, ok := m.Get("foo")
fmt.Println("foo", v, ok)

v, ok = m.Get("baz")
fmt.Println("baz", v, ok)

v, ok = m.Get("bat") // does not exist
fmt.Println("bat", v, ok)

Output:

foo bar true
baz 100 true
bat <nil> false

type SortedMapBuilder

SortedMapBuilder represents an efficient builder for creating sorted maps. 

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

func NewSortedMapBuilder 

func NewSortedMapBuilder[K, V any](comparer Comparer[K]) *SortedMapBuilder[K, V]

NewSortedMapBuilder returns a new instance of SortedMapBuilder.

func (*SortedMapBuilder[K, V]) Delete 

func (b *SortedMapBuilder[K, V]) Delete(key K)

Delete removes the given key. See SortedMap.Delete() for additional details.

▾ Example

Code:

b := NewSortedMapBuilder[string, any](nil)
b.Set("foo", "bar")
b.Set("baz", 100)
b.Delete("baz")

m := b.Map()
v, ok := m.Get("foo")
fmt.Println("foo", v, ok)

v, ok = m.Get("baz")
fmt.Println("baz", v, ok)

Output:

foo bar true
baz <nil> false

func (*SortedMapBuilder[K, V]) Get 

func (b *SortedMapBuilder[K, V]) Get(key K) (value V, ok bool)

Get returns the value for the given key.

func (*SortedMapBuilder[K, V]) Iterator 

func (b *SortedMapBuilder[K, V]) Iterator() *SortedMapIterator[K, V]

Iterator returns a new iterator for the underlying map positioned at the first key.

func (*SortedMapBuilder[K, V]) Len 

func (b *SortedMapBuilder[K, V]) Len() int

Len returns the number of elements in the underlying map.

func (*SortedMapBuilder[K, V]) Map 

func (b *SortedMapBuilder[K, V]) Map() *SortedMap[K, V]

SortedMap returns the current copy of the map. The returned map is safe to use even if after the builder continues to be used.

func (*SortedMapBuilder[K, V]) Set 

func (b *SortedMapBuilder[K, V]) Set(key K, value V)

Set sets the value of the given key. See SortedMap.Set() for additional details.

▾ Example

Code:

b := NewSortedMapBuilder[string, any](nil)
b.Set("foo", "bar")
b.Set("baz", 100)

m := b.Map()
v, ok := m.Get("foo")
fmt.Println("foo", v, ok)

v, ok = m.Get("baz")
fmt.Println("baz", v, ok)

v, ok = m.Get("bat") // does not exist
fmt.Println("bat", v, ok)

Output:

foo bar true
baz 100 true
bat <nil> false

type SortedMapIterator

SortedMapIterator represents an iterator over a sorted map. Iteration can occur in natural or reverse order based on use of Next() or Prev(). 

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

func (*SortedMapIterator[K, V]) Done 

func (itr *SortedMapIterator[K, V]) Done() bool

Done returns true if no more key/value pairs remain in the iterator.

func (*SortedMapIterator[K, V]) First 

func (itr *SortedMapIterator[K, V]) First()

First moves the iterator to the first key/value pair.

func (*SortedMapIterator[K, V]) Last 

func (itr *SortedMapIterator[K, V]) Last()

Last moves the iterator to the last key/value pair.

func (*SortedMapIterator[K, V]) Next 

func (itr *SortedMapIterator[K, V]) Next() (key K, value V, ok bool)

Next returns the current key/value pair and moves the iterator forward. Returns a nil key if the there are no more elements to return.

func (*SortedMapIterator[K, V]) Prev 

func (itr *SortedMapIterator[K, V]) Prev() (key K, value V, ok bool)

Prev returns the current key/value pair and moves the iterator backward. Returns a nil key if the there are no more elements to return.

func (*SortedMapIterator[K, V]) Seek 

func (itr *SortedMapIterator[K, V]) Seek(key K)

Seek moves the iterator position to the given key in the map. If the key does not exist then the next key is used. If no more keys exist then the iteartor is marked as done.

type SortedSet 

type SortedSet[T any] struct {
    // contains filtered or unexported fields
}

func NewSortedSet 

func NewSortedSet[T any](comparer Comparer[T], values ...T) SortedSet[T]

NewSortedSet returns a new instance of SortedSet.

If comparer is nil then a default comparer is set after the first key is inserted. Default comparers exist for int, string, and byte slice keys. NewSortedSet can also take some initial values as varargs.

func (SortedSet[T]) Add 

func (s SortedSet[T]) Add(value T) SortedSet[T]

Add returns a set containing the new value.

This function will return a new set even if the set already contains the value.

func (SortedSet[T]) Delete 

func (s SortedSet[T]) Delete(value T) SortedSet[T]

Delete returns a set with the given key removed.

func (SortedSet[T]) Has 

func (s SortedSet[T]) Has(val T) bool

Has returns true when the set contains the given value

func (SortedSet[T]) Items 

func (s SortedSet[T]) Items() []T

Items returns a slice of the items inside the set

func (SortedSet[T]) Iterator 

func (s SortedSet[T]) Iterator() *SortedSetIterator[T]

Iterator returns a new iterator for this set positioned at the first value.

func (SortedSet[K]) Len 

func (s SortedSet[K]) Len() int

Len returns the number of elements in the underlying map.

type SortedSetBuilder 

type SortedSetBuilder[T any] struct {
    // contains filtered or unexported fields
}

func NewSortedSetBuilder 

func NewSortedSetBuilder[T any](comparer Comparer[T]) *SortedSetBuilder[T]

func (SortedSetBuilder[T]) Delete 

func (s SortedSetBuilder[T]) Delete(val T)

func (SortedSetBuilder[T]) Has 

func (s SortedSetBuilder[T]) Has(val T) bool

func (SortedSetBuilder[T]) Len 

func (s SortedSetBuilder[T]) Len() int

func (SortedSetBuilder[T]) Set 

func (s SortedSetBuilder[T]) Set(val T)

type SortedSetIterator

SortedSetIterator represents an iterator over a sorted set. Iteration can occur in natural or reverse order based on use of Next() or Prev(). 

type SortedSetIterator[T any] struct {
    // contains filtered or unexported fields
}

func (*SortedSetIterator[T]) Done 

func (itr *SortedSetIterator[T]) Done() bool

Done returns true if no more values remain in the iterator.

func (*SortedSetIterator[T]) First 

func (itr *SortedSetIterator[T]) First()

First moves the iterator to the first value.

func (*SortedSetIterator[T]) Last 

func (itr *SortedSetIterator[T]) Last()

Last moves the iterator to the last value.

func (*SortedSetIterator[T]) Next 

func (itr *SortedSetIterator[T]) Next() (val T, ok bool)

Next moves the iterator to the next value.

func (*SortedSetIterator[T]) Prev 

func (itr *SortedSetIterator[T]) Prev() (val T, ok bool)

Next moves the iterator to the previous value.

func (*SortedSetIterator[T]) Seek 

func (itr *SortedSetIterator[T]) Seek(val T)

Next moves the iterator to the given value.

If the value does not exist then the next value is used. If no more keys exist then the iterator is marked as done.