immutable

package module
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 25, 2023 License: Unlicense Imports: 5 Imported by: 0

README

immutable

import "github.com/reactivego/immutable"

Go Reference

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

Examples

Constants

View Source 
const UnhashableKeyType = MapError("Unhashable Key Type")

Variables

View Source 
var EnableHashCollision = false

Functions

This section is empty.

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 added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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

Len returns the number of entries that are present.

func (Map[K, V]) Lookup added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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

func (MapX[K, V]) Del added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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

Len returns the number of entries that are present.

func (MapX[K, V]) Lookup added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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

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

type Set added in v0.0.2 

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

func (Set[K]) Del added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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

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

func (Set[K]) Len added in v0.0.2 

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

Len returns the number of entries that are present.

func (Set[K]) Put added in v0.0.2 

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 added in v0.0.2 

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

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

func (Set[K]) String added in v0.0.2 

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

String returns a string representation of the keys pairs present.

type Store added in v0.0.2 

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 added in v0.0.2 

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

func (Store[D, K, V]) Del added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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

Len returns the number of entries that are present.

func (Store[D, K, V]) Put added in v0.0.2 

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 added in v0.0.2 

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 added in v0.0.2 

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

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.