collections

package module
v0.0.0-...-7434fb3 Latest Latest
Warning

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

Go to latest
Published: Aug 12, 2022 License: MIT Imports: 11 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func CompareValues

func CompareValues(first any, second any) bool

This function determines whether or not the specified values are equal using their canonical comparison rules.

func ParseString

func ParseString(str string) any

func RankReflective

func RankReflective(first any, second any) int

This function returns the ranking order of the specified reflective values using reflection.

func RankValues

func RankValues(first any, second any) int

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

type Attribute[K any, V any] struct {
	// contains filtered or unexported fields
}

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

func NewAttribute[K any, V any](key K, value V) *Attribute[K, V]

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.

func (*Attribute[K, V]) GetValue

func (a *Attribute[K, V]) GetValue() V

This method returns the value for this attribute.

func (*Attribute[K, V]) SetValue

func (a *Attribute[K, V]) SetValue(value V) V

This method sets the value of this attribute to a new value and returns the old value.

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

func Extract[K any, V any](catalog *Catalog[K, V], keys []K) *Catalog[K, V]

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

func Merge[K any, V any](first *Catalog[K, V], second *Catalog[K, V]) *Catalog[K, V]

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

func NewCatalog[K any, V any]() *Catalog[K, V]

This constructor creates a new empty catalog.

func (*Catalog[K, V]) AddItem

func (c *Catalog[K, V]) AddItem(attribute Keyed[K, V])

This method appends the specified attribute to the end of this catalog.

func (*Catalog[K, V]) AddItems

func (c *Catalog[K, V]) AddItems(attributes []Keyed[K, V])

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

func (c *Catalog[K, V]) SortAttributesWithRanker(rank Rank)

This method sorts this catalog using the specified rank function to compare the keys.

type Compare

type Compare func(first any, second any) bool

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

type FIFO[T any] interface {
	GetCapacity() int
	IsActive() bool
	RemoveHead() T
	CloseQueue()
}

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

func NewFormatterWithIndentation(indentation int) *Formatter

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

func (s *Formatter) FormatValue(value any) string

This method returns the canonical string for the specified value.

func (*Formatter) GetIndentation

func (s *Formatter) GetIndentation() int

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

func (i *Iterator[T]) GetSlot() int

This method returns the current slot between items that this iterator is currently locked into.

func (*Iterator[T]) HasNext

func (i *Iterator[T]) HasNext() bool

This method determines whether or not there is an item after the current slot.

func (*Iterator[T]) HasPrevious

func (i *Iterator[T]) HasPrevious() bool

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.

func (*Iterator[T]) ToSlot

func (i *Iterator[T]) ToSlot(slot int)

This method moves this iterator to the specified slot between items.

func (*Iterator[T]) ToStart

func (i *Iterator[T]) ToStart()

This method moves this iterator to the slot before the first item.

type Keyed

type Keyed[K any, V any] interface {
	GetKey() K
	GetValue() V
	SetValue(value V) V
}

This interface defines the methods supported by all keyed types. A keyed type associates a key with a value.

type LIFO

type LIFO[T any] interface {
	GetCapacity() int
	GetTop() T
	RemoveTop() T
	RemoveAll()
}

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

func Concatenate[T any](first *List[T], second *List[T]) *List[T]

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 NewList

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

This constructor creates a new empty list that uses the canonical compare function.

func NewListWithComparer

func NewListWithComparer[T any](compare Compare) *List[T]

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

func (l *List[T]) ContainsAll(items []T) bool

This method determines whether or not this list contains ALL of the specified items.

func (*List[T]) ContainsAny

func (l *List[T]) ContainsAny(items []T) bool

This method determines whether or not this list contains ANY of the specified items.

func (*List[T]) ContainsItem

func (l *List[T]) ContainsItem(item T) bool

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

func (l *List[T]) GetIndex(item T) int

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

func (l *List[T]) GetItem(index int) T

This method retrieves from this list the item that is associated with the specified index.

func (*List[T]) GetItems

func (l *List[T]) GetItems(first int, last int) []T

This method retrieves from this list all items from the first index through the last index (inclusive).

func (*List[T]) GetSize

func (l *List[T]) GetSize() int

This method returns the number of items contained in this list.

func (*List[T]) InsertItem

func (l *List[T]) InsertItem(slot int, item T)

This method inserts the specified item into this list in the specified slot between existing items.

func (*List[T]) InsertItems

func (l *List[T]) InsertItems(slot int, items []T)

This method inserts the specified items into this list in the specified slot between existing items.

func (*List[T]) IsEmpty

func (l *List[T]) IsEmpty() bool

This method determines whether or not this list is empty.

func (*List[T]) RemoveAll

func (l *List[T]) RemoveAll()

This method removes all items from this list.

func (*List[T]) RemoveItem

func (l *List[T]) RemoveItem(index int) T

This method removes the item at the specified index from this list. The removed item is returned.

func (*List[T]) RemoveItems

func (l *List[T]) RemoveItems(first int, last int) []T

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

func (l *List[T]) SetItem(index int, item T) T

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

func (l *List[T]) SetItems(index int, items []T) []T

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

func (l *List[T]) SortItemsWithRanker(rank Rank)

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

func Fork[T any](wg *sync.WaitGroup, input *Queue[T], size int) []*Queue[T]

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

func Join[T any](wg *sync.WaitGroup, inputs []*Queue[T]) *Queue[T]

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

func NewQueue[T any]() *Queue[T]

This constructor creates a new empty queue with the default capacity. The default capacity is 16 items.

func NewQueueWithCapacity

func NewQueueWithCapacity[T any](capacity int) *Queue[T]

This constructor creates a new empty queue with the specified capacity.

func Split

func Split[T any](wg *sync.WaitGroup, input *Queue[T], size int) []*Queue[T]

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

func (q *Queue[T]) GetCapacity() int

This method retrieves the capacity of this queue.

func (*Queue[T]) GetSize

func (q *Queue[T]) GetSize() int

This method returns the number of items contained in this queue.

func (*Queue[T]) IsEmpty

func (q *Queue[T]) IsEmpty() bool

This method determines whether or not this queue is empty.

func (*Queue[T]) RemoveHead

func (q *Queue[T]) RemoveHead() (head T, ok bool)

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

type Rank func(first any, second any) int

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

type Sequential[T any] interface {
	IsEmpty() bool
	GetSize() int
	GetAll() []T
}

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

func Combine[T any](first *Set[T], second *Set[T]) *Set[T]

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

func Intersect[T any](first *Set[T], second *Set[T]) *Set[T]

This function returns a new set containing all of the items that are in BOTH of the two specified sets.

func NewSet

func NewSet[T any]() *Set[T]

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

func NewSetWithRanker[T any](rank Rank) *Set[T]

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

func Subtract[T any](first *Set[T], second *Set[T]) *Set[T]

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

func (s *Set[T]) ContainsAll(items []T) bool

This method determines whether or not this set contains ALL of the specified items.

func (*Set[T]) ContainsAny

func (s *Set[T]) ContainsAny(items []T) bool

This method determines whether or not this set contains ANY of the specified items.

func (*Set[T]) ContainsItem

func (s *Set[T]) ContainsItem(item T) bool

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

func NewStack[T any]() *Stack[T]

This constructor creates a new empty stack with the default capacity. The default capacity is 16 items.

func NewStackWithCapacity

func NewStackWithCapacity[T any](capacity int) *Stack[T]

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

func (s *Stack[T]) GetCapacity() int

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.

func (*Stack[T]) RemoveAll

func (s *Stack[T]) RemoveAll()

This method removes all items from this stack.

func (*Stack[T]) RemoveTop

func (s *Stack[T]) RemoveTop() T

This method removes from this stack the item that is on top of it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL