Documentation ¶
Overview ¶
This framework provides a simple set of Go based collection types that can be used to address the needs of higher level programming tasks that often involve sequences of items. The collection types are more intuitive and easy to use than the low level native Go array, slice and map types.
Each collection type allows the traversal and manipulation of its items as well as the generation of a canonical formatted string for each collection type that is very useful in debug statements.
The collections use ordinal (position: "first", "second", etc.) based indices instead of cardinal (quantitative: 0, 1, 2, etc.) based indices. One could argue that cardinal based indices might possibly have made sense 70 years ago when assembly languages were mapping directly to memory locations that included index offset amounts. But even back then for programming languages it would probably have made more sense to use ordinal base indices and reserved the value 0 for an invalid index instead of -1.
The various interfaces for the collection types provided by this framework support both positive and negative indices. And since they are ordinal based, the positive and negative indices are symmetrical. You can use an index of 1 to access the first item in a sequence and -1 to access the last item.
For more details on this package see:
Index ¶
- func CompareValues(first any, second any) bool
- func ParseString(str string) any
- func RankReflective(first any, second any) int
- func RankValues(first any, second any) int
- type Associative
- type Attribute
- type Catalog
- func (c *Catalog[K, V]) AddItem(attribute Keyed[K, V])
- func (c *Catalog[K, V]) AddItems(attributes []Keyed[K, V])
- func (c *Catalog[K, V]) GetKeys() []K
- func (c *Catalog[K, V]) GetValue(key K) V
- func (c *Catalog[K, V]) GetValues(keys []K) []V
- func (c *Catalog[K, V]) RemoveAll()
- func (c *Catalog[K, V]) RemoveValue(key K) V
- func (c *Catalog[K, V]) RemoveValues(keys []K) []V
- func (c *Catalog[K, V]) ReverseAttributes()
- func (c *Catalog[K, V]) SetValue(key K, value V) V
- func (c *Catalog[K, V]) SortAttributes()
- func (c *Catalog[K, V]) SortAttributesWithRanker(rank Rank)
- type Compare
- type Contractable
- type Expandable
- type FIFO
- type Formatter
- type FormatterState
- type Indexed
- type Iterator
- type Keyed
- type LIFO
- type List
- func (l *List[T]) AddItem(item T)
- func (l *List[T]) AddItems(items []T)
- func (l *List[T]) ContainsAll(items []T) bool
- func (l *List[T]) ContainsAny(items []T) bool
- func (l *List[T]) ContainsItem(item T) bool
- func (l *List[T]) GetAll() []T
- func (l *List[T]) GetIndex(item T) int
- func (l *List[T]) GetItem(index int) T
- func (l *List[T]) GetItems(first int, last int) []T
- func (l *List[T]) GetSize() int
- func (l *List[T]) InsertItem(slot int, item T)
- func (l *List[T]) InsertItems(slot int, items []T)
- func (l *List[T]) IsEmpty() bool
- func (l *List[T]) RemoveAll()
- func (l *List[T]) RemoveItem(index int) T
- func (l *List[T]) RemoveItems(first int, last int) []T
- func (l *List[T]) ReverseItems()
- func (l *List[T]) SetItem(index int, item T) T
- func (l *List[T]) SetItems(index int, items []T) []T
- func (l *List[T]) ShuffleItems()
- func (l *List[T]) SortItems()
- func (l *List[T]) SortItemsWithRanker(rank Rank)
- type Malleable
- type Queue
- func Fork[T any](wg *sync.WaitGroup, input *Queue[T], size int) []*Queue[T]
- func Join[T any](wg *sync.WaitGroup, inputs []*Queue[T]) *Queue[T]
- func NewQueue[T any]() *Queue[T]
- func NewQueueWithCapacity[T any](capacity int) *Queue[T]
- func Split[T any](wg *sync.WaitGroup, input *Queue[T], size int) []*Queue[T]
- type Rank
- type Ratcheted
- type RecursiveState
- type Searchable
- type Sequential
- type Set
- func (s *Set[T]) AddItem(item T)
- func (s *Set[T]) AddItems(items []T)
- func (s *Set[T]) ContainsAll(items []T) bool
- func (s *Set[T]) ContainsAny(items []T) bool
- func (s *Set[T]) ContainsItem(item T) bool
- func (s *Set[T]) RemoveAll()
- func (s *Set[T]) RemoveItem(item T)
- func (s *Set[T]) RemoveItems(items []T)
- type Stack
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompareValues ¶
This function determines whether or not the specified values are equal using their canonical comparison rules.
func ParseString ¶
func RankReflective ¶
This function returns the ranking order of the specified reflective values using reflection.
func RankValues ¶
This function returns the ranking order of the specified values using their canonical sorting rules.
Types ¶
type Associative ¶
type Associative[K any, V any] interface { GetKeys() []K GetValue(key K) V GetValues(keys []K) []V SetValue(key K, value V) V RemoveValue(key K) V RemoveValues(keys []K) []V RemoveAll() SortAttributes() SortAttributesWithRanker(rank Rank) ReverseAttributes() }
This interface defines the methods supported by all associative collections whose items consist of key-value pair attributes.
type Attribute ¶
This type defines the structure and methods associated with a key-value pair. It directly implements the following interface:
- Keyed[K any, V any]
This type is parameterized as follows:
- K is an ordered type of key.
- V is any type of value.
This structure is used by the catalog type to maintain its associations.
func NewAttribute ¶
This constructor creates a new attribute with the specified key and value.
func (*Attribute[K, V]) GetKey ¶
func (a *Attribute[K, V]) GetKey() K
This method returns the key for this attribute.
type Catalog ¶
type Catalog[K any, V any] struct { // Note: The delegated methods don't see the real collection type. Sequential[Keyed[K, V]] Indexed[Keyed[K, V]] // contains filtered or unexported fields }
This type defines the structure and methods associated with a catalog of key-value pair attributes. It delegates the implemention of the following interfaces to List[Keyed[K, V]]:
- Sequential[Keyed[K, V]]
- Indexed[Keyed[K, V]]
And it directly implements the following interfaces using the same list and a Go map structure:
- Expandable[Keyed[K, V]]
- Associative[K, V]
This type is parameterized as follows:
- K is a primitive Go type of ordered key.
- V is any type of value.
func Extract ¶
This function returns a new catalog containing only the attributes that are in the specified catalog that have the specified keys. The attributes in the resulting catalog will be in the same order as the specified keys.
func Merge ¶
This function returns a new catalog containing all of the attributes that are in the specified catalogs in the order that they appear in each catalog.
func NewCatalog ¶
This constructor creates a new empty catalog.
func (*Catalog[K, V]) AddItem ¶
This method appends the specified attribute to the end of this catalog.
func (*Catalog[K, V]) AddItems ¶
This method appends the specified attributes to the end of this catalog.
func (*Catalog[K, V]) GetKeys ¶
func (c *Catalog[K, V]) GetKeys() []K
This method returns the keys for this catalog.
func (*Catalog[K, V]) GetValue ¶
func (c *Catalog[K, V]) GetValue(key K) V
This method returns the value that is associated with the specified key in this catalog.
func (*Catalog[K, V]) GetValues ¶
func (c *Catalog[K, V]) GetValues(keys []K) []V
This method returns the values associated with the specified keys for this catalog. The values are returned in the same order as the keys in the catalog.
func (*Catalog[K, V]) RemoveAll ¶
func (c *Catalog[K, V]) RemoveAll()
This method removes all attributes from this catalog.
func (*Catalog[K, V]) RemoveValue ¶
func (c *Catalog[K, V]) RemoveValue(key K) V
This method removes the attribute associated with the specified key from the catalog and returns it.
func (*Catalog[K, V]) RemoveValues ¶
func (c *Catalog[K, V]) RemoveValues(keys []K) []V
This method removes the attributes associated with the specified keys from the catalog and returns the removed values.
func (*Catalog[K, V]) ReverseAttributes ¶
func (c *Catalog[K, V]) ReverseAttributes()
This method reverses the order of all attributes in this catalog.
func (*Catalog[K, V]) SetValue ¶
func (c *Catalog[K, V]) SetValue(key K, value V) V
This method sets the value associated with the specified key to the specified value and returns the old value if one already existed in the catalog.
func (*Catalog[K, V]) SortAttributes ¶
func (c *Catalog[K, V]) SortAttributes()
This method sorts this catalog using the canonical rank function to compare the keys.
func (*Catalog[K, V]) SortAttributesWithRanker ¶
This method sorts this catalog using the specified rank function to compare the keys.
type Compare ¶
This type defines the function signature for any function that can determine whether or not two specified values are equal to each other.
type Contractable ¶
type Contractable[T any] interface { RemoveItem(item T) RemoveItems(items []T) RemoveAll() }
This interface defines the methods supported by all collections of items that allow additional items to be added to them.
type Expandable ¶
type Expandable[T any] interface { AddItem(item T) AddItems(items []T) }
This interface defines the methods supported by all collections of items that allow additional items to be added to them.
type FIFO ¶
This interface defines the methods supported by all collections whose items are accessed using first-in-first-out (FIFO) semantics.
type Formatter ¶
type Formatter struct {
// contains filtered or unexported fields
}
This type defines the structure and methods for a canonical formatting agent.
func NewFormatter ¶
func NewFormatter() *Formatter
This constructor creates a new instance of a formatter that can be used to generate the canonical string format for any value.
func NewFormatterWithIndentation ¶
This constructor creates a new instance of a formatter that can be used to generate the canonical string format for any value using the specified initial indentation level.
func (*Formatter) FormatValue ¶
This method returns the canonical string for the specified value.
func (*Formatter) GetIndentation ¶
This method returns the number of levels that each line is indented in the resulting canonical string.
type FormatterState ¶
type FormatterState struct { RecursiveState // contains filtered or unexported fields }
This type defines the structure and methods for the state of a formatting agent. The formatted state uses a string builder to maintain the growing formatted string.
func NewFormatterState ¶
func NewFormatterState(indentation int) *FormatterState
This constructor creates a new instance of a formatted state that can be used to hold the formatted string indented to the specified initial level.
func (*FormatterState) AppendNewline ¶
func (s *FormatterState) AppendNewline()
This method appends a properly indented newline to the result.
func (*FormatterState) AppendString ¶
func (s *FormatterState) AppendString(str string)
This method appends the specified string to the result.
func (*FormatterState) GetIndentation ¶
func (s *FormatterState) GetIndentation() int
This method returns the number of levels that each line is indented in the resulting canonical string.
func (*FormatterState) GetResult ¶
func (s *FormatterState) GetResult() string
This method returns the canonical string result.
type Indexed ¶
type Indexed[T any] interface { GetItem(index int) T GetItems(first int, last int) []T GetIndex(item T) int }
This interface defines the methods supported by all collections whose items can be indexed. The indexing of an indexed collection is ORDINAL based, rather than ZERO based (which is "SO last century"). This allows for positive indices starting at the beginning of the collection, and negative indices starting at the end of the collection as follows:
1 2 3 N [item 1] . [item 2] . [item 3] ... [item N] -N -(N-1) -(N-2) -1
Because the indices are ordinal based, the positive and negative indices are symmetrical.
type Iterator ¶
type Iterator[T any] struct { // contains filtered or unexported fields }
This type defines the structure and methods for a ratcheted iterator agent. It directly implements the following interfaces:
- Ratcheted[T any]
The iterator operates on a sequence of items and is backed by an immutable native Go array.
func NewIterator ¶
func NewIterator[T any](sequence Sequential[T]) *Iterator[T]
This constructor creates a new instance of an iterator that can be used to traverse the items in the specified array.
func (*Iterator[T]) GetNext ¶
func (i *Iterator[T]) GetNext() T
This method retrieves the item after the current slot.
func (*Iterator[T]) GetPrevious ¶
func (i *Iterator[T]) GetPrevious() T
This method retrieves the item before the current slot.
func (*Iterator[T]) GetSlot ¶
This method returns the current slot between items that this iterator is currently locked into.
func (*Iterator[T]) HasNext ¶
This method determines whether or not there is an item after the current slot.
func (*Iterator[T]) HasPrevious ¶
This method determines whether or not there is an item before the current slot.
func (*Iterator[T]) ToEnd ¶
func (i *Iterator[T]) ToEnd()
This method moves this iterator to the slot after the last item.
type Keyed ¶
This interface defines the methods supported by all keyed types. A keyed type associates a key with a value.
type LIFO ¶
This interface defines the methods supported by all collections whose items are accessed using last-in-first-out (LIFO) semantics.
type List ¶
type List[T any] struct { // contains filtered or unexported fields }
This type defines the structure and methods associated with a list of items. Each item is associated with an implicit positive integer index. It directly implements the following interfaces using a Go array/slice:
- Sequential[T]
- Indexed[T]
- Searchable[T]
- Expandable[T]
- Malleable[T]
The list uses ORDINAL based indexing rather than ZERO based indexing (see the description of what this means in the Sequential interface definition).
This type is parameterized as follows:
- T is any type of item.
func Concatenate ¶
This function returns a new list containing all of the items that are in the specified lists in the order that they appear in each list.
func NewListWithComparer ¶
This constructor creates a new empty list that uses the specified compare function.
func (*List[T]) AddItem ¶
func (l *List[T]) AddItem(item T)
This method appends the specified item to the end of this list.
func (*List[T]) AddItems ¶
func (l *List[T]) AddItems(items []T)
This method appends the specified items to the end of this list.
func (*List[T]) ContainsAll ¶
This method determines whether or not this list contains ALL of the specified items.
func (*List[T]) ContainsAny ¶
This method determines whether or not this list contains ANY of the specified items.
func (*List[T]) ContainsItem ¶
This method determines whether or not this list contains the specified item.
func (*List[T]) GetAll ¶
func (l *List[T]) GetAll() []T
This method returns all the items in this list. The items retrieved are in the same order as they are in the list.
func (*List[T]) GetIndex ¶
This method returns the index of the FIRST occurence of the specified item in this list, or zero if this list does not contain the item.
func (*List[T]) GetItem ¶
This method retrieves from this list the item that is associated with the specified index.
func (*List[T]) GetItems ¶
This method retrieves from this list all items from the first index through the last index (inclusive).
func (*List[T]) InsertItem ¶
This method inserts the specified item into this list in the specified slot between existing items.
func (*List[T]) InsertItems ¶
This method inserts the specified items into this list in the specified slot between existing items.
func (*List[T]) RemoveAll ¶
func (l *List[T]) RemoveAll()
This method removes all items from this list.
func (*List[T]) RemoveItem ¶
This method removes the item at the specified index from this list. The removed item is returned.
func (*List[T]) RemoveItems ¶
This method removes the items in the specified index range from this list. The removed items are returned.
func (*List[T]) ReverseItems ¶
func (l *List[T]) ReverseItems()
This method reverses the order of all items in this list.
func (*List[T]) SetItem ¶
This method sets the item in this list that is associated with the specified index to be the specified item. It returns the old value of that item.
func (*List[T]) SetItems ¶
This method sets the items in this list starting with the specified index to the specified items. It returns the old values of those items.
func (*List[T]) ShuffleItems ¶
func (l *List[T]) ShuffleItems()
This method pseudo-randomly shuffles the items in this list.
func (*List[T]) SortItems ¶
func (l *List[T]) SortItems()
This method sorts the items in this list using the canonical rank function.
func (*List[T]) SortItemsWithRanker ¶
This method sorts the items in this list using the specified rank function.
type Malleable ¶
type Malleable[T any] interface { SetItem(index int, item T) T SetItems(index int, items []T) []T InsertItem(slot int, item T) InsertItems(slot int, items []T) RemoveItem(index int) T RemoveItems(first int, last int) []T RemoveAll() ShuffleItems() SortItems() SortItemsWithRanker(rank Rank) ReverseItems() }
This interface defines the methods supported by all collections whose items may be modified, inserted, removed, or reordered.
type Queue ¶
type Queue[T any] struct { // contains filtered or unexported fields }
This type defines the structure and methods associated with a queue of items. A queue implements first-in-first-out semantics. It is generally used by multiple goroutines at the same time and therefore enforces synchronized access.
A queue directly implements the following interfaces using a channel and a list:
- Sequential[T]
- Expandable[T]
- FIFO[T]
If the go chan type ever supports snapshots of its state, the underlying list can be removed and the channel modified to pass the items instead of the availability. Currently, the underlying list is only required by the GetAll() method.
This type is parameterized as follows:
- T is any type of item.
func Fork ¶
This function connects the output of the specified input queue with a number of new output queues specified by the size parameter and returns an array of the new output queues. Each item added to the input queue will be added automatically to ALL of the output queues. This pattern is useful when a set of DIFFERENT operations needs to occur for every item and each operation can be done in parallel.
func Join ¶
This function connects the outputs of the specified array of input queues with a new output queue returns the new output queue. Each item removed from each input queue will automatically be added to the output queue. This pattern is useful when the results of the processing with a Split() function need to be consolicated into a single queue.
func NewQueue ¶
This constructor creates a new empty queue with the default capacity. The default capacity is 16 items.
func NewQueueWithCapacity ¶
This constructor creates a new empty queue with the specified capacity.
func Split ¶
This function connects the output of the specified input queue with the number of output queues specified by the size parameter and returns an array of the new output queues. Each item added to the input queue will be added automatically to ONE of the output queues. This pattern is useful when a SINGLE operation needs to occur for each item and the operation can be done on the items in parallel. The results can then be consolidated later on using the Join() function.
func (*Queue[T]) AddItem ¶
func (q *Queue[T]) AddItem(item T)
This method adds the specified item to the end of this queue.
func (*Queue[T]) AddItems ¶
func (q *Queue[T]) AddItems(items []T)
This method adds the specified items to the top of this queue.
func (*Queue[T]) CloseQueue ¶
func (q *Queue[T]) CloseQueue()
This method closes the queue so no more items can be placed on it.
func (*Queue[T]) GetAll ¶
func (q *Queue[T]) GetAll() []T
This method returns all the items in this queue. The items retrieved are in the same order as they are in the queue.
func (*Queue[T]) GetCapacity ¶
This method retrieves the capacity of this queue.
func (*Queue[T]) RemoveHead ¶
This method removes from this queue the item that is at the head of it. It returns the removed value and a "comma ok" value as the result.
type Rank ¶
This type defines the function signature for any function that can determine the relative ordering of two specified values. The result must be one of the following:
- -1: The first value is less than the second value.
- 0: The first value is equal to the second value.
- 1: The first value is more than the second value.
type Ratcheted ¶
type Ratcheted[T any] interface { GetSlot() int ToSlot(slot int) ToStart() ToEnd() HasPrevious() bool GetPrevious() T HasNext() bool GetNext() T }
This interface defines the methods supported by all ratcheted agents that are capable of moving forward and backward over the items in a sequence. It is used to implement the GoF Iterator Pattern.
The ratcheted agent locks into the slots that reside between each item in the sequence:
[item 1] . [item 2] . [item 3] ... [item N] ^ ^ ^ ^ slot 0 slot 1 slot 2 slot N
The ratcheted agent moves from slot to slot and has access to the items (if they exist) on each side of the slot.
type RecursiveState ¶
type RecursiveState struct {
// contains filtered or unexported fields
}
This type defines the structure and methods for the state of a recursive agent.
func (*RecursiveState) CurrentDepth ¶
func (s *RecursiveState) CurrentDepth() int
This method returns the current depth level of recursion.
func (*RecursiveState) DecrementDepth ¶
func (s *RecursiveState) DecrementDepth() int
This method decreases the depth level of recursion by one and returns the new depth level.
func (*RecursiveState) IncrementDepth ¶
func (s *RecursiveState) IncrementDepth() int
This method increases the depth level of recursion by one and returns the new depth level.
type Searchable ¶
type Searchable[T any] interface { ContainsItem(item T) bool ContainsAny(items []T) bool ContainsAll(items []T) bool }
This interface defines the methods supported by all searchable collections of items.
type Sequential ¶
This interface defines the methods supported by all sequential collections of items.
type Set ¶
type Set[T any] struct { // Note: The delegated methods don't see the real collection type. Sequential[T] Indexed[T] // contains filtered or unexported fields }
This type defines the structure and methods associated with a set of items. It delegates the implemention of the following interfaces to List[T]:
- Sequential[T]
- Indexed[T]
And it directly implements the following interfaces using the same list:
- Searchable[T]
- Expandable[T]
- Contractable[T]
The set uses ORDINAL based indexing rather than ZERO based indexing (see the description of what this means in the Sequential interface definition).
This type is parameterized as follows:
- T is any type of item.
func Combine ¶
This function returns a new set containing all of the items that are in EITHER of the two specified sets or in BOTH sets.
func Intersect ¶
This function returns a new set containing all of the items that are in BOTH of the two specified sets.
func NewSet ¶
This constructor creates a new empty set that uses the canonical order function to determine the order of the items in the set.
func NewSetWithRanker ¶
This constructor creates a new empty set that uses the specified order function to determine the order of the items in the set.
func Subtract ¶
This function returns a new set containing all of the items that are in the first specified set but not in the second specified set.
func (*Set[T]) AddItem ¶
func (s *Set[T]) AddItem(item T)
This method adds the specified item to this set if it is not already a member of the set.
func (*Set[T]) AddItems ¶
func (s *Set[T]) AddItems(items []T)
This method adds the specified items to this set if they are not already members of the set.
func (*Set[T]) ContainsAll ¶
This method determines whether or not this set contains ALL of the specified items.
func (*Set[T]) ContainsAny ¶
This method determines whether or not this set contains ANY of the specified items.
func (*Set[T]) ContainsItem ¶
This method determines whether or not this set contains the specified item.
func (*Set[T]) RemoveAll ¶
func (s *Set[T]) RemoveAll()
This method removes all items from this set.
func (*Set[T]) RemoveItem ¶
func (s *Set[T]) RemoveItem(item T)
This method removes the specified item from this set. It returns true if the item was in the set and false otherwise.
func (*Set[T]) RemoveItems ¶
func (s *Set[T]) RemoveItems(items []T)
This method removes the specified items from this set. It returns the number of items that were removed.
type Stack ¶
type Stack[T any] struct { // Note: The delegated methods don't see the real collection type. Sequential[T] // contains filtered or unexported fields }
This type defines the structure and methods associated with a stack of items. A stack implements last-in-first-out semantics. It delegates the implemention of the following interfaces to a List[T]:
- Sequential[T]
And it directly implements the following interfaces using the same list:
- Expandable[T]
- LIFO[T]
This type is parameterized as follows:
- T is any type of item.
func NewStack ¶
This constructor creates a new empty stack with the default capacity. The default capacity is 16 items.
func NewStackWithCapacity ¶
This constructor creates a new empty stack with the specified capacity.
func (*Stack[T]) AddItem ¶
func (s *Stack[T]) AddItem(item T)
This method adds the specified item to the top of this stack.
func (*Stack[T]) AddItems ¶
func (s *Stack[T]) AddItems(items []T)
This method adds the specified items to the top of this stack.
func (*Stack[T]) GetCapacity ¶
This method retrieves the capacity of this stack.
func (*Stack[T]) GetTop ¶
func (s *Stack[T]) GetTop() T
This method retrieves from this stack the item that is on top of it.