immutable

README

immutable

import "github.com/reactivego/immutable"

Package immutable provides an immutable persistent Map type. A Map is a collection of unordered key:value pairs.

package main

import (
    "fmt"
    "github.com/reactivego/immutable"
)

func main() {
	var m immutable.Map[string, string]

	m = m.Set("Hello", "World!")

	fmt.Println(m)
	// Output:
	// {Hello:World!}
}

package main

import (
    "fmt"
    "github.com/reactivego/immutable"
)

func main() {
	var m immutable.Map[string, int]

	m = m.Set("first", 123).Set("second", 456).Set("first", 789)

	m.Range(func(key string, value int) bool {
		fmt.Println(key, value)
		return true
	})

	// Unordered Output:
	// first 789
	// second 456
}

package main

import (
    "fmt"
    "github.com/reactivego/immutable"
)

func main() {
	// Key is comparable (i.e. == and !=) but not hashable.
	// Notice that the key is a struct with unexported fields that are not
	// marshalled by the default json.Marshal function.
	type key struct{ A, B, c int }

	// Map with a marshal function to convert the key to []byte for hashing.
	m := immutable.MapWith[key, string](json.Marshal)

	m = m.Set(key{1, 2, 3}, "Mammalia is the class of mammals.")
	m = m.Set(key{1, 2, 4}, "Aves is the class of birds.")

	b, e := json.Marshal(key{1, 2, 3})
	fmt.Println(string(b), e)
	fmt.Println(m.Get(key{1, 2, 3}))
	fmt.Println(m.Get(key{1, 2, 4})) // same hash as key{1, 2, 3} because 'c' is not exported.
	fmt.Println(m.Get(key{7, 8, 9}))

	// Output:
	// {"A":1,"B":2} <nil>
	// Mammalia is the class of mammals.
	// Aves is the class of birds.
}

package main

import (
    "fmt"
    "github.com/reactivego/immutable"
)

func main() {
	// Key is comparable (i.e. == and !=) but not hashable.
	type Key struct{ K1, K2 int64 }
	type Topic struct{ Name, Description string }

	// Map with a marshal function to convert the key to []byte for hashing.
	m := immutable.MapWith[Key, Topic](json.Marshal)

	m = m.Set(Key{1, 2}, Topic{"Theme", "This is a topic about theme"})
	fmt.Println(m)
	fmt.Println(m.Get(Key{1, 2}))

	// Output:
	// {{K1:1 K2:2}:{Name:Theme Description:This is a topic about theme}}
	// {Theme This is a topic about theme}
}

package main

import (
    "fmt"
    "github.com/reactivego/immutable"
)

func main() {
	// Topic is an example of data where the key (i.e. Name) is part of the data.
	type Topic struct{ Name, Description string }

	store := immutable.StoreWith(func(t Topic) (string, Topic) {
		return t.Name, t
	})

	store = store.Put(Topic{Name: "Aves", Description: "This topic is about birds."})
	store = store.Put(Topic{Name: "Mammalia", Description: "This topic is about mammals"})
	fmt.Printf("%+v\n", store.Get(Topic{Name: "Mammalia"}))
	fmt.Printf("%+v\n", store.Get(Topic{Name: "Aves"}))

    // Output:
	// {Name:Mammalia Description:This topic is about mammals}
	// {Name:Aves Description:This topic is about birds.}
}

Documentation

Overview

Example (Map)

package main

import (
	"fmt"

	"github.com/reactivego/immutable"
)

func main() {
	var m immutable.Map[string, string]

	m = m.Set("Hello", "World!")

	fmt.Println(m)
}

Output:

{Hello:World!}

Index

• Constants
• Variables
• type Map
  • func (a Map[K, V]) Del(key K) Map[K, V]
  • func (a Map[K, V]) Depth() int
  • func (a Map[K, V]) Get(key K) V
  • func (a Map[K, V]) Has(key K) bool
  • func (a Map[K, V]) Len() int
  • func (a Map[K, V]) Lookup(key K) (V, bool)
  • func (a Map[K, V]) Range(f func(K, V) bool)
  • func (a Map[K, V]) Set(key K, value V) Map[K, V]
  • func (a Map[K, V]) String() string
• type MapError
  • func (e MapError) Error() string
• type MapX
  • func MapWith[K comparable, V any](marshal func(any) ([]byte, error)) MapX[K, V]
  • func (a MapX[K, V]) Del(key K) MapX[K, V]
  • func (a MapX[K, V]) Depth() int
  • func (a MapX[K, V]) Get(key K) V
  • func (a MapX[K, V]) Has(key K) bool
  • func (a MapX[K, V]) Len() int
  • func (a MapX[K, V]) Lookup(key K) (V, bool)
  • func (a MapX[K, V]) Range(f func(K, V) bool)
  • func (a MapX[K, V]) Set(key K, value V) MapX[K, V]
  • func (a MapX[K, V]) String() string
• type Set
  • func (a Set[K]) Del(key K) Set[K]
  • func (a Set[K]) Depth() int
  • func (a Set[K]) Has(key K) bool
  • func (a Set[K]) Len() int
  • func (a Set[K]) Put(key K) Set[K]
  • func (a Set[K]) Range(f func(K) bool)
  • func (a Set[K]) String() string
• type Store
  • func StoreWith[D any, K comparable, V any](splitter func(D) (K, V)) Store[D, K, V]
  • func (a Store[D, K, V]) Del(data D) Store[D, K, V]
  • func (a Store[D, K, V]) Depth() int
  • func (a Store[D, K, V]) Get(data D) any
  • func (a Store[D, K, V]) Has(data D) bool
  • func (a Store[D, K, V]) Len() int
  • func (a Store[D, K, V]) Put(data D) Store[D, K, V]
  • func (a Store[D, K, V]) Range(f func(K, V) bool)
  • func (a Store[D, K, V]) String() string

Examples

• Package (Map)
• Map
• MapX
• MapX.Set
• Store.Put

Constants

const UnhashableKeyType = MapError("Unhashable Key Type")

Variables

var EnableHashCollision = false

Types

type Map

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

Map is a persistent immutable hash array mapped trie (HAMT) with an internal hash function. The key types it supports are either string or any integer type. Keys are directly compared using the '==' operator. Key types other than string or integers need an external hasher.

Example

package main

import (
	"fmt"

	"github.com/reactivego/immutable"
)

func main() {
	var m immutable.Map[string, int]

	m = m.Set("first", 123).Set("second", 456).Set("first", 789)

	m.Range(func(key string, value int) bool {
		fmt.Println(key, value)
		return true
	})
}

Output:

first 789
second 456

func (Map[K, V]) Del

func (a Map[K, V]) Del(key K) Map[K, V]

Del returns a copy of the Map with the entry for the key removed.

func (Map[K, V]) Depth

func (a Map[K, V]) Depth() int

Depth returns the number of levels in the amt. Calling Depth on an empty amt returns 1.

func (Map[K, V]) Get

func (a Map[K, V]) Get(key K) V

Get returns the value for the entry with the given key or zero value when it is not present.

func (Map[K, V]) Has

func (a Map[K, V]) Has(key K) bool

Has returns true when an entry with the given key is present.

func (Map[K, V]) Len

func (a Map[K, V]) Len() int

Len returns the number of entries that are present.

func (Map[K, V]) Lookup

func (a Map[K, V]) Lookup(key K) (V, bool)

Lookup returns the value of an entry associated with a given key along with the value true when the key is present. Otherwise it returns (zero, false).

func (Map[K, V]) Range

func (a Map[K, V]) Range(f func(K, V) bool)

Range calls the given function for every key,value pair present.

func (Map[K, V]) Set

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

Set returns a copy of the Map with the given key,value pair inserted.

func (Map[K, V]) String

func (a Map[K, V]) String() string

String returns a string representation of the key,value pairs present.

type MapError

type MapError string

func (MapError) Error

func (e MapError) Error() string

type MapX

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

MapX is a persistent immutable hash array mapped trie (HAMT) with an external key marshal function. The marshal function will map the key to a byte slice. The byteslice is passed to the internal hash function for the Map. The key itself is stored in the Map verbatim and actually used in compare operations. The marshaled key is only used for hashing.

Example

package main

import (
	"encoding/json"
	"fmt"

	"github.com/reactivego/immutable"
)

func main() {
	// Key is comparable (i.e. == and !=) but not hashable.
	// Notice that the key is a struct with unexported fields that are not
	// marshalled by the default json.Marshal function.
	type key struct{ A, B, c int }

	// Map with a marshal function to convert the key to []byte for hashing.
	m := immutable.MapWith[key, string](json.Marshal)

	m = m.Set(key{1, 2, 3}, "Mammalia is the class of mammals.")
	m = m.Set(key{1, 2, 4}, "Aves is the class of birds.")

	b, e := json.Marshal(key{1, 2, 3})
	fmt.Println(string(b), e)
	fmt.Println(m.Get(key{1, 2, 3}))
	fmt.Println(m.Get(key{1, 2, 4})) // same hash as key{1, 2, 3} because 'c' is not exported.
	fmt.Println(m.Get(key{7, 8, 9}))
}

Output:

{"A":1,"B":2} <nil>
Mammalia is the class of mammals.
Aves is the class of birds.

func MapWith

func MapWith[K comparable, V any](marshal func(any) ([]byte, error)) MapX[K, V]

func (MapX[K, V]) Del

func (a MapX[K, V]) Del(key K) MapX[K, V]

Del returns a copy of the Map with the entry for the key removed.

func (MapX[K, V]) Depth

func (a MapX[K, V]) Depth() int

Depth returns the number of levels in the Map. Calling Depth on an empty amt returns 1.

func (MapX[K, V]) Get

func (a MapX[K, V]) Get(key K) V

Get returns the value for the entry with the given key or nil when it is not present.

func (MapX[K, V]) Has

func (a MapX[K, V]) Has(key K) bool

Has returns true when an entry with the given key is present.

func (MapX[K, V]) Len

func (a MapX[K, V]) Len() int

Len returns the number of entries that are present.

func (MapX[K, V]) Lookup

func (a MapX[K, V]) Lookup(key K) (V, bool)

Lookup returns the value of an entry associated with a given key along with the value true when the key is present. Otherwise it returns (nil, false).

func (MapX[K, V]) Range

func (a MapX[K, V]) Range(f func(K, V) bool)

Range calls the given function for every key,value pair present.

func (MapX[K, V]) Set

func (a MapX[K, V]) Set(key K, value V) MapX[K, V]

Set returns a copy of the Map with the given key,value pair inserted.

Example

package main

import (
	"encoding/json"
	"fmt"

	"github.com/reactivego/immutable"
)

func main() {
	// Key is comparable (i.e. == and !=) but not hashable.
	type Key struct{ K1, K2 int64 }
	type Topic struct{ Name, Description string }

	// Map with a marshal function to convert the key to []byte for hashing.
	m := immutable.MapWith[Key, Topic](json.Marshal)

	m = m.Set(Key{1, 2}, Topic{"Theme", "This is a topic about theme"})
	fmt.Println(m)
	fmt.Println(m.Get(Key{1, 2}))
}

Output:

{{K1:1 K2:2}:{Name:Theme Description:This is a topic about theme}}
{Theme This is a topic about theme}

func (MapX[K, V]) String

func (a MapX[K, V]) String() string

String returns a string representation of the key,value pairs present.

type Set

type Set[K comparable] struct {
	// contains filtered or unexported fields
}

func (Set[K]) Del

func (a Set[K]) Del(key K) Set[K]

Del returns a copy of the Set with the key removed from it.

func (Set[K]) Depth

func (a Set[K]) Depth() int

Depth returns the number of levels in the Set. Calling Depth on an empty amt returns 1.

func (Set[K]) Has

func (a Set[K]) Has(key K) bool

Has returns true when an entry with the given key is present.

func (Set[K]) Len

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

Len returns the number of entries that are present.

func (Set[K]) Put

func (a Set[K]) Put(key K) Set[K]

Put returns a copy of the Set with the key added to it.

func (Set[K]) Range

func (a Set[K]) Range(f func(K) bool)

Range calls the given function for every (key,value) pair present.

func (Set[K]) String

func (a Set[K]) String() string

String returns a string representation of the keys pairs present.

type Store

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

Store is a Hash Array Mapped Trie with an external split function.

func StoreWith

func StoreWith[D any, K comparable, V any](splitter func(D) (K, V)) Store[D, K, V]

func (Store[D, K, V]) Del

func (a Store[D, K, V]) Del(data D) Store[D, K, V]

Del returns a copy of the Store with the key removed from the set.

func (Store[D, K, V]) Depth

func (a Store[D, K, V]) Depth() int

Depth returns the number of levels in the Hamt. Calling Depth on an empty Hamt returns 1.

func (Store[D, K, V]) Get

func (a Store[D, K, V]) Get(data D) any

Get returns the value for the entry with the given key or nil when it is not present.

func (Store[D, K, V]) Has

func (a Store[D, K, V]) Has(data D) bool

Has returns true when an entry with the given key is present.

func (Store[D, K, V]) Len

func (a Store[D, K, V]) Len() int

Len returns the number of entries that are present.

func (Store[D, K, V]) Put

func (a Store[D, K, V]) Put(data D) Store[D, K, V]

Put returns a copy of the Set with the key as part of the set.

Example

package main

import (
	"fmt"

	"github.com/reactivego/immutable"
)

func main() {
	// Topic is an example of data where the key (i.e. Name) is part of the data.
	type Topic struct{ Name, Description string }

	store := immutable.StoreWith(func(t Topic) (string, Topic) {
		return t.Name, t
	})

	store = store.Put(Topic{Name: "Aves", Description: "This topic is about birds."})
	store = store.Put(Topic{Name: "Mammalia", Description: "This topic is about mammals"})
	fmt.Printf("%+v\n", store.Get(Topic{Name: "Mammalia"}))
	fmt.Printf("%+v\n", store.Get(Topic{Name: "Aves"}))
}

Output:

{Name:Mammalia Description:This topic is about mammals}
{Name:Aves Description:This topic is about birds.}

func (Store[D, K, V]) Range

func (a Store[D, K, V]) Range(f func(K, V) bool)

Range calls the given function for every key,value pair present.

func (Store[D, K, V]) String

func (a Store[D, K, V]) String() string

String returns a string representation of the key,value pairs present.