collections

package
v0.15.0-rc2 Latest Latest
Warning

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

 Go to latest Published: Oct 23, 2022 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultSequenceStart uint64 = 1

DefaultSequenceStart is the initial starting number of the Sequence.

Variables

View Source 
var ErrNotFound = errors.New("collections: not found")

ErrNotFound is returned when an object is not found.

Functions

This section is empty.

Types

type Bound 

type Bound[K any] struct {
	// contains filtered or unexported fields
}

Bound defines key bounds for Start and Ends of iterator ranges.

func BoundExclusive 

func BoundExclusive[K any](key K) *Bound[K]

BoundExclusive creates a Bound of the provided key K which is exclusive. Meaning, if it is used as Ranger.RangeValues start, the provided key will be excluded if it exists in the Iterator range.

func BoundInclusive 

func BoundInclusive[K any](key K) *Bound[K]

BoundInclusive creates a Bound of the provided key K which is inclusive. Meaning, if it is used as Ranger.RangeValues start, the provided key will be included if it exists in the Iterator range.

type IndexedMap 

type IndexedMap[PK any, V any, I IndexersProvider[PK, V]] struct {
	Indexes I // struct that groups together Indexer instances, implements IndexersProvider
	// contains filtered or unexported fields
}

IndexedMap defines a map which is indexed using the IndexersProvider PK defines the primary key of the object V.

func NewIndexedMap 

func NewIndexedMap[PK any, V any, I IndexersProvider[PK, V]](
	storeKey sdk.StoreKey, namespace Namespace,
	primaryKeyEncoder KeyEncoder[PK],
	valueEncoder ValueEncoder[V],
	indexers I) IndexedMap[PK, V, I]

NewIndexedMap instantiates a new IndexedMap instance.

func (IndexedMap[PK, V, I]) Delete 

func (i IndexedMap[PK, V, I]) Delete(ctx sdk.Context, key PK) error

Delete fetches the object from the Map removes it from the Map then instructs every Indexer to remove the relationships between the object and the associated primary keys.

func (IndexedMap[PK, V, I]) Get 

func (i IndexedMap[PK, V, I]) Get(ctx sdk.Context, key PK) (V, error)

Get returns the object V given its primary key PK.

func (IndexedMap[PK, V, I]) GetOr 

func (i IndexedMap[PK, V, I]) GetOr(ctx sdk.Context, key PK, def V) V

GetOr returns the object V given its primary key PK, or if the operation fails returns the provided default.

func (IndexedMap[PK, V, I]) Insert 

func (i IndexedMap[PK, V, I]) Insert(ctx sdk.Context, key PK, v V)

Insert inserts the object v into the Map using the primary key, then iterates over every registered Indexer and instructs them to create the relationship between the primary key PK and the object v.

func (IndexedMap[PK, V, I]) Iterate 

func (i IndexedMap[PK, V, I]) Iterate(ctx sdk.Context, rng Range[PK]) Iterator[PK, V]

Iterate iterates over the underlying store containing the concrete objects. The range provided filters over the primary keys.

type Indexer 

type Indexer[PK any, V any] interface {
	// Insert is called when the IndexedMap is inserting
	// an object into its state, so the Indexer here
	// creates the relationship between primary key
	// and the fields of the object V.
	Insert(ctx sdk.Context, primaryKey PK, v V)
	// Delete is called when the IndexedMap is removing
	// the object V and hence the relationship between
	// V and its primary keys need to be removed too.
	Delete(ctx sdk.Context, primaryKey PK, v V)
}

Indexer defines an object which given an object V and a primary key PK, creates a relationship between one or multiple fields of the object V with the primary key PK.

type IndexerIterator 

type IndexerIterator[IK, PK any] KeySetIterator[Pair[IK, PK]]

IndexerIterator wraps a KeySetIterator to provide more useful functionalities around index key iteration.

func (IndexerIterator[IK, PK]) Close 

func (i IndexerIterator[IK, PK]) Close()

func (IndexerIterator[IK, PK]) FullKey 

func (i IndexerIterator[IK, PK]) FullKey() Pair[IK, PK]

FullKey returns the iterator current key composed of both indexing key and primary key.

func (IndexerIterator[IK, PK]) FullKeys 

func (i IndexerIterator[IK, PK]) FullKeys() []Pair[IK, PK]

FullKeys fully consumes the iterator and returns the set of joined indexing key and primary key found.

func (IndexerIterator[IK, PK]) Next 

func (i IndexerIterator[IK, PK]) Next()

func (IndexerIterator[IK, PK]) PrimaryKey 

func (i IndexerIterator[IK, PK]) PrimaryKey() PK

PrimaryKey returns the iterator current primary key

func (IndexerIterator[IK, PK]) PrimaryKeys 

func (i IndexerIterator[IK, PK]) PrimaryKeys() []PK

PrimaryKeys fully consumes the iterator and returns the set of primary keys found.

func (IndexerIterator[IK, PK]) Valid 

func (i IndexerIterator[IK, PK]) Valid() bool

type IndexersProvider 

type IndexersProvider[PK any, V any] interface {
	// IndexerList provides the list of Indexer contained
	// in the struct.
	IndexerList() []Indexer[PK, V]
}

IndexersProvider is implemented by structs containing a series of Indexer instances.

type Item 

type Item[V any] Map[uint64, V]

Item represents a state object which will always have one instance of itself saved in the namespace. Examples are:

  • config
  • parameters
  • a sequence

It builds on top of a Map with a constant key.

func NewItem 

func NewItem[V any](sk sdk.StoreKey, namespace Namespace, valueEncoder ValueEncoder[V]) Item[V]

NewItem instantiates a new Item instance.

func (Item[V]) Get 

func (i Item[V]) Get(ctx sdk.Context) (V, error)

Get gets the item V or returns an error.

func (Item[V]) GetOr 

func (i Item[V]) GetOr(ctx sdk.Context, def V) V

GetOr either returns the provided default if it's not present in state, or the value found in state.

func (Item[V]) Set 

func (i Item[V]) Set(ctx sdk.Context, v V)

Set sets the item value to v.

type Iterator 

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

Iterator defines a generic wrapper around an sdk.Iterator. This iterator provides automatic key and value encoding, it assumes all the keys and values contained within the sdk.Iterator range are the same.

func (Iterator[K, V]) Close 

func (i Iterator[K, V]) Close()

func (Iterator[K, V]) Key 

func (i Iterator[K, V]) Key() K

Key returns the current sdk.Iterator decoded key.

func (Iterator[K, V]) KeyValue 

func (i Iterator[K, V]) KeyValue() KeyValue[K, V]

KeyValue returns the current key and value decoded.

func (Iterator[K, V]) KeyValues 

func (i Iterator[K, V]) KeyValues() []KeyValue[K, V]

KeyValues fully consumes the iterator and returns the list of key and values within the iterator range.

func (Iterator[K, V]) Keys 

func (i Iterator[K, V]) Keys() []K

Keys fully consumes the iterator and returns all the decoded keys contained within the range.

func (Iterator[K, V]) Next 

func (i Iterator[K, V]) Next()

func (Iterator[K, V]) Valid 

func (i Iterator[K, V]) Valid() bool

func (Iterator[K, V]) Value 

func (i Iterator[K, V]) Value() V

Value returns the current iterator value bytes decoded.

func (Iterator[K, V]) Values 

func (i Iterator[K, V]) Values() []V

Values fully consumes the iterator and returns all the decoded values contained within the range.

type KeyEncoder 

type KeyEncoder[T any] interface {
	// Encode encodes the type T into bytes.
	Encode(key T) []byte
	// Decode decodes the given bytes back into T.
	// And it also must return the bytes of the buffer which were read.
	Decode(b []byte) (int, T)
	// Stringify returns a string representation of T.
	Stringify(key T) string
}

KeyEncoder defines a generic interface which is implemented by types that are capable of encoding and decoding collections keys. 

var (
	// StringKeyEncoder can be used to encode string keys.
	StringKeyEncoder KeyEncoder[string] = stringKey{}
	// AccAddressKeyEncoder can be used to encode sdk.AccAddress keys.
	AccAddressKeyEncoder KeyEncoder[sdk.AccAddress] = accAddressKey{}
	// TimeKeyEncoder can be used to encode time.Time keys.
	TimeKeyEncoder KeyEncoder[time.Time] = timeKey{}
	// Uint64KeyEncoder can be used to encode uint64 keys.
	Uint64KeyEncoder KeyEncoder[uint64] = uint64Key{}
	// ValAddressKeyEncoder can be used to encode sdk.ValAddress keys.
	ValAddressKeyEncoder KeyEncoder[sdk.ValAddress] = valAddressKeyEncoder{}
)

func PairKeyEncoder 

func PairKeyEncoder[K1, K2 any](kc1 KeyEncoder[K1], kc2 KeyEncoder[K2]) KeyEncoder[Pair[K1, K2]]

PairKeyEncoder creates a new KeyEncoder for Pair types, give the two key encoders for K1 and K2.

type KeySet 

type KeySet[K any] Map[K, setObject]

KeySet wraps the default Map, but is used only for keys.Key presence and ranging functionalities.

func NewKeySet 

func NewKeySet[K any](sk sdk.StoreKey, namespace Namespace, keyEncoder KeyEncoder[K]) KeySet[K]

NewKeySet instantiates a new KeySet.

func (KeySet[K]) Delete 

func (s KeySet[K]) Delete(ctx sdk.Context, k K)

Delete deletes the key from the set. Does not check if the key exists or not.

func (KeySet[K]) Has 

func (s KeySet[K]) Has(ctx sdk.Context, k K) bool

Has reports whether the key K is present or not in the set.

func (KeySet[K]) Insert 

func (s KeySet[K]) Insert(ctx sdk.Context, k K)

Insert inserts the key K in the set.

func (KeySet[K]) Iterate 

func (s KeySet[K]) Iterate(ctx sdk.Context, r Ranger[K]) KeySetIterator[K]

Iterate returns a KeySetIterator over the provided keys.Range of keys.

type KeySetIterator 

type KeySetIterator[K any] Iterator[K, setObject]

KeySetIterator wraps the default MapIterator, but is used only for keys.Key ranging.

func (KeySetIterator[K]) Close 

func (s KeySetIterator[K]) Close()

Close closes the KeySetIterator. No other operation is valid.

func (KeySetIterator[K]) Key 

func (s KeySetIterator[K]) Key() K

Key returns the current iterator key.

func (KeySetIterator[K]) Keys 

func (s KeySetIterator[K]) Keys() []K

Keys consumes the iterator fully and returns all the available keys. The KeySetIterator is closed after this operation.

func (KeySetIterator[K]) Next 

func (s KeySetIterator[K]) Next()

Next moves the iterator onto the next key.

func (KeySetIterator[K]) Valid 

func (s KeySetIterator[K]) Valid() bool

Valid checks if the iterator is still valid.

type KeyValue 

type KeyValue[K, V any] struct {
	Key   K
	Value V
}

type Map 

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

func NewMap 

func NewMap[K, V any](sk sdk.StoreKey, namespace Namespace, kc KeyEncoder[K], vc ValueEncoder[V]) Map[K, V]

func (Map[K, V]) Delete 

func (m Map[K, V]) Delete(ctx sdk.Context, k K) error

func (Map[K, V]) Get 

func (m Map[K, V]) Get(ctx sdk.Context, k K) (v V, err error)

func (Map[K, V]) GetOr 

func (m Map[K, V]) GetOr(ctx sdk.Context, key K, def V) (v V)

func (Map[K, V]) Insert 

func (m Map[K, V]) Insert(ctx sdk.Context, k K, v V)

func (Map[K, V]) Iterate 

func (m Map[K, V]) Iterate(ctx sdk.Context, rng Ranger[K]) Iterator[K, V]

type MultiIndex 

type MultiIndex[IK, PK, V any] struct {
	// contains filtered or unexported fields
}

MultiIndex defines an Indexer with no uniqueness constraints. Meaning that given two objects V1 and V2 both can be indexed with the same secondary key. Example: Person1 { ID: 0, City: Milan } Person2 { ID: 1, City: Milan } Both can be indexed with the secondary key "Milan". The key generated are, respectively: Pair[Milan, 0] Pair[Milan, 1] So if we want to get all the objects whose City is Milan we prefix over Pair[Milan, nil], and we get the respective primary keys: 0,1.

func NewMultiIndex 

func NewMultiIndex[IK, PK any, V any](
	sk sdk.StoreKey, namespace Namespace,
	indexKeyEncoder KeyEncoder[IK], primaryKeyEncoder KeyEncoder[PK],
	getIndexingKeyFunc func(v V) IK) MultiIndex[IK, PK, V]

NewMultiIndex instantiates a new MultiIndex instance. namespace is the unique storage namespace for the index. getIndexingKeyFunc is a function which given the object returns the key we use to index the object.

func (MultiIndex[IK, PK, V]) Delete 

func (i MultiIndex[IK, PK, V]) Delete(ctx sdk.Context, pk PK, v V)

Delete implements the Indexer interface.

func (MultiIndex[IK, PK, V]) ExactMatch 

func (i MultiIndex[IK, PK, V]) ExactMatch(ctx sdk.Context, ik IK) IndexerIterator[IK, PK]

ExactMatch returns an iterator of all the primary keys of objects which contain the provided indexing key ik.

func (MultiIndex[IK, PK, V]) Insert 

func (i MultiIndex[IK, PK, V]) Insert(ctx sdk.Context, pk PK, v V)

Insert implements the Indexer interface.

func (MultiIndex[IK, PK, V]) Iterate 

func (i MultiIndex[IK, PK, V]) Iterate(ctx sdk.Context, rng Ranger[Pair[IK, PK]]) IndexerIterator[IK, PK]

Iterate iterates over the provided range.

func (MultiIndex[IK, PK, V]) ReverseExactMatch 

func (i MultiIndex[IK, PK, V]) ReverseExactMatch(ctx sdk.Context, ik IK) IndexerIterator[IK, PK]

ReverseExactMatch works in the same way as ExactMatch, but the iteration happens in reverse.

type Namespace 

type Namespace uint8

Namespace defines a storage namespace which must be unique in a single module for all the different storage layer types: Map, Sequence, KeySet, Item, MultiIndex, IndexedMap

func (Namespace) Prefix 

func (n Namespace) Prefix() []byte

type Order 

type Order uint8

Order defines the key order. 

const (
	// OrderAscending instructs the Iterator to provide keys from the smallest to the greatest.
	OrderAscending Order = 0
	// OrderDescending instructs the Iterator to provide keys from the greatest to the smallest.
	OrderDescending Order = 1
)

type Pair 

type Pair[K1, K2 any] struct {
	// contains filtered or unexported fields
}

Pair defines a storage key composed of two keys of different or equal types.

func Join 

func Join[K1, K2 any](k1 K1, k2 K2) Pair[K1, K2]

Join returns a fully populated Pair given the two key parts.

func PairPrefix 

func PairPrefix[K1, K2 any](k1 K1) Pair[K1, K2]

PairPrefix returns a partially populated pair given the first part of the key.

func PairSuffix 

func PairSuffix[K1, K2 any](k2 K2) Pair[K1, K2]

PairSuffix returns a partially populated pair given the last part of the key.

func (Pair[K1, K2]) K1 

func (p Pair[K1, K2]) K1() (k1 K1)

func (Pair[K1, K2]) K2 

func (p Pair[K1, K2]) K2() (k2 K2)

type PairRange 

type PairRange[K1, K2 any] struct {
	// contains filtered or unexported fields
}

PairRange implements the Ranger interface to provide an easier way to range over Pair keys.

func (PairRange[K1, K2]) Descending 

func (p PairRange[K1, K2]) Descending() PairRange[K1, K2]

Descending makes the range run in reverse (bigger->smaller, instead of smaller->bigger)

func (PairRange[K1, K2]) EndExclusive 

func (p PairRange[K1, K2]) EndExclusive(end K2) PairRange[K1, K2]

EndExclusive makes the range contain only keys which are smaller to the provided end K2.

func (PairRange[K1, K2]) EndInclusive 

func (p PairRange[K1, K2]) EndInclusive(end K2) PairRange[K1, K2]

EndInclusive makes the range contain only keys which are smaller or equal to the provided end K2.

func (PairRange[K1, K2]) Prefix 

func (p PairRange[K1, K2]) Prefix(prefix K1) PairRange[K1, K2]

Prefix makes the range contain only keys starting with the given k1 prefix.

func (PairRange[K1, K2]) RangeValues 

func (p PairRange[K1, K2]) RangeValues() (prefix *Pair[K1, K2], start *Bound[Pair[K1, K2]], end *Bound[Pair[K1, K2]], order Order)

RangeValues implements Ranger for Pair[K1, K2]. If start and end are set, prefix must be set too or the function call will panic. The implementation returns a range which prefixes over the K1 prefix. And the key range goes from K2 start to K2 end (if any are defined). Example: given the following keys in storage: Pair["milan", "person1"] Pair["milan", "person2"] Pair["milan", "person3"] Pair["new york", "person0"] doing: PairRange[string, string].Prefix("milan").StartInclusive("person1").EndExclusive("person3") returns: Pair["milan", "person1"], Pair["milan", "person2"]

func (PairRange[K1, K2]) StartExclusive 

func (p PairRange[K1, K2]) StartExclusive(start K2) PairRange[K1, K2]

StartExclusive makes the range contain only keys which are bigger to the provided start K2.

func (PairRange[K1, K2]) StartInclusive 

func (p PairRange[K1, K2]) StartInclusive(start K2) PairRange[K1, K2]

StartInclusive makes the range contain only keys which are bigger or equal to the provided start K2.

type Range 

type Range[K any] struct {
	// contains filtered or unexported fields
}

Range is a Ranger implementer.

func (Range[K]) Descending 

func (r Range[K]) Descending() Range[K]

func (Range[K]) EndExclusive 

func (r Range[K]) EndExclusive(end K) Range[K]

EndExclusive makes the range contain only keys which are smaller to the provided end K.

func (Range[K]) EndInclusive 

func (r Range[K]) EndInclusive(end K) Range[K]

EndInclusive makes the range contain only keys which are smaller or equal to the provided end K.

func (Range[K]) Prefix 

func (r Range[K]) Prefix(key K) Range[K]

Prefix sets a fixed prefix for the key range.

func (Range[K]) RangeValues 

func (r Range[K]) RangeValues() (prefix *K, start *Bound[K], end *Bound[K], order Order)

func (Range[K]) StartExclusive 

func (r Range[K]) StartExclusive(start K) Range[K]

StartExclusive makes the range contain only keys which are bigger to the provided start K.

func (Range[K]) StartInclusive 

func (r Range[K]) StartInclusive(start K) Range[K]

StartInclusive makes the range contain only keys which are bigger or equal to the provided start K.

type Ranger 

type Ranger[K any] interface {
	// RangeValues is defined by Ranger implementers.
	// It provides instructions to generate an Iterator instance.
	// If prefix is not nil, then the Iterator will return only the keys which start
	// with the given prefix.
	// If start is not nil, then the Iterator will return only keys which are greater than the provided start
	// or greater equal depending on the bound is inclusive or exclusive.
	// If end is not nil, then the Iterator will return only keys which are smaller than the provided end
	// or smaller equal depending on the bound is inclusive or exclusive.
	RangeValues() (prefix *K, start *Bound[K], end *Bound[K], order Order)
}

Ranger defines a generic interface that provides a range of keys.

type Sequence 

type Sequence struct {
	// contains filtered or unexported fields
}

Sequence defines a collection item which contains an always increasing number. Useful for those flows which require ever raising unique ids.

func NewSequence 

func NewSequence(sk sdk.StoreKey, namespace Namespace) Sequence

NewSequence instantiates a new sequence object.

func (Sequence) Next 

func (s Sequence) Next(ctx sdk.Context) uint64

Next returns the next available sequence number and also increases the sequence number count.

func (Sequence) Peek 

func (s Sequence) Peek(ctx sdk.Context) uint64

Peek gets the next available sequence number without increasing it.

func (Sequence) Set 

func (s Sequence) Set(ctx sdk.Context, u uint64)

Set hard resets the sequence to the provided number.

type ValueEncoder 

type ValueEncoder[T any] interface {
	// Encode encodes the value T into bytes.
	Encode(value T) []byte
	// Decode returns the type T given its bytes representation.
	Decode(b []byte) T
	// Stringify returns a string representation of T.
	Stringify(value T) string
	// Name returns the name of the object.
	Name() string
}

ValueEncoder defines a generic interface which is implemented by types that are capable of encoding and decoding collection values. 

var (
	AccAddressValueEncoder ValueEncoder[sdk.AccAddress] = accAddressValueEncoder{}
	DecValueEncoder        ValueEncoder[sdk.Dec]        = decValue{}
	Uint64ValueEncoder     ValueEncoder[uint64]         = uint64Value{}
)

func ProtoValueEncoder 

func ProtoValueEncoder[V any, PV interface {
	*V
	codec.ProtoMarshaler
}](cdc codec.BinaryCodec) ValueEncoder[V]

ProtoValueEncoder returns a protobuf value encoder given the codec.BinaryCodec. It's used to convert a specific protobuf object into bytes representation and convert the protobuf object bytes representation into the concrete object.

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.