collections

Documentation

Index

• type ChangeArgs
• type Clippable
• type Collection
• type Combiner
• type Container
• type Countable
• type Dictionary
• type Enumerable
• type Enumerator
• type Getter
• type Iterable
• type Iterator
• type List
• type Listable
• type OnChanger
• type Peeker
• type Predicate
• type Queue
• type ReadonlyDictionary
• type ReadonlyList
• type ReadonlyQueue
• type ReadonlySet
• type ReadonlyStack
• type Reducer
• type Selector
• type Set
• type Sliceable
• type Stack
• type Tuple
• type Tuple1
• type Tuple2
• type Tuple3
• type Tuple4
• type Window

Types

type ChangeArgs

type ChangeArgs interface {
	// Type gets the type of change that caused the OnChange event to invoke.
	Type() changeType.ChangeType
}

ChangeArgs is the value returned by an OnChange event.

type Clippable

type Clippable interface {
	// Clip removes any excess capacity.
	//
	// If there is no capacity, this will have no effect.
	Clip()
}

Clippable is an interface for data which can have excess capacity removed.

Not all clippable data structures will be able to have capacity.

type Collection

type Collection[T any] interface {
	Enumerable[T]
	Countable
	utils.Stringer
	utils.Equatable

	// Empty indicates if the collection is empty.
	Empty() bool
}

Collection is a collection of values.

type Combiner

type Combiner[TFirst, TSecond, TOut any] func(first TFirst, second TSecond) TOut

Combiner is a function which merges the two given values into one value.

type Container

type Container[T any] interface {
	// Contains determines if the given value exists in the collection.
	// This method works as a predicate.
	Contains(value T) bool
}

Container is a data collection that can be queried to determine if a specific value is in the collection.

type Countable

type Countable interface {
	// Count is the number of values in this object.
	Count() int
}

Countable is an object which has a countable number of values in it.

type Dictionary

type Dictionary[TKey comparable, TValue any] interface {
	ReadonlyDictionary[TKey, TValue]

	// Add will add or overwrite the key with the given value.
	// Returns true if the key was added or, if the key
	// existed but the value is different, otherwise returns false.
	Add(key TKey, value TValue) bool

	// AddIfNotSet will add the given key with the given value if the
	// given key doesn't exist. If the key exists the value is not overwritten.
	// Returns true if the key was added or false if not added.
	AddIfNotSet(key TKey, value TValue) bool

	// AddFrom adds all the key/value pairs from the tuples.
	// This will overwrite any existing value with the same key.
	// Returns true if any key/value was added or overwritten,
	// false if none were changed.
	AddFrom(e Enumerator[Tuple2[TKey, TValue]]) bool

	// AddIfNotSetFrom adds all the key/value pairs
	// from the tuples for each key that doesn't exist.
	// If the key exists the value is not overwritten.
	// Returns true if any key was added, false if none were added.
	AddIfNotSetFrom(e Enumerator[Tuple2[TKey, TValue]]) bool

	// AddMap adds all the key/value pairs from the map.
	// This will overwrite any existing value with the same key.
	// Returns true if any key/value was added or overwritten,
	// false if none were changed.
	AddMap(m map[TKey]TValue) bool

	// AddIfNotSetMap adds all the key/value pairs from the map
	// for each key that doesn't exist.
	// If the key exists the value is not overwritten.
	// Returns true if any key was added, false if none were added.
	AddMapIfNotSet(m map[TKey]TValue) bool

	// Remove removes the given keys.
	// Returns true if any key existed and was removed, false if none of the keys existed.
	Remove(keys ...TKey) bool

	// RemoveIf removes the keys that the predicate returns true for.
	// Returns true if any key was removed, false if nothing was removed.
	RemoveIf(p Predicate[TKey]) bool

	// Clear removes all the values from the dictionary.
	Clear()

	// Clones this dictionary.
	Clone() Dictionary[TKey, TValue]

	// Readonly gets a readonly version of this dictionary.
	//
	// The readonly version points back to this dictionary
	// but is not able to be cast into this dictionary.
	Readonly() ReadonlyDictionary[TKey, TValue]
}

Dictionary is the interface for key/value pairs.

The keys are unique. Depending on the implementation the keys may be in sorted order or not.

type Enumerable

type Enumerable[T any] interface {
	// Enumerate gets an enumerator for this objects data.
	Enumerate() Enumerator[T]
}

Enumerable is an interface for an object which can have its data enumerated.

type Enumerator

type Enumerator[T any] interface {
	Countable
	Sliceable[T]
	utils.Equatable

	// Iterate creates a new iterator
	Iterate() Iterator[T]

	// Where filters the enumeration to only values which satisfy the predicate.
	Where(p Predicate[T]) Enumerator[T]

	// WhereNot filters the enumeration to only values which do not satisfy the predicate.
	WhereNot(p Predicate[T]) Enumerator[T]

	// NotNil filters the enumeration to only values which are not nil.
	NotNil() Enumerator[T]

	// NotZero filters the enumeration to only values which are not zero.
	NotZero() Enumerator[T]

	// Any determines if any value in the enumerator satisfies the given predicate.
	Any(p Predicate[T]) bool

	// All determines if all of the values in the enumerator satisfies the given predicate.
	// This will return true if the enumerator is empty.
	All(p Predicate[T]) bool

	// Foreach runs the given function for each values from the given enumerator.
	//
	// Use an `All` if your foreach needs to escape early,
	Foreach(m func(value T))

	// DoUntilError runs the given function for each value from the given enumerator.
	// If any error occurs, the error will be returned right away,
	// if no error occurs, then nil is returned.
	DoUntilError(m func(value T) error) error

	// StepsUntil determines the number of values in the enumerator are read until
	// a value satisfies the given predicate.
	//
	// The count will not include the value which satisfied the predicate such that
	// if the first value satisfies the predicate then this will return zero.
	// If no value satisfies the predicate then -1 is returned.
	StepsUntil(p Predicate[T]) int

	// Empty determines if the enumerator has no values.
	Empty() bool

	// AtLeast determines if there are at least the given number of values.
	// This is faster than using count so use when an exact count isn't needed.
	AtLeast(min int) bool

	// AtMost determines if there are at most the given number of values.
	// This is faster than using count so use when an exact count isn't needed.
	AtMost(max int) bool

	// First returns the first value in the enumerator with true,
	// or zero value with false if the enumerator is empty.
	First() (T, bool)

	// Last returns the last value in the enumerator with true,
	// or zero value with false if the enumerator is empty.
	Last() (T, bool)

	// Single returns the only value if there is only one value.
	// If there are no values or more than one then zero and false is returned.
	Single() (T, bool)

	// Skip skips over the given count of values before returning the rest.
	Skip(count int) Enumerator[T]

	// SkipWhile skips over values until the given predicate returns false.
	// The values from the given enumerator are returned after and including
	// the first false from the predicate.
	SkipWhile(p Predicate[T]) Enumerator[T]

	// Take enumerates the given number of values before stopping enumeration.
	Take(count int) Enumerator[T]

	// TakeWhile enumerates the values until the given predicate returns false.
	// The values are returned until and excluding the first false from the predicate.
	TakeWhile(p Predicate[T]) Enumerator[T]

	// Replace replaces or returns values using the given replacer function.
	Replace(replacer Selector[T, T]) Enumerator[T]

	// Reverse enumerates the values in the opposite order.
	Reverse() Enumerator[T]

	// Strings enumerates the string of each value.
	Strings() Enumerator[string]

	// Quotes enumerates the string of each value quoted.
	Quotes() Enumerator[string]

	// Trim converts all the values into strings and trims any whitespace
	// from the front and end of the strings.
	Trim() Enumerator[string]

	// Join converts all the values into strings and joins
	// them with the given separator.
	Join(sep string) string

	// Append enumerates all the values in the enumerator
	// followed by the given tail value.
	Append(tails ...T) Enumerator[T]

	// Concat enumerates all the values in the enumerator
	// followed by the values enumerators from the given tail.
	Concat(tails ...Enumerator[T]) Enumerator[T]

	// SortInterweave creates an enumerator that is the two given enumerators interwoven
	// such that both lists keep their order but lowest value from each list is used first.
	//
	// If the two enumerators are sorted, this will effectively merge sort the values.
	// This can take an optional comparer to override the default comparer
	// or to give a comparer if there is no default comparer for this type.
	SortInterweave(other Enumerator[T], comparer ...utils.Comparer[T]) Enumerator[T]

	// Sorted determines if the values in the enumerator are already sorted.
	//
	// This can take an optional comparer to override the default comparer
	// or to give a comparer if there is no default comparer for this type.
	Sorted(comparer ...utils.Comparer[T]) bool

	// Sort enumerates the values in sorted order.
	//
	// This can take an optional comparer to override the default comparer
	// or to give a comparer if there is no default comparer for this type.
	Sort(comparer ...utils.Comparer[T]) Enumerator[T]

	// Merge preforms a merge of the values in the given enumerator.
	//
	// The merge method is called with the prior returned value from the previous call.
	// The first value is used as the prior value with the second value in the merger.
	// The last returned value from merge is returned, the first value if there
	// is only one value, or the zero value if no values.
	Merge(merger Reducer[T, T]) T

	// Max gets the maximum value from all the values.
	//
	// This can take an optional comparer to override the default comparer
	// or to give a comparer if there is no default comparer for this type.
	Max(comparer ...utils.Comparer[T]) T

	// Min gets the minimum value from all the values.
	//
	// This can take an optional comparer to override the default comparer
	// or to give a comparer if there is no default comparer for this type.
	Min(comparer ...utils.Comparer[T]) T

	// Buffered stores the result of an enumeration and repeats it back
	// in the returned enumerator. Uses memory to reduce calculations.
	// This will not read from this enumerator only when needed.
	Buffered() Enumerator[T]

	// StartsWith determines if the first enumerator starts with the given prefix.
	StartsWith(other Enumerator[T]) bool
}

Enumerator is a tool for walking through a collection of data.

type Getter

type Getter[TIn, TOut any] interface {
	// Get gets a value at the given index or key.
	//
	// Typically, if the index is out-of-bounds, this will panic.
	// However, if this is getting a value with a key that doesn't exist
	// it will typically return the zero value.
	Get(index TIn) TOut

	// TryGet gets a value at the given index or key.
	//
	// If the key exists or the index is in bounds then the found value
	// is returned with a true, otherwise if the key doesn't exist or
	// the index is out-of-bounds then the zero value is returned with false.
	TryGet(index TIn) (TOut, bool)
}

Getter is an object which can get data at a given index or key.

In other languages this would be an indexer. For example in C# this would be `public T this[int i]{ get; }`, but with Go's flair of allowing one or two returns, like when reading from a map in Go.

type Iterable

type Iterable[T any] func() Iterator[T]

Iterable is a function which constructs a new instance of an iterator.

type Iterator

type Iterator[T any] interface {
	// Next steps this iterator the next value and updates Current.
	//
	// After creation `Next` should be called to prime the iterator
	// to the first value in the set.
	Next() bool

	// Current value in the iterator.
	//
	// This will return the zero value after creation until
	// the first time `Next` is called.
	Current() T
}

Iterator is an object to step through a set of values as part of an enumeration of values.

Typical usage of an iterator is to use it in a while loop:

```Go var it Iterator[T] = //...

for it.Next() {
   it.Current()
}

```

type List

type List[T any] interface {
	ReadonlyList[T]

	// Prepend adds a new values to the front of the list.
	// The values will end up in the list in the same order they are given.
	Prepend(values ...T)

	// PrependFrom adds a new values to the front of the list.
	// The values will end up in the list in the same order they are given.
	PrependFrom(e Enumerator[T])

	// Append adds a new  values to the back of the list.
	// The values will end up in the list in the same order they are given.
	Append(values ...T)

	// AppendFrom adds a new  values to the back of the list.
	// The values will end up in the list in the same order they are given.
	AppendFrom(e Enumerator[T])

	// TakeFirst removes one value from the front of the list.
	// If the list is empty, this will panic.
	TakeFirst() T

	// TakeLast removes one value from the back of the list.
	// If the list is empty, this will panic.
	TakeLast() T

	// TakeFront remove the given number of values from the front of list.
	// It will return less values if the list is shorter than the count.
	TakeFront(count int) List[T]

	// TakeBack remove the given number of values from the back of list.
	// It will return less values if the list is shorter than the count.
	TakeBack(count int) List[T]

	// Insert adds the given values into the list at the given location.
	// If the index is zero, then these values will be added to the front of the list.
	// If the index is the length of the list, then the values will be added to the back of the list.
	Insert(index int, values ...T)

	// InsertFrom adds the values from the given enumerator into the list at the given location.
	// If the index is zero, then these values will be added to the front of the list.
	// If the index is the length of the list, then the values will be added to the back of the list.
	InsertFrom(index int, e Enumerator[T])

	// Remove removes the given number of values from the given index.
	Remove(index, count int)

	// RemoveIf removes all the values which return true for the given predicate.
	RemoveIf(handle Predicate[T]) bool

	// Set sets the values starting with the given index.
	// The index must [0..count] to be valid.
	// If there are more values given than already exist in the list,
	// the remaining will be appended.
	Set(index int, values ...T)

	// SetFrom sets the values starting with the given index.
	// If there are more values given than already exist in the list,
	// the remaining will be appended.
	SetFrom(index int, e Enumerator[T])

	// Clear removes all the values from the whole list, leaving the list empty.
	Clear()

	// Clones this list.
	Clone() List[T]

	// Readonly gets a readonly version of this list that will stay up-to-date
	// with this list but will not allow changes itself.
	Readonly() ReadonlyList[T]
}

List is a linear collection of values.

type Listable

type Listable[T any] interface {
	// ToList returns the values as a list.
	//
	// Typically the list will be an array or sliced
	// based list but may, for some cases, be a linked list.
	ToList() List[T]
}

Listable is an object which can get the data as a List.

type OnChanger

type OnChanger interface {
	// OnChange gets the event that is invoked on change.
	OnChange() events.Event[ChangeArgs]
}

OnChanger is an object which can emit a change event.

type Peeker

type Peeker[T any] interface {
	// Peek peeks at the next value, without removing it.
	//
	// This will panic if there are no values that can be peeked.
	Peek() T

	// TryPeek peeks at the next value, without removing it.
	//
	// Returns zero and false if there are no values that can be peeked.
	TryPeek() (T, bool)
}

Peeker is an object which can peek data from the location that data is usually taken from in the object.

type Predicate

type Predicate[T any] func(value T) bool

Predicate is a function that takes a value and returns a boolean.

Typically predicates are used to answer some question like "is equal" or "contains".

type Queue

type Queue[T any] interface {
	ReadonlyQueue[T]
	Clippable

	// Enqueue adds all the given values into
	// the queue in the order that they were given in.
	Enqueue(values ...T)

	// EnqueueFrom adds all the values from the given enumerator
	// onto the queue in the order that they were given in.
	EnqueueFrom(e Enumerator[T])

	// Take dequeues the given number of values from the queue.
	// It will return less values if the queue is shorter than the count.
	Take(count int) []T

	// Dequeue removes and returns one value from the queue.
	// If there are no values in the queue, this will panic.
	Dequeue() T

	// TryDequeue removes and returns one value from the queue.
	// Returns zero and false if there are no values in the queue.
	TryDequeue() (T, bool)

	// Clear removes all the values from the queue.
	Clear()

	// Clone makes a copy of this queue.
	Clone() Queue[T]

	// Readonly gets a readonly version of this queue that will stay up-to-date
	// with this queue but will not allow changes itself.
	Readonly() ReadonlyQueue[T]
}

Queue is a linear collection of values which are FIFO (first in, first out).

type ReadonlyDictionary

type ReadonlyDictionary[TKey comparable, TValue any] interface {
	Collection[Tuple2[TKey, TValue]]
	Container[TKey]
	Getter[TKey, TValue]
	OnChanger

	// Keys enumerates the keys.
	//
	// Depending on the type of dictionary these may
	// be in random order or be sorted.
	Keys() Enumerator[TKey]

	// Values enumerates the values.
	//
	// Depending on the type of dictionary these may
	// be in random order or ordered to match the sorted keys.
	Values() Enumerator[TValue]

	// ToMap creates a map for this dictionary.
	ToMap() map[TKey]TValue
}

ReadonlyDictionary is the interface for key value pairs which can not be directly modified.

The keys are unique. Depending on the implementation the keys may be in sorted order or not.

type ReadonlyList

type ReadonlyList[T any] interface {
	Collection[T]
	Sliceable[T]
	Container[T]
	Getter[int, T]
	OnChanger

	// First attempts to get the first value from the list.
	// If the list is empty, this will panic.
	First() T

	// Last attempts to get the last value from the list.
	// If the list is empty, this will panic.
	Last() T

	// Backwards gets an enumerator for this list that
	// goes from the end to the front.
	Backwards() Enumerator[T]

	// IndexOf gets the index of the given value type,
	// -1 is returned if the value is not in the list.
	//
	// May have one optional after index to start searching after.
	// If the after index is negative the search starts from the beginning.
	// If the after index is greater or equal to the length then -1 is returned.
	IndexOf(value T, after ...int) int

	// StartsWith determines if the given list of values
	// is at the start of this list.
	StartsWith(other ReadonlyList[T]) bool

	// EndsWith determines if the given list of values
	// is at the end of this list.
	EndsWith(other ReadonlyList[T]) bool
}

ReadonlyList is a readonly linear collection of values.

type ReadonlyQueue

type ReadonlyQueue[T any] interface {
	Collection[T]
	Sliceable[T]
	Listable[T]
	Peeker[T]
	OnChanger
}

ReadonlyQueue is the readonly version of a queue.

type ReadonlySet

type ReadonlySet[T comparable] interface {
	Collection[T]
	Sliceable[T]
	Listable[T]
	Container[T]
	OnChanger
}

ReadonlySet is a readonly version of a set.

For sets, the `ToSlice`, `ToList`, and `Enumerate` methods do not guarantee any specific order and must be considered returning values in random order.

type ReadonlyStack

type ReadonlyStack[T any] interface {
	Collection[T]
	Sliceable[T]
	Listable[T]
	Peeker[T]
	OnChanger
}

ReadonlyStack is the readonly version of a stack.

type Reducer

type Reducer[TIn, TOut any] func(value TIn, prior TOut) TOut

Reducer is a function which merges the given value with the prior value to create a new value to use in next reduce call.

type Selector

type Selector[TIn, TOut any] func(value TIn) TOut

Selector is a function to convert one value type into another.

type Set

type Set[T comparable] interface {
	ReadonlySet[T]

	// Add inserts the given values into the set.
	// Returns true if any value was added, false if all values already existed.
	Add(values ...T) bool

	// AddFrom inserts the values from the given enumerator into the set.
	// Returns true if any value was added, false if all values already existed.
	AddFrom(e Enumerator[T]) bool

	// Remove removes all the given values from the set.
	// Returns true if any values were removed.
	Remove(values ...T) bool

	// RemoveIf removes all the values which return true for the given predicate.
	// Returns true if any values were removed.
	RemoveIf(handle Predicate[T]) bool

	// Clear removes all the values from the set.
	Clear()

	// Clones this set.
	Clone() Set[T]

	// Readonly gets a readonly version of this set.
	//
	// The readonly version points back to this set
	// but is not able to be cast into this set.
	Readonly() ReadonlySet[T]
}

Set is a collection of values in random order which has no repeat values.

For sets, the `ToSlice`, `ToList`, and `Enumerate` methods do not guarantee any specific order and must be considered returning values in random order.

type Sliceable

type Sliceable[T any] interface {
	// ToSlice returns the values as a slice.
	ToSlice() []T

	// CopyToSlice copies as much of the values fit into the given slice.
	CopyToSlice(s []T)
}

Sliceable is an object which can get the data as a slice.

type Stack

type Stack[T any] interface {
	ReadonlyStack[T]
	Clippable

	// Push adds all the given values onto
	// the stack in the order that they were given in.
	Push(values ...T)

	// PushFrom adds all the values from the given enumerator
	// onto the stack in the order that they were given in.
	PushFrom(e Enumerator[T])

	// Take pops the given number of values from the stack.
	// It will return less values if the stack is shorter than the count.
	Take(count int) []T

	// Pop removes and returns one value from the stack.
	// If there are no values in the stack, this will panic.
	Pop() T

	// TryPop removes and returns one value from the stack.
	// Returns zero and false if there are no values in the stack.
	TryPop() (T, bool)

	// TrimTo will remove anything off the back of the stack
	// until the stack is the the given count.
	TrimTo(count int)

	// Clear removes all the values from the stack.
	Clear()

	// Clone makes a copy of this stack.
	Clone() Stack[T]

	// Readonly gets a readonly version of this stack that will stay up-to-date
	// with this stack but will not allow changes itself.
	Readonly() ReadonlyStack[T]
}

Stack is a linear collection of values which are FILO (first in, last out).

type Tuple

type Tuple interface {
	Countable
	Getter[int, any]
	Sliceable[any]
	utils.Stringer
	utils.Equatable
}

Tuple is an object containing several values.

type Tuple1

type Tuple1[T1 any] interface {
	Tuple

	// Value1 gets the value.
	Value1() T1
}

Tuple1 is an object containing one value.

type Tuple2

type Tuple2[T1, T2 any] interface {
	Tuple

	// Value1 gets the first value.
	Value1() T1

	// Value2 gets the second value.
	Value2() T2

	// Values gets all the values in the tuple.
	Values() (T1, T2)
}

Tuple2 is an object containing two values.

type Tuple3

type Tuple3[T1, T2, T3 any] interface {
	Tuple

	// Value1 gets the first value.
	Value1() T1

	// Value2 gets the second value.
	Value2() T2

	// Value3 gets the third value.
	Value3() T3

	// Values gets all the values in the tuple.
	Values() (T1, T2, T3)
}

Triple3 is an object containing three values.

type Tuple4

type Tuple4[T1, T2, T3, T4 any] interface {
	Tuple

	// Value1 gets the first value.
	Value1() T1

	// Value2 gets the second value.
	Value2() T2

	// Value3 gets the third value.
	Value3() T3

	// Value4 gets the fourth value.
	Value4() T4

	// Values gets all the values in the tuple.
	Values() (T1, T2, T3, T4)
}

Triple4 is an object containing four values.

type Window

type Window[TIn, TOut any] func(values []TIn) TOut

Window is a function which handles a sliding window of values and returns a result from that window.