collections

package module
v2.2.1 Latest Latest
Warning

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

 Go to latest Published: Dec 5, 2023 License: MIT Imports: 11 Imported by: 15

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

View Source 
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 

func CompareValues(first Value, second Value) bool

This function determines whether or not the specified values are equal using their natural comparison criteria.

func FormatAssociation added in v2.2.1 

func FormatAssociation(association Value) string

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 

func RankValues(first Value, second Value) int

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 

func Scanner(source []byte, tokens chan Token) *scanner

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]) GetSize 

func (v Array[V]) GetSize() int

This method returns the number of values contained in this array.

func (Array[V]) GetValue 

func (v Array[V]) GetValue(index int) V

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 

func (v Array[V]) GoIndex(index int) int

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]) IsEmpty 

func (v Array[V]) IsEmpty() bool

This method determines whether or not this array is empty.

func (Array[V]) SetValue 

func (v Array[V]) SetValue(index int, value V)

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.

func (Array[V]) String 

func (v Array[V]) String() string

This method is used by Go to generate a string from an array.

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 

type AssociationLike[K Key, V Value] interface {
	Binding[K, V]
}

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 

type Binding[K Key, V Value] interface {
	GetKey() K
	GetValue() V
	SetValue(value V)
}

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 

type ComparisonFunction func(first Value, second Value) 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 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 

func Join[V Value](wg *syn.WaitGroup, inputs Sequential[FIFO[V]]) FIFO[V]

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 

type IteratorLike[V Value] interface {
	Ratcheted[V]
}

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 Key 

type Key any

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 

func Concatenate[V Value](first, second ListLike[V]) ListLike[V]

This function returns the concatenation of the two specified lists.

func List 

func List[V Value]() ListLike[V]

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

func ListFromArray 

func ListFromArray[V Value](array []V) ListLike[V]

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 

func (v Map[K, V]) AsArray() []Binding[K, V]

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]) GetSize 

func (v Map[K, V]) GetSize() int

This method returns the number of values contained in 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]) IsEmpty 

func (v Map[K, V]) IsEmpty() bool

This method determines whether or not this map is empty.

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.

func (Map[K, V]) SetValue 

func (v Map[K, V]) SetValue(key K, value V)

This method sets the value associated with the specified key to the specified value.

func (Map[K, V]) String 

func (v Map[K, V]) String() string

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 Primitive added in v2.2.0 

type Primitive any

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 

func Queue[V Value]() QueueLike[V]

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 

func QueueWithCapacity[V Value](capacity int) QueueLike[V]

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

type RankingFunction 

type RankingFunction func(first Value, second Value) 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[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 

type Sequential[V Value] interface {
	IsEmpty() bool
	GetSize() int
	AsArray() []V
}

This interface defines the methods supported by all sequences of values.

func Fork 

func Fork[V Value](wg *syn.WaitGroup, input FIFO[V], size int) Sequential[FIFO[V]]

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 

func Split[V Value](wg *syn.WaitGroup, input FIFO[V], size int) Sequential[FIFO[V]]

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 And 

func And[V Value](first, second SetLike[V]) SetLike[V]

This function returns the logical conjunction of the specified sets.

func Not 

func Not[V Value](set SetLike[V]) SetLike[V]

This function returns the logical inverse of the specified set.

func Or 

func Or[V Value](first, second SetLike[V]) SetLike[V]

This function returns the logical disjunction of the specified sets.

func Sans 

func Sans[V Value](first, second SetLike[V]) SetLike[V]

This function returns the logical material non-implication of the specified sets.

func Set 

func Set[V Value]() SetLike[V]

This constructor creates a new empty set that uses the natural rank function.

func SetFromArray 

func SetFromArray[V Value](array []V) SetLike[V]

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.

func Xor 

func Xor[V Value](first, second SetLike[V]) SetLike[V]

This function returns the logical exclusive disjunction of the specified sets.

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 

func Stack[V Value]() StackLike[V]

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 

func StackWithCapacity[V Value](capacity int) StackLike[V]

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.

func (Token) String added in v2.2.0 

func (v Token) String() string

This method returns the canonical string version of this token.

type TokenType added in v2.2.0 

type TokenType int

This integer type is used as a type identifier for each token. 

const (
	TokenError TokenType = iota
	TokenBoolean
	TokenComplex
	TokenContext
	TokenDelimiter
	TokenEOF
	TokenEOL
	TokenFloat
	TokenInteger
	TokenNil
	TokenRune
	TokenString
	TokenUnsigned
)

This enumeration defines all possible token types including the error token.

func (TokenType) String added in v2.2.0 

func (v TokenType) String() string

This method returns the string representation for each token type.

type Updatable 

type Updatable[V Value] interface {
	SetValue(index int, value V)
	SetValues(index int, values Sequential[V])
}

This interface defines the methods supported by all updatable sequences of values.

type Value 

type Value any

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.