Documentation ¶
Overview ¶
This collections package defines a set of simple, pragmatic interfaces for collections of sequential values. It also provides efficient and compact implementations of the following collection types based on those interfaces:
- array (native Go array)
- catalog (a sortable map)
- list (a sortable list)
- map (native Go map)
- queue (a blocking FIFO)
- set (an ordered set)
- stack (LIFO)
Additional implementations of these collection types can be defined and used seemlessly since the interface definitions only depend on other interfaces and native types; and the type implementations only depend on interfaces, not on each other. For a full description of this package see the wiki documentation at the github repository maintaining this package:
https://github.com/craterdog/go-collection-framework/wiki
Index ¶
- Constants
- func ArrayFromSequence[V Value](sequence Sequential[V]) []V
- func CompareValues(first Value, second Value) bool
- func FormatAssociation(association Value) string
- func FormatCollection(collection Collection) string
- func FormatDocument(collection Collection) []byte
- func FormatGrammar() string
- func MapFromSequence[K comparable, V Value](sequence Sequential[Binding[K, V]]) map[K]V
- func RankValues(first Value, second Value) int
- func ReverseArray[V Value](array []V)
- func Scanner(source []byte, tokens chan Token) *scanner
- func ShuffleArray[V Value](array []V)
- func SortArray[V Value](array []V, rank RankingFunction)
- type Accessible
- type Array
- func (v Array[V]) AsArray() []V
- func (v Array[V]) GetSize() int
- func (v Array[V]) GetValue(index int) V
- func (v Array[V]) GetValues(first int, last int) Sequential[V]
- func (v Array[V]) GoIndex(index int) int
- func (v Array[V]) IsEmpty() bool
- func (v Array[V]) SetValue(index int, value V)
- func (v Array[V]) SetValues(index int, values Sequential[V])
- func (v Array[V]) String() string
- type ArrayLike
- type AssociationLike
- type Associative
- type Binding
- type CatalogLike
- func Catalog[K Key, V Value]() CatalogLike[K, V]
- func CatalogFromArray[K Key, V Value](array []Binding[K, V]) CatalogLike[K, V]
- func CatalogFromSequence[K Key, V Value](sequence Sequential[Binding[K, V]]) CatalogLike[K, V]
- func Extract[K Key, V Value](catalog CatalogLike[K, V], keys Sequential[K]) CatalogLike[K, V]
- func Merge[K Key, V Value](first, second CatalogLike[K, V]) CatalogLike[K, V]
- type CollatorLike
- type Collection
- type ComparisonFunction
- type Discerning
- type FIFO
- type Flexible
- type IteratorLike
- type Key
- type LIFO
- type ListLike
- type Malleable
- type Map
- func (v Map[K, V]) AsArray() []Binding[K, V]
- func (v Map[K, V]) GetKeys() Sequential[K]
- func (v Map[K, V]) GetSize() int
- func (v Map[K, V]) GetValue(key K) V
- func (v Map[K, V]) GetValues(keys Sequential[K]) Sequential[V]
- func (v Map[K, V]) IsEmpty() bool
- func (v Map[K, V]) RemoveAll()
- func (v Map[K, V]) RemoveValue(key K) V
- func (v Map[K, V]) RemoveValues(keys Sequential[K]) Sequential[V]
- func (v Map[K, V]) SetValue(key K, value V)
- func (v Map[K, V]) String() string
- type MapLike
- type Primitive
- type QueueLike
- type RankingFunction
- type Ratcheted
- type Searchable
- type Sequential
- type SetLike
- func And[V Value](first, second SetLike[V]) SetLike[V]
- func Not[V Value](set SetLike[V]) SetLike[V]
- func Or[V Value](first, second SetLike[V]) SetLike[V]
- func Sans[V Value](first, second SetLike[V]) SetLike[V]
- func Set[V Value]() SetLike[V]
- func SetFromArray[V Value](array []V) SetLike[V]
- func SetFromSequence[V Value](sequence Sequential[V]) SetLike[V]
- func SetWithRanker[V Value](rank RankingFunction) SetLike[V]
- func Xor[V Value](first, second SetLike[V]) SetLike[V]
- type Sort
- type Sortable
- type SorterLike
- type StackLike
- type Systematic
- type Token
- type TokenType
- type Updatable
- type Value
Constants ¶
const ( EOF = "\n" // Must be last byte in a file. EOL = "\n" )
These constants define the POSIX standard representations.
Variables ¶
This section is empty.
Functions ¶
func ArrayFromSequence ¶ added in v2.2.0
func ArrayFromSequence[V Value](sequence Sequential[V]) []V
This constructor creates a new array from the specified sequence of values.
func CompareValues ¶
This function determines whether or not the specified values are equal using their natural comparison criteria.
func FormatAssociation ¶ added in v2.2.1
This function returns a string containing the canonical format for the specified collection.
func FormatCollection ¶ added in v2.2.1
func FormatCollection(collection Collection) string
This function returns a string containing the canonical format for the specified collection.
func FormatDocument ¶ added in v2.2.0
func FormatDocument(collection Collection) []byte
This function returns the bytes containing the canonical format for the specified collection including the POSIX standard EOF marker.
func FormatGrammar ¶ added in v2.2.0
func FormatGrammar() string
func MapFromSequence ¶ added in v2.2.0
func MapFromSequence[K comparable, V Value](sequence Sequential[Binding[K, V]]) map[K]V
This constructor creates a new catalog from the specified sequence of associations.
func RankValues ¶
This function ranks the specified values based on their natural ordering.
func ReverseArray ¶
func ReverseArray[V Value](array []V)
This function reverses the order of the values in the specified array.
func Scanner ¶ added in v2.2.0
This constructor creates a new scanner initialized with the specified array of bytes. The scanner will scan in tokens matching Go primitive types.
func ShuffleArray ¶
func ShuffleArray[V Value](array []V)
This function randomly shuffles the values in the specified array.
func SortArray ¶
func SortArray[V Value](array []V, rank RankingFunction)
This function sorts the values in the specified array using the specified ranking function.
Types ¶
type Accessible ¶
type Accessible[V Value] interface { GetValue(index int) V GetValues(first int, last int) Sequential[V] }
This interface defines the methods supported by all sequences whose values can be accessed using indices. The indices of an accessible sequence are ORDINAL rather than ZERO based (which is "SO last century"). This allows for positive indices starting at the beginning of the sequence, and negative indices starting at the end of the sequence as follows:
1 2 3 N [value 1] . [value 2] . [value 3] ... [value N] -N -(N-1) -(N-2) -1
Notice that because the indices are ordinal based, the positive and negative indices are symmetrical.
type Array ¶
type Array[V Value] []V
This type defines the structure and methods associated with a native array of values. Each value is associated with an implicit positive integer index. The array 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:
- V is any type of value.
func (Array[V]) AsArray ¶
func (v Array[V]) AsArray() []V
This method returns all the values in this array. The values retrieved are in the same order as they are in the array.
func (Array[V]) GetValue ¶
This method retrieves from this array the value that is associated with the specified index.
func (Array[V]) GetValues ¶
func (v Array[V]) GetValues(first int, last int) Sequential[V]
This method retrieves from this array all values from the first index through the last index (inclusive).
func (Array[V]) GoIndex ¶
This method normalizes an index to match the Go (zero based) indexing. The following transformation is performed:
[-length..-1] and [1..length] => [0..length)
Notice that the specified index cannot be zero since zero is not an ORDINAL.
func (Array[V]) SetValue ¶
This method sets the value in this array that is associated with the specified index to be the specified value.
func (Array[V]) SetValues ¶
func (v Array[V]) SetValues(index int, values Sequential[V])
This method sets the values in this array starting with the specified index to the specified values.
type ArrayLike ¶
type ArrayLike[V Value] interface { Sequential[V] Accessible[V] Updatable[V] }
This interface consolidates all the interfaces supported by native array-like sequences.
type AssociationLike ¶
This interface defines the methods supported by all association-like types. An association binds a key with a value.
func Association ¶
func Association[K Key, V Value](key K, value V) AssociationLike[K, V]
This constructor creates a new association with the specified key and value.
type Associative ¶
type Associative[K Key, V Value] interface { GetKeys() Sequential[K] GetValues(keys Sequential[K]) Sequential[V] GetValue(key K) V SetValue(key K, value V) RemoveValue(key K) V RemoveValues(keys Sequential[K]) Sequential[V] RemoveAll() }
This interface defines the methods supported by all associative sequences whose values consist of key-value pair associations.
type Binding ¶
This interface defines the methods supported by all binding associations. It binds a readonly key with a setable value.
type CatalogLike ¶
type CatalogLike[K Key, V Value] interface { Sequential[Binding[K, V]] Associative[K, V] Sortable[Binding[K, V]] }
This interface consolidates all the interfaces supported by catalog-like sequences.
func Catalog ¶
func Catalog[K Key, V Value]() CatalogLike[K, V]
This constructor creates a new empty catalog.
func CatalogFromArray ¶
func CatalogFromArray[K Key, V Value](array []Binding[K, V]) CatalogLike[K, V]
This constructor creates a new catalog from the specified array of associations.
func CatalogFromSequence ¶
func CatalogFromSequence[K Key, V Value](sequence Sequential[Binding[K, V]]) CatalogLike[K, V]
This constructor creates a new catalog from the specified sequence of associations.
func Extract ¶
func Extract[K Key, V Value](catalog CatalogLike[K, V], keys Sequential[K]) CatalogLike[K, V]
This function returns a new catalog containing only the associations that are in the specified catalog that have the specified keys. The associations in the resulting catalog will be in the same order as the specified keys.
func Merge ¶
func Merge[K Key, V Value](first, second CatalogLike[K, V]) CatalogLike[K, V]
This function returns a new catalog containing all of the associations that are in the specified catalogs in the order that they appear in each catalog.
type CollatorLike ¶
type CollatorLike interface { Discerning }
This interface defines the methods supported by all collator-like types.
func Collator ¶
func Collator() CollatorLike
This constructor creates a new instance of a collator that can be used to compare or rank any two values.
type Collection ¶ added in v2.2.0
type Collection any
func ParseCollection ¶ added in v2.2.0
func ParseCollection(source string) Collection
This function parses a source string rather than the bytes from a document file. It is useful when parsing strings within source code.
func ParseDocument ¶ added in v2.2.0
func ParseDocument(source []byte) Collection
This function parses the specified document source retrieved from a POSIX compliant file and returns the corresponding collection that was used to generate the document using the collection formatting capabilities. A POSIX compliant file must end with an EOF marker.
type ComparisonFunction ¶
This type defines the function signature for any function that can determine whether or not two specified values are equal to each other.
type Discerning ¶
type Discerning interface { CompareValues(first Value, second Value) bool RankValues(first Value, second Value) int }
This interface defines the methods supported by all discerning agent types that can compare and rank two values.
type FIFO ¶
type FIFO[V Value] interface { GetCapacity() int AddValue(value V) RemoveHead() (head V, ok bool) CloseQueue() }
This interface defines the methods supported by all sequences whose values are accessed using first-in-first-out (FIFO) semantics.
func Join ¶
This function connects the outputs of the specified sequence of input queues with a new output queue returns the new output queue. Each value 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.
type Flexible ¶
type Flexible[V Value] interface { AddValue(value V) AddValues(values Sequential[V]) RemoveValue(value V) RemoveValues(values Sequential[V]) RemoveAll() }
This interface defines the methods supported by all sequences of values that allow values to be added and removed.
type IteratorLike ¶
This interface defines the methods supported by all iterator-like types.
func Iterator ¶
func Iterator[V Value](sequence Sequential[V]) IteratorLike[V]
This constructor creates a new instance of an iterator that can be used to traverse the values in the specified sequence.
type LIFO ¶
type LIFO[V Value] interface { GetCapacity() int AddValue(value V) GetTop() V RemoveTop() V RemoveAll() }
This interface defines the methods supported by all sequences whose values are accessed using last-in-first-out (LIFO) semantics.
type ListLike ¶
type ListLike[V Value] interface { Sequential[V] Accessible[V] Updatable[V] Searchable[V] Malleable[V] Sortable[V] }
This interface consolidates all the interfaces supported by list-like sequences.
func Concatenate ¶
This function returns the concatenation of the two specified lists.
func ListFromArray ¶
This constructor creates a new list from the specified array. The list uses the natural compare function.
func ListFromSequence ¶
func ListFromSequence[V Value](sequence Sequential[V]) ListLike[V]
This constructor creates a new list from the specified sequence. The list uses the natural compare function.
func ListWithComparer ¶
func ListWithComparer[V Value](compare ComparisonFunction) ListLike[V]
This constructor creates a new empty list that uses the specified compare function.
type Malleable ¶
type Malleable[V Value] interface { AddValue(value V) AddValues(values Sequential[V]) InsertValue(slot int, value V) InsertValues(slot int, values Sequential[V]) RemoveValue(index int) V RemoveValues(first int, last int) Sequential[V] RemoveAll() }
This interface defines the methods supported by all sequences whose values may be modified, inserted, removed, or reordered.
type Map ¶
type Map[K comparable, V Value] map[K]V
This type defines the structure and methods associated with a native map of key-value pair associations. This type is parameterized as follows:
- K is a primitive type of key.
- V is any type of entity.
func (Map[K, V]) AsArray ¶
This method returns all the associations that are in this map. The associations retrieved are in the same order as they are in the map.
func (Map[K, V]) GetKeys ¶
func (v Map[K, V]) GetKeys() Sequential[K]
This method returns the keys for this map.
func (Map[K, V]) GetValue ¶
func (v Map[K, V]) GetValue(key K) V
This method returns the value that is associated with the specified key in this map.
func (Map[K, V]) GetValues ¶
func (v Map[K, V]) GetValues(keys Sequential[K]) Sequential[V]
This method returns the values associated with the specified keys for this map. The values are returned in the same order as the keys in the map.
func (Map[K, V]) RemoveAll ¶
func (v Map[K, V]) RemoveAll()
This method removes all associations from this map.
func (Map[K, V]) RemoveValue ¶
func (v Map[K, V]) RemoveValue(key K) V
This method removes the association associated with the specified key from the map and returns it.
func (Map[K, V]) RemoveValues ¶
func (v Map[K, V]) RemoveValues(keys Sequential[K]) Sequential[V]
This method removes the associations associated with the specified keys from the map and returns the removed values.
type MapLike ¶
type MapLike[K Key, V Value] interface { Sequential[Binding[K, V]] Associative[K, V] }
This interface consolidates all the interfaces supported by native map-like sequences. Note, that the order of the key-value pairs on a native map is random, even for two maps containing the same keys.
type QueueLike ¶
type QueueLike[V Value] interface { Sequential[V] FIFO[V] }
This interface consolidates all of the interfaces supported by queue-like sequences.
func Queue ¶
This constructor creates a new empty queue with the default capacity. The default capacity is 16 values.
func QueueFromSequence ¶ added in v2.2.0
func QueueFromSequence[V Value](sequence Sequential[V]) QueueLike[V]
This constructor creates a new queue from the specified sequence. The queue uses the default capacity
func QueueWithCapacity ¶
This constructor creates a new empty queue with the specified capacity.
type RankingFunction ¶
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[V Value] interface { GetSlot() int ToSlot(slot int) ToStart() ToEnd() HasPrevious() bool GetPrevious() V HasNext() bool GetNext() V }
This interface defines the methods supported by all ratcheted agents that are capable of moving forward and backward over the values in a sequence. It is used to implement the GoF Iterator Pattern:
A ratcheted agent locks into the slots that reside between each value in the sequence:
[value 1] . [value 2] . [value 3] ... [value N] ^ ^ ^ ^ slot 0 slot 1 slot 2 slot N
It moves from slot to slot and has access to the values (if they exist) on each side of the slot.
type Searchable ¶
type Searchable[V Value] interface { GetIndex(value V) int ContainsValue(value V) bool ContainsAny(values Sequential[V]) bool ContainsAll(values Sequential[V]) bool }
This interface defines the methods supported by all searchable sequences of values.
type Sequential ¶
This interface defines the methods supported by all sequences of values.
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 a sequence of the new output queues. Each value 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 value and each operation can be done in parallel.
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 a sequence of the new output queues. Each value 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 value and the operation can be done on the values in parallel. The results can then be consolidated later on using the Join() function.
type SetLike ¶
type SetLike[V Value] interface { Sequential[V] Accessible[V] Searchable[V] Flexible[V] }
This interface consolidates all the interfaces supported by set-like sequences.
func SetFromArray ¶
This constructor creates a new set from the specified array. The set uses the natural rank function.
func SetFromSequence ¶
func SetFromSequence[V Value](sequence Sequential[V]) SetLike[V]
This constructor creates a new set from the specified sequence. The set uses the natural rank function.
func SetWithRanker ¶
func SetWithRanker[V Value](rank RankingFunction) SetLike[V]
This constructor creates a new empty set that uses the specified rank function.
type Sort ¶
type Sort[V Value] func(array []V, rank RankingFunction)
This type defines the function signature for any function that can sort an array of values using a ranking function.
type Sortable ¶
type Sortable[V Value] interface { SortValues() SortValuesWithRanker(rank RankingFunction) ReverseValues() ShuffleValues() }
This interface defines the methods supported by all sequences whose values may be sorted using various sorting algorithms.
type SorterLike ¶
type SorterLike[V Value] interface { Systematic[V] }
This interface defines the methods supported by all sorter-like types.
func Sorter ¶
func Sorter[V Value](rank RankingFunction) SorterLike[V]
This constructor creates a new instance of a sorter that can be used to sort an array using a specific ranking function.
type StackLike ¶
type StackLike[V Value] interface { Sequential[V] LIFO[V] }
This interface consolidates all the interfaces supported by stack-like sequences.
func Stack ¶
This constructor creates a new empty stack with the default capacity. The default capacity is 16 values.
func StackFromSequence ¶ added in v2.2.0
func StackFromSequence[V Value](sequence Sequential[V]) StackLike[V]
This constructor creates a new stack from the specified sequence. The stack uses the default capacity
func StackWithCapacity ¶
This constructor creates a new empty stack with the specified capacity.
type Systematic ¶
type Systematic[V Value] interface { ReverseArray(array []V) ShuffleArray(array []V) SortArray(array []V) }
This interface defines the methods supported by all systematic agents that can shuffle or sort an array of values using a ranking function.
type Token ¶ added in v2.2.0
type Token struct { Type TokenType Value string Line int // The line number of the token in the input string. Position int // The position in the line of the first rune of the token. }
This type defines the structure and methods for each token returned by the scanner.
type TokenType ¶ added in v2.2.0
type TokenType int
This integer type is used as a type identifier for each token.