Documentation
¶
Overview ¶
Package immutable provides immutable data structures (map/set/list).
Note that immutable map/set/list only guarantee the immutability of the container itself, not the content inside. For example if you are using a immutable list of pointers, you are guaranteed that you always get the same pointer with the same index, but the content pointer points to might be changed by others sharing the same immutable list.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrBreak = errors.New("immutable: stop iteration")
ErrBreak can be used in Range functions to stop the iteration early.
Functions ¶
This section is empty.
Types ¶
type List ¶
type List[T any] interface { // Len returns the length of the list. Len() int // Get returns the i-th item with 0-index. // // It panics when i is out of [0, Len()-1]. Get(i int) T // Range iterates through the list, in its original order. // // It will return the error returned by f. Range(f ListRangeFunc[T]) error // Reslice returns the sublist from start to end-1 index. // // Use out of range indices will cause panic. Reslice(start, end int) List[T] }
List defines the interface of an immutable list.
Example ¶
package main import ( "fmt" "go.yhsif.com/immutable" ) func main() { list := immutable.ListLiteral("a", "b", "c") fmt.Println("Len:", list.Len()) fmt.Println("list.Get(1):", list.Get(1)) fmt.Println("Break iteration:") list.Range(func(i int, x string) error { if i >= 1 { return immutable.ErrBreak } fmt.Printf("%d: %v\n", i, x) return nil }) fmt.Println("Full iteration:") list.Range(func(i int, x string) error { fmt.Printf("%d: %v\n", i, x) return nil }) fmt.Printf("%%v: %v\n", list) fmt.Println("Reslice(1, 3):", list.Reslice(1, 3)) }
Output: Len: 3 list.Get(1): b Break iteration: 0: a Full iteration: 0: a 1: b 2: c %v: [a b c] Reslice(1, 3): [b c]
func ListLiteral ¶
ListLiteral creates an immutable list from items.
It's shorthand for immutable.NewListBuilder[T]().Append(items...).Build().
type ListBuilder ¶
type ListBuilder[T any] interface { List[T] // Append appends item(s) to the list. // // It returns self for chaining. Append(x ...T) ListBuilder[T] // Build builds the immutable list. Build() List[T] }
ListBuilder defines the interface of an immutable list builder.
It's not guaranteed to be thread-safe and shouldn't be used concurrently.
func NewListBuilder ¶
func NewListBuilder[T any]() ListBuilder[T]
NewListBuilder creates a ListBuilder.
type ListRangeFunc ¶
ListRangeFunc defines the iteration function for List type.
i will be the 0-based index and x will be the item.
Whenever ListRangeFunc returns a non-nil error, the iteration will be stopped. The error will be returned by Range function.
type Map ¶
type Map[K comparable, V any] interface { // Len returns the size of the map. Len() int // Load returns the value to the key. // // If the key is not in the map, value will be zero and ok will be false. Load(key K) (value V, ok bool) // Get returns the value to the key. // // It's the same as Load just without ok return. Get(key K) V // Range iterates through the map. // // It will return the error returned by f. Range(f MapRangeFunc[K, V]) error }
Map defines the interface of an immutable map.
Example ¶
package main import ( "fmt" "go.yhsif.com/immutable" ) func main() { m := immutable.MapLiteral(map[int]string{ 1: "a", }) fmt.Printf("%%v: %v\n", m) m = immutable.MapLiteral(map[int]string{ 1: "a", 2: "b", 3: "c", }) fmt.Println("Len:", m.Len()) fmt.Println("m.Get(1):", m.Get(1)) fmt.Println("range:") m.Range(func(k int, v string) error { fmt.Printf("%v: %v\n", k, v) return nil }) }
Output: %v: map[1:a] Len: 3 m.Get(1): a range: 1: a 2: b 3: c
func EmptyMap ¶ added in v0.1.1
func EmptyMap[K comparable, V any]() Map[K, V]
EmptyMap returns an immutable empty map.
func MapLiteral ¶
func MapLiteral[K comparable, V any](m map[K]V) Map[K, V]
MapLiteral creates an immutable map from existing map.
It's shorthand for immutable.NewMapBuilder[K, V]().Update(m).Build().
type MapBuilder ¶
type MapBuilder[K comparable, V any] interface { Map[K, V] // Set sets the key value pair to the map. // // It returns self for chaining. Set(key K, value V) MapBuilder[K, V] // Update updates every key value pair from m to the map. // // It returns self for chaining. Update(m map[K]V) MapBuilder[K, V] // Build builds the immutable map. Build() Map[K, V] }
MapBuilder defines the interface of an immutable map builder.
It's not guaranteed to be thread-safe and shouldn't be used concurrently.
func NewMapBuilder ¶
func NewMapBuilder[K comparable, V any]() MapBuilder[K, V]
NewMapBuilder creates a new MapBuilder.
type MapRangeFunc ¶
type MapRangeFunc[K comparable, V any] func(key K, value V) error
MapRangeFunc defines the iteration function for Map type.
Whenever MapRangeFunc returns a non-nil error, the iteration will be stopped. The error will be returned by Range function.
type Set ¶
type Set[T comparable] interface { // Len returns the length of the set. Len() int // Contains checks whether an item is in the set. Contains(x T) bool // Range iterates through the set. // // It will return the error returned by f. Range(f SetRangeFunc[T]) error }
Set defines the interface of an immutable set.
Example ¶
package main import ( "fmt" "go.yhsif.com/immutable" ) func main() { s := immutable.SetLiteral("a") fmt.Printf("%%v: %v\n", s) s = immutable.SetLiteral("a", "b", "c") fmt.Println("Len:", s.Len()) fmt.Println(`s.Contains("a"):`, s.Contains("a")) fmt.Println(`s.Contains("d"):`, s.Contains("d")) fmt.Println("range:") s.Range(func(x string) error { fmt.Printf("%v\n", x) return nil }) }
Output: %v: [a] Len: 3 s.Contains("a"): true s.Contains("d"): false range: a b c
func EmptySet ¶ added in v0.1.1
func EmptySet[T comparable]() Set[T]
EmptySet returns an immutable empty set.
func SetLiteral ¶
func SetLiteral[T comparable](items ...T) Set[T]
SetLiteral creates an immutable set from items.
It's shorthand for immutable.NewSetBuilder[T]().Add(items...).Build().
type SetBuilder ¶
type SetBuilder[T comparable] interface { Set[T] // Add adds item(s) to the set. // // It returns self for chaining. Add(x ...T) SetBuilder[T] // Build builds the immutable set. Build() Set[T] }
SetBuilder defines the interface of an immutable set builder.
It's not guaranteed to be thread-safe and shouldn't be used concurrently.
func NewSetBuilder ¶
func NewSetBuilder[T comparable]() SetBuilder[T]
NewSetBuilder creates a new SetBuilder.
type SetRangeFunc ¶
type SetRangeFunc[T comparable] func(x T) error
SetRangeFunc defines the iteration function for Set type.
Whenever SetRangeFunc returns a non-nil error, the iteration will be stopped. The error will be returned by Range function.