package immutable

Import Path
	github.com/benbjohnson/immutable (on go.dev)

Dependency Relation
	imports 6 packages, and imported by one package

Involved Source Files

	  d immutable.go
		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.
Package-Level Type Names (total 11)

	/* sort by: alphabet | popularity */
	 type Comparer[K] (interface)

		Type Parameters:
			K: constraints.Ordered

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

		Methods (only one)
			( Comparer[K]) Compare(a, b K) int
				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.

		As Outputs Of (at least one exported)
			func NewComparer[K](key K) Comparer[K]
		As Inputs Of (at least 2)
			func NewSortedMap[K, V](comparer Comparer[K]) *SortedMap[K, V]
			func NewSortedMapBuilder[K, V](comparer Comparer[K]) *SortedMapBuilder[K, V]

	 type Hasher[K] (interface)

		Type Parameters:
			K: constraints.Ordered

		Hasher hashes keys and checks them for equality.

		Methods (total 2)
			( Hasher[K]) Equal(a, b K) bool
				Returns true if a and b are equal.

			( Hasher[K]) Hash(key K) uint32
				Computes a hash for key.

		As Outputs Of (at least one exported)
			func NewHasher[K](key K) Hasher[K]
		As Inputs Of (at least 2)
			func NewMap[K, V](hasher Hasher[K]) *Map[K, V]
			func NewMapBuilder[K, V](hasher Hasher[K]) *MapBuilder[K, V]

	 type List[T] (struct)

		Type Parameters:
			T: comparable

		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.

		Methods (total 7)
			(*List[T]) Append(value T) *List[T]
				Append returns a new list with value added to the end of the list.

			(*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.

			(*List[T]) Iterator() *ListIterator[T]
				Iterator returns a new iterator for this list positioned at the first index.

			(*List[T]) Len() int
				Len returns the number of elements in the list.

			(*List[T]) Prepend(value T) *List[T]
				Prepend returns a new list with value added to the beginning of the list.

			(*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.

			(*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.

		As Outputs Of (at least 6)
			func NewList[T]() *List[T]
			func (*List)[T].Append(value T) *List[T]
			func (*List)[T].Prepend(value T) *List[T]
			func (*List)[T].Set(index int, value T) *List[T]
			func (*List)[T].Slice(start, end int) *List[T]
			func (*ListBuilder)[T].List() *List[T]

	 type ListBuilder[T] (struct)

		Type Parameters:
			T: comparable

		ListBuilder represents an efficient builder for creating new Lists.

		Methods (total 8)
			(*ListBuilder[T]) Append(value T)
				Append adds value to the end of the list.

			(*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.

			(*ListBuilder[T]) Iterator() *ListIterator[T]
				Iterator returns a new iterator for the underlying list.

			(*ListBuilder[T]) Len() int
				Len returns the number of elements in the underlying list.

			(*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.

			(*ListBuilder[T]) Prepend(value T)
				Prepend adds value to the beginning of the list.

			(*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.

			(*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.

		As Outputs Of (at least one exported)
			func NewListBuilder[T]() *ListBuilder[T]

	 type ListIterator[T] (struct)

		Type Parameters:
			T: comparable

		ListIterator represents an ordered iterator over a list.

		Methods (total 6)
			(*ListIterator[T]) Done() bool
				Done returns true if no more elements remain in the iterator.

			(*ListIterator[T]) First()
				First positions the iterator on the first index.
				If source list is empty then no change is made.

			(*ListIterator[T]) Last()
				Last positions the iterator on the last index.
				If source list is empty then no change is made.

			(*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.

			(*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.

			(*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.

		As Outputs Of (at least 2)
			func (*List)[T].Iterator() *ListIterator[T]
			func (*ListBuilder)[T].Iterator() *ListIterator[T]

	 type Map[K, V] (struct)

		Type Parameters:
			K: constraints.Ordered
			V: any

		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.

		Methods (total 5)
			(*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.

			(*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.

			(*Map[K, V]) Iterator() *MapIterator[K, V]
				Iterator returns a new iterator for the map.

			(*Map[K, V]) Len() int
				Len returns the number of elements in the map.

			(*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.

		As Outputs Of (at least 4)
			func NewMap[K, V](hasher Hasher[K]) *Map[K, V]
			func (*Map)[K, V].Delete(key K) *Map[K, V]
			func (*Map)[K, V].Set(key K, value V) *Map[K, V]
			func (*MapBuilder)[K, V].Map() *Map[K, V]

	 type MapBuilder[K, V] (struct)

		Type Parameters:
			K: constraints.Ordered
			V: any

		MapBuilder represents an efficient builder for creating Maps.

		Methods (total 6)
			(*MapBuilder[K, V]) Delete(key K)
				Delete removes the given key. See Map.Delete() for additional details.

			(*MapBuilder[K, V]) Get(key K) (value V, ok bool)
				Get returns the value for the given key.

			(*MapBuilder[K, V]) Iterator() *MapIterator[K, V]
				Iterator returns a new iterator for the underlying map.

			(*MapBuilder[K, V]) Len() int
				Len returns the number of elements in the underlying map.

			(*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.

			(*MapBuilder[K, V]) Set(key K, value V)
				Set sets the value of the given key. See Map.Set() for additional details.

		As Outputs Of (at least one exported)
			func NewMapBuilder[K, V](hasher Hasher[K]) *MapBuilder[K, V]

	 type MapIterator[K, V] (struct)

		Type Parameters:
			K: constraints.Ordered
			V: any

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

		Methods (total 3)
			(*MapIterator[K, V]) Done() bool
				Done returns true if no more elements remain in the iterator.

			(*MapIterator[K, V]) First()
				First resets the iterator to the first key/value pair.

			(*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.

		As Outputs Of (at least 2)
			func (*Map)[K, V].Iterator() *MapIterator[K, V]
			func (*MapBuilder)[K, V].Iterator() *MapIterator[K, V]

	 type SortedMap[K, V] (struct)

		Type Parameters:
			K: constraints.Ordered
			V: any

		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.

		Methods (total 5)
			(*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.

			(*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.

			(*SortedMap[K, V]) Iterator() *SortedMapIterator[K, V]
				Iterator returns a new iterator for this map positioned at the first key.

			(*SortedMap[K, V]) Len() int
				Len returns the number of elements in the sorted map.

			(*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.

		As Outputs Of (at least 4)
			func NewSortedMap[K, V](comparer Comparer[K]) *SortedMap[K, V]
			func (*SortedMap)[K, V].Delete(key K) *SortedMap[K, V]
			func (*SortedMap)[K, V].Set(key K, value V) *SortedMap[K, V]
			func (*SortedMapBuilder)[K, V].Map() *SortedMap[K, V]

	 type SortedMapBuilder[K, V] (struct)

		Type Parameters:
			K: constraints.Ordered
			V: any

		SortedMapBuilder represents an efficient builder for creating sorted maps.

		Methods (total 6)
			(*SortedMapBuilder[K, V]) Delete(key K)
				Delete removes the given key. See SortedMap.Delete() for additional details.

			(*SortedMapBuilder[K, V]) Get(key K) (value V, ok bool)
				Get returns the value for the given key.

			(*SortedMapBuilder[K, V]) Iterator() *SortedMapIterator[K, V]
				Iterator returns a new iterator for the underlying map positioned at the first key.

			(*SortedMapBuilder[K, V]) Len() int
				Len returns the number of elements in the underlying map.

			(*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.

			(*SortedMapBuilder[K, V]) Set(key K, value V)
				Set sets the value of the given key. See SortedMap.Set() for additional details.

		As Outputs Of (at least one exported)
			func NewSortedMapBuilder[K, V](comparer Comparer[K]) *SortedMapBuilder[K, V]

	 type SortedMapIterator[K, V] (struct)

		Type Parameters:
			K: constraints.Ordered
			V: any

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

		Methods (total 6)
			(*SortedMapIterator[K, V]) Done() bool
				Done returns true if no more key/value pairs remain in the iterator.

			(*SortedMapIterator[K, V]) First()
				First moves the iterator to the first key/value pair.

			(*SortedMapIterator[K, V]) Last()
				Last moves the iterator to the last key/value pair.

			(*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.

			(*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.

			(*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.

		As Outputs Of (at least 2)
			func (*SortedMap)[K, V].Iterator() *SortedMapIterator[K, V]
			func (*SortedMapBuilder)[K, V].Iterator() *SortedMapIterator[K, V]


Package-Level Functions (total 8)

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

		Type Parameters:
			K: constraints.Ordered

		NewComparer returns the built-in comparer for a given key type.

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

		Type Parameters:
			K: constraints.Ordered

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

	 func NewList[T]() *List[T]

		Type Parameters:
			T: comparable

		NewList returns a new empty instance of List.

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

		Type Parameters:
			T: comparable

		NewListBuilder returns a new instance of ListBuilder.

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

		Type Parameters:
			K: constraints.Ordered
			V: any

		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 NewMapBuilder[K, V](hasher Hasher[K]) *MapBuilder[K, V]

		Type Parameters:
			K: constraints.Ordered
			V: any

		NewMapBuilder returns a new instance of MapBuilder.

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

		Type Parameters:
			K: constraints.Ordered
			V: any

		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 NewSortedMapBuilder[K, V](comparer Comparer[K]) *SortedMapBuilder[K, V]

		Type Parameters:
			K: constraints.Ordered
			V: any

		NewSortedMapBuilder returns a new instance of SortedMapBuilder.

The pages are generated with Golds v0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.