collections

package module
v0.0.0-...-095f669 Latest Latest
Warning

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

 Go to latest Published: Mar 7, 2023 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultSequenceStart uint64 = 1

DefaultSequenceStart defines the default starting number of a sequence.

View Source 
const NameRegex = "[A-Za-z][A-Za-z0-9_]*"

NameRegex is the regular expression that all valid collection names must match.

Variables

View Source 
var (
	// ErrNotFound is returned when the provided key is not present in the StorageProvider.
	ErrNotFound = errors.New("collections: not found")
	// ErrEncoding is returned when something fails during key or value encoding/decoding.
	ErrEncoding = codec.ErrEncoding
	// ErrConflict is returned when there are conflicts, for example in UniqueIndex.
	ErrConflict = errors.New("collections: conflict")
)
View Source 
var (
	// Uint16Key can be used to encode uint16 keys. Encoding is big endian to retain ordering.
	Uint16Key = codec.NewUint16Key[uint16]()
	// Uint32Key can be used to encode uint32 keys. Encoding is big endian to retain ordering.
	Uint32Key = codec.NewUint32Key[uint32]()
	// Uint64Key can be used to encode uint64 keys. Encoding is big endian to retain ordering.
	Uint64Key = codec.NewUint64Key[uint64]()
	// Int32Key can be used to encode int32 keys. Encoding retains ordering by toggling the MSB.
	Int32Key = codec.NewInt32Key[int32]()
	// Int64Key can be used to encode int64. Encoding retains ordering by toggling the MSB.
	Int64Key = codec.NewInt64Key[int64]()
	// StringKey can be used to encode string keys. The encoding just converts the string
	// to bytes.
	// Non-terminality in multipart keys is handled by appending the StringDelimiter,
	// this means that a string key when used as the non final part of a multipart key cannot
	// contain the StringDelimiter.
	// Lexicographical ordering is retained both in non and multipart keys.
	StringKey = codec.NewStringKeyCodec[string]()
	// BytesKey can be used to encode bytes keys. The encoding will just use
	// the provided bytes.
	// When used as the non-terminal part of a multipart key, we prefix the bytes key
	// with a single byte representing the length of the key. This means two things:
	// 1. When used in multipart keys the length can be at maximum 255 (max number that
	// can be represented with a single byte).
	// 2. When used in multipart keys the lexicographical ordering is lost due to the
	// length prefixing.
	// JSON encoding represents a bytes key as a hex encoded string.
	BytesKey = codec.NewBytesKey[[]byte]()
	// BoolKey can be used to encode booleans. It uses a single byte to represent the boolean.
	// 0x0 is used to represent false, and 0x1 is used to represent true.
	BoolKey = codec.NewBoolKey[bool]()
)
View Source 
var (
	// BoolValue implements a ValueCodec for bool.
	BoolValue = codec.KeyToValueCodec(BoolKey)
	// Uint16Value implements a ValueCodec for uint16.
	Uint16Value = codec.KeyToValueCodec(Uint16Key)
	// Uint32Value implements a ValueCodec for uint32.
	Uint32Value = codec.KeyToValueCodec(Uint32Key)
	// Uint64Value implements a ValueCodec for uint64.
	Uint64Value = codec.KeyToValueCodec(Uint64Key)
	// Int32Value implements a ValueCodec for int32.
	Int32Value = codec.KeyToValueCodec(Int32Key)
	// Int64Value implements a ValueCodec for int64.
	Int64Value = codec.KeyToValueCodec(Int64Key)
	// StringValue implements a ValueCodec for string.
	StringValue = codec.KeyToValueCodec(StringKey)
	// BytesValue implements a ValueCodec for bytes.
	BytesValue = codec.KeyToValueCodec(BytesKey)
)
View Source 
var ErrInvalidIterator = errors.New("collections: invalid iterator")

ErrInvalidIterator is returned when an Iterate call resulted in an invalid iterator.

Functions

func PairKeyCodec 

func PairKeyCodec[K1, K2 any](keyCodec1 codec.KeyCodec[K1], keyCodec2 codec.KeyCodec[K2]) codec.KeyCodec[Pair[K1, K2]]

PairKeyCodec instantiates a new KeyCodec instance that can encode the Pair, given the KeyCodec of the first part of the key and the KeyCodec of the second part of the key.

Types

type GenericMultiIndex 

type GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value any] struct {
	// contains filtered or unexported fields
}

GenericMultiIndex defines a generic Index type that given a primary key and the value associated with that primary key returns one or multiple IndexReference.

The referencing key can be anything, usually it is either a part of the primary key when we deal with multipart keys, or a field of Value.

The referenced key usually is the primary key, or it can be a part of the primary key in the context of multipart keys.

The Referencing and Referenced keys are joined and saved as a Pair in a KeySet where the key is Pair[ReferencingKey, ReferencedKey]. So if we wanted to get all the keys referenced by a generic (concrete) ReferencingKey we would just need to iterate over all the keys starting with bytes(ReferencingKey).

Unless you're trying to build your generic multi index, you should be using the indexes package.

func NewGenericMultiIndex 

func NewGenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value any](
	schema *SchemaBuilder,
	prefix Prefix,
	name string,
	referencingKeyCodec codec.KeyCodec[ReferencingKey],
	referencedKeyCodec codec.KeyCodec[ReferencedKey],
	getRefsFunc func(pk PrimaryKey, value Value) ([]IndexReference[ReferencingKey, ReferencedKey], error),
) *GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]

NewGenericMultiIndex instantiates a GenericMultiIndex, given schema, Prefix, humanised name, the key codec used to encode the referencing key to bytes, the key codec used to encode the referenced key to bytes and a function which given the primary key and a value of an object being saved or removed in IndexedMap returns all the possible IndexReference of that object.

The IndexReference is usually just one. But in certain cases can be multiple, for example when the Value has an array field, and we want to create a relationship between the object and all the elements of the array contained in the object.

func (*GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Has 

func (i *GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Has(
	ctx context.Context,
	referencing ReferencingKey,
	referenced ReferencedKey,
) (bool, error)

Has reports if there is a relationship in the index between the referencing and the referenced key.

func (*GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Iterate 

func (i *GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Iterate(
	ctx context.Context,
	ranger Ranger[Pair[ReferencingKey, ReferencedKey]],
) (KeySetIterator[Pair[ReferencingKey, ReferencedKey]], error)

Iterate allows to iterate over the index. It returns a KeySetIterator of Pair[ReferencingKey, ReferencedKey]. K1 of the Pair is the key (referencing) pointing to K2 (referenced).

func (*GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) IterateRaw 

func (i *GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) IterateRaw(
	ctx context.Context,
	start, end []byte,
	order Order,
) (Iterator[Pair[ReferencingKey, ReferencedKey], NoValue], error)

func (*GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) KeyCodec 

func (i *GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) KeyCodec() codec.KeyCodec[Pair[ReferencingKey, ReferencedKey]]

func (*GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Reference 

func (i *GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Reference(
	ctx context.Context,
	pk PrimaryKey,
	value Value,
	oldValue *Value,
) error

Reference implements the Index interface.

func (*GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Unreference 

func (i *GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Unreference(
	ctx context.Context,
	pk PrimaryKey,
	value Value,
) error

Unreference implements the Index interface.

func (*GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) ValueCodec 

func (i *GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) ValueCodec() codec.ValueCodec[NoValue]

func (*GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Walk 

func (i *GenericMultiIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Walk(
	ctx context.Context,
	ranger Ranger[Pair[ReferencingKey, ReferencedKey]],
	walkFunc func(referencingKey ReferencingKey, referencedKey ReferencedKey) bool,
) error

type GenericUniqueIndex 

type GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value any] struct {
	// contains filtered or unexported fields
}

GenericUniqueIndex defines a generic index which enforces uniqueness constraints between ReferencingKey and ReferencedKey, meaning that one referencing key maps only one referenced key. The same referenced key can be mapped by multiple referencing keys.

The referencing key can be anything, usually it is either a part of the primary key when we deal with multipart keys, or a field of Value.

The referenced key usually is the primary key, or it can be a part of the primary key in the context of multipart keys.

The referencing and referenced keys are mapped together using a Map.

Unless you're trying to build your generic unique index, you should be using the indexes package.

func NewGenericUniqueIndex 

func NewGenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value any](
	schema *SchemaBuilder,
	prefix Prefix,
	name string,
	referencingKeyCodec codec.KeyCodec[ReferencingKey],
	referencedKeyCodec codec.KeyCodec[ReferencedKey],
	getRefs func(pk PrimaryKey, value Value) ([]IndexReference[ReferencingKey, ReferencedKey], error),
) *GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]

NewGenericUniqueIndex instantiates a GenericUniqueIndex. Works in the same way as NewGenericMultiIndex.

func (*GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Get 

func (i *GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Get(ctx context.Context, ref ReferencingKey) (ReferencedKey, error)

func (*GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Iterate 

func (i *GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Iterate(
	ctx context.Context,
	ranger Ranger[ReferencingKey],
) (Iterator[ReferencingKey, ReferencedKey], error)

func (*GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) IterateRaw 

func (i *GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) IterateRaw(
	ctx context.Context,
	start, end []byte,
	order Order,
) (Iterator[ReferencingKey, ReferencedKey], error)

func (*GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Reference 

func (i *GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Reference(
	ctx context.Context,
	pk PrimaryKey,
	newValue Value,
	oldValue *Value,
) error

Reference implements Index.

func (*GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Unreference 

func (i *GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Unreference(
	ctx context.Context,
	pk PrimaryKey,
	value Value,
) error

Unreference implements Index.

func (*GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Walk 

func (i *GenericUniqueIndex[ReferencingKey, ReferencedKey, PrimaryKey, Value]) Walk(
	ctx context.Context,
	ranger Ranger[ReferencingKey],
	walkFunc func(referencingKey ReferencingKey, referencedKey ReferencedKey) bool,
) error

type Index 

type Index[PrimaryKey, Value any] interface {
	// Reference creates a reference between the provided primary key and value.
	// If oldValue is not nil then the Index must update the references
	// of the primary key associated with the new value and remove the
	// old invalid references.
	Reference(ctx context.Context, pk PrimaryKey, newValue Value, oldValue *Value) error
	// Unreference removes the reference between the primary key and value.
	Unreference(ctx context.Context, pk PrimaryKey, value Value) error
}

Index represents an index of the Value indexed using the type PrimaryKey.

type IndexReference 

type IndexReference[ReferencingKey, ReferencedKey any] struct {
	// Referring is the key that refers, points to the Referred key.
	Referring ReferencingKey
	// Referred is the key that is being pointed to by the Referring key.
	Referred ReferencedKey
}

IndexReference defines a generic index reference.

func NewIndexReference 

func NewIndexReference[ReferencingKey, ReferencedKey any](referencing ReferencingKey, referenced ReferencedKey) IndexReference[ReferencingKey, ReferencedKey]

type IndexedMap 

type IndexedMap[PrimaryKey, Value any, Idx Indexes[PrimaryKey, Value]] struct {
	Indexes Idx
	// contains filtered or unexported fields
}

IndexedMap works like a Map but creates references between fields of Value and its PrimaryKey. These relationships are expressed and maintained using the Indexes type. Internally IndexedMap can be seen as a partitioned collection, one partition is a Map[PrimaryKey, Value], that maintains the object, the second are the Indexes.

func NewIndexedMap 

func NewIndexedMap[PrimaryKey, Value any, Idx Indexes[PrimaryKey, Value]](
	schema *SchemaBuilder,
	prefix Prefix,
	name string,
	pkCodec codec.KeyCodec[PrimaryKey],
	valueCodec codec.ValueCodec[Value],
	indexes Idx,
) *IndexedMap[PrimaryKey, Value, Idx]

NewIndexedMap instantiates a new IndexedMap. Accepts a SchemaBuilder, a Prefix, a humanised name that defines the name of the collection, the primary key codec which is basically what IndexedMap uses to encode the primary key to bytes, the value codec which is what the IndexedMap uses to encode the value. Then it expects the initialised indexes.

func (*IndexedMap[PrimaryKey, Value, Idx]) Get 

func (m *IndexedMap[PrimaryKey, Value, Idx]) Get(ctx context.Context, pk PrimaryKey) (Value, error)

Get gets the object given its primary key.

func (*IndexedMap[PrimaryKey, Value, Idx]) Has 

func (m *IndexedMap[PrimaryKey, Value, Idx]) Has(ctx context.Context, pk PrimaryKey) (bool, error)

Has reports if exists a value with the provided primary key.

func (*IndexedMap[PrimaryKey, Value, Idx]) Iterate 

func (m *IndexedMap[PrimaryKey, Value, Idx]) Iterate(ctx context.Context, ranger Ranger[PrimaryKey]) (Iterator[PrimaryKey, Value], error)

Iterate allows to iterate over the objects given a Ranger of the primary key.

func (*IndexedMap[PrimaryKey, Value, Idx]) IterateRaw 

func (m *IndexedMap[PrimaryKey, Value, Idx]) IterateRaw(ctx context.Context, start, end []byte, order Order) (Iterator[PrimaryKey, Value], error)

IterateRaw iterates the IndexedMap using raw bytes keys. Follows the same semantics as Map.IterateRaw

func (*IndexedMap[PrimaryKey, Value, Idx]) KeyCodec 

func (m *IndexedMap[PrimaryKey, Value, Idx]) KeyCodec() codec.KeyCodec[PrimaryKey]

func (*IndexedMap[PrimaryKey, Value, Idx]) Remove 

func (m *IndexedMap[PrimaryKey, Value, Idx]) Remove(ctx context.Context, pk PrimaryKey) error

Remove removes the value associated with the primary key from the map. Then it iterates over all the indexes and instructs them to remove all the references associated with the removed value.

func (*IndexedMap[PrimaryKey, Value, Idx]) Set 

func (m *IndexedMap[PrimaryKey, Value, Idx]) Set(ctx context.Context, pk PrimaryKey, value Value) error

Set maps the value using the primary key. It will also iterate every index and instruct them to add or update the indexes.

func (*IndexedMap[PrimaryKey, Value, Idx]) ValueCodec 

func (m *IndexedMap[PrimaryKey, Value, Idx]) ValueCodec() codec.ValueCodec[Value]

func (*IndexedMap[PrimaryKey, Value, Idx]) Walk 

func (m *IndexedMap[PrimaryKey, Value, Idx]) Walk(ctx context.Context, ranger Ranger[PrimaryKey], walkFunc func(key PrimaryKey, value Value) bool) error

Walk applies the same semantics as Map.Walk.

type Indexes 

type Indexes[PrimaryKey, Value any] interface {
	// IndexesList is implemented by the Indexes type
	// and returns all the grouped Index of Value.
	IndexesList() []Index[PrimaryKey, Value]
}

Indexes represents a type which groups multiple Index of one Value saved with the provided PrimaryKey. Indexes is just meant to be a struct containing all the indexes to maintain relationship for.

type Item 

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

Item is a type declaration based on Map with a non-existent key.

func NewItem 

func NewItem[V any](
	schema *SchemaBuilder,
	prefix Prefix,
	name string,
	valueCodec codec.ValueCodec[V],
) Item[V]

NewItem instantiates a new Item instance, given the value encoder of the item V. Name and prefix must be unique within the schema and name must match the format specified by NameRegex, or else this method will panic.

func (Item[V]) Get 

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

Get gets the item, if it is not set it returns an ErrNotFound error. If value decoding fails then an ErrEncoding is returned.

func (Item[V]) Has 

func (i Item[V]) Has(ctx context.Context) (bool, error)

Has reports whether the item exists in the store or not. Returns an error in case

func (Item[V]) Remove 

func (i Item[V]) Remove(ctx context.Context) error

Remove removes the item in the store.

func (Item[V]) Set 

func (i Item[V]) Set(ctx context.Context, value V) error

Set sets the item in the store. If Value encoding fails then an ErrEncoding is returned.

type Iterator 

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

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

func (Iterator[K, V]) Close 

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

func (Iterator[K, V]) Key 

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

Key returns the current storetypes.Iterator decoded key.

func (Iterator[K, V]) KeyValue 

func (i Iterator[K, V]) KeyValue() (kv KeyValue[K, V], err error)

KeyValue returns the current key and value decoded.

func (Iterator[K, V]) KeyValues 

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

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, error)

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, error)

Value returns the current iterator value bytes decoded.

func (Iterator[K, V]) Values 

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

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

type KeySet 

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

KeySet builds on top of a Map and represents a collection retaining only a set of keys and no value. It can be used, for example, in an allow list.

func NewKeySet 

func NewKeySet[K any](schema *SchemaBuilder, prefix Prefix, name string, keyCodec codec.KeyCodec[K]) KeySet[K]

NewKeySet returns a KeySet given a Schema, Prefix a human name for the collection and a KeyCodec for the key K.

func (KeySet[K]) Has 

func (k KeySet[K]) Has(ctx context.Context, key K) (bool, error)

Has returns if the key is present in the KeySet. An error is returned only in case of encoding problems.

func (KeySet[K]) Iterate 

func (k KeySet[K]) Iterate(ctx context.Context, ranger Ranger[K]) (KeySetIterator[K], error)

Iterate iterates over the keys given the provided Ranger. If ranger is nil, the KeySetIterator will include all the existing keys within the KeySet.

func (KeySet[K]) IterateRaw 

func (k KeySet[K]) IterateRaw(ctx context.Context, start, end []byte, order Order) (Iterator[K, NoValue], error)

func (KeySet[K]) KeyCodec 

func (k KeySet[K]) KeyCodec() codec.KeyCodec[K]

func (KeySet[K]) Remove 

func (k KeySet[K]) Remove(ctx context.Context, key K) error

Remove removes the key for the KeySet. An error is returned in case of encoding error, it won't report through the error if the key was removed or not.

func (KeySet[K]) Set 

func (k KeySet[K]) Set(ctx context.Context, key K) error

Set adds the key to the KeySet. Errors on encoding problems.

func (KeySet[K]) ValueCodec 

func (k KeySet[K]) ValueCodec() codec.ValueCodec[NoValue]

func (KeySet[K]) Walk 

func (k KeySet[K]) Walk(ctx context.Context, ranger Ranger[K], walkFunc func(key K) bool) error

Walk provides the same functionality as Map.Walk, but callbacks the walk function only with the key.

type KeySetIterator 

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

KeySetIterator works like an Iterator, but it does not expose any API to deal with values.

func (KeySetIterator[K]) Close 

func (i KeySetIterator[K]) Close() error

func (KeySetIterator[K]) Key 

func (i KeySetIterator[K]) Key() (K, error)

func (KeySetIterator[K]) Keys 

func (i KeySetIterator[K]) Keys() ([]K, error)

func (KeySetIterator[K]) Next 

func (i KeySetIterator[K]) Next()

func (KeySetIterator[K]) Valid 

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

type KeyValue 

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

KeyValue represent a Key and Value pair of an iteration.

type Map 

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

Map represents the basic collections object. It is used to map arbitrary keys to arbitrary objects.

func NewMap 

func NewMap[K, V any](
	schemaBuilder *SchemaBuilder,
	prefix Prefix,
	name string,
	keyCodec codec.KeyCodec[K],
	valueCodec codec.ValueCodec[V],
) Map[K, V]

NewMap returns a Map given a StoreKey, a Prefix, human-readable name and the relative value and key encoders. Name and prefix must be unique within the schema and name must match the format specified by NameRegex, or else this method will panic.

func (Map[K, V]) Get 

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

Get returns the value associated with the provided key, errors with ErrNotFound if the key does not exist, or with ErrEncoding if the key or value decoding fails.

func (Map[K, V]) Has 

func (m Map[K, V]) Has(ctx context.Context, key K) (bool, error)

Has reports whether the key is present in storage or not. Errors with ErrEncoding if key encoding fails.

func (Map[K, V]) Iterate 

func (m Map[K, V]) Iterate(ctx context.Context, ranger Ranger[K]) (Iterator[K, V], error)

Iterate provides an Iterator over K and V. It accepts a Ranger interface. A nil ranger equals to iterate over all the keys in ascending order.

func (Map[K, V]) IterateRaw 

func (m Map[K, V]) IterateRaw(ctx context.Context, start, end []byte, order Order) (Iterator[K, V], error)

IterateRaw iterates over the collection. The iteration range is untyped, it uses raw bytes. The resulting Iterator is typed. A nil start iterates from the first key contained in the collection. A nil end iterates up to the last key contained in the collection. A nil start and a nil end iterates over every key contained in the collection. TODO(tip): simplify after https://github.com/verzth/cosmos-sdk/pull/14310 is merged

func (Map[K, V]) KeyCodec 

func (m Map[K, V]) KeyCodec() codec.KeyCodec[K]

KeyCodec returns the Map's KeyCodec.

func (Map[K, V]) Remove 

func (m Map[K, V]) Remove(ctx context.Context, key K) error

Remove removes the key from the storage. Errors with ErrEncoding if key encoding fails. If the key does not exist then this is a no-op.

func (Map[K, V]) Set 

func (m Map[K, V]) Set(ctx context.Context, key K, value V) error

Set maps the provided value to the provided key in the store. Errors with ErrEncoding if key or value encoding fails.

func (Map[K, V]) ValueCodec 

func (m Map[K, V]) ValueCodec() codec.ValueCodec[V]

ValueCodec returns the Map's ValueCodec.

func (Map[K, V]) Walk 

func (m Map[K, V]) Walk(ctx context.Context, ranger Ranger[K], walkFunc func(K, V) bool) error

Walk iterates over the Map with the provided range, calls the provided walk function with the decoded key and value. If the callback function returns true then the walking is stopped. A nil ranger equals to walking over the entire key and value set.

type NoValue 

type NoValue struct{}

func (NoValue) Decode 

func (NoValue) Decode(b []byte) (NoValue, error)

func (NoValue) DecodeJSON 

func (n NoValue) DecodeJSON(b []byte) (NoValue, error)

func (NoValue) Encode 

func (NoValue) Encode(_ NoValue) ([]byte, error)

func (NoValue) EncodeJSON 

func (n NoValue) EncodeJSON(_ NoValue) ([]byte, error)

func (NoValue) Stringify 

func (NoValue) Stringify(_ NoValue) string

func (NoValue) ValueType 

func (n NoValue) ValueType() string

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 key composed of two keys.

func Join 

func Join[K1, K2 any](key1 K1, key2 K2) Pair[K1, K2]

Join creates a new Pair instance composed of the two provided keys, in order.

func PairPrefix 

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

PairPrefix creates a new Pair instance composed only of the first part of the key.

func (Pair[K1, K2]) K1 

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

K1 returns the first part of the key. If not present the zero value is returned.

func (Pair[K1, K2]) K2 

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

K2 returns the second part of the key. If not present the zero value is returned.

type PairRange 

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

PairRange is an API that facilitates working with Pair iteration. It implements the Ranger API. Unstable: API and methods are currently unstable.

func NewPrefixedPairRange 

func NewPrefixedPairRange[K1, K2 any](prefix K1) *PairRange[K1, K2]

NewPrefixedPairRange creates a new PairRange which will prefix over all the keys starting with the provided prefix.

func (*PairRange[K1, K2]) Descending 

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

func (*PairRange[K1, K2]) EndExclusive 

func (p *PairRange[K1, K2]) EndExclusive(k2 K2) *PairRange[K1, K2]

func (*PairRange[K1, K2]) EndInclusive 

func (p *PairRange[K1, K2]) EndInclusive(k2 K2) *PairRange[K1, K2]

func (*PairRange[K1, K2]) RangeValues 

func (p *PairRange[K1, K2]) RangeValues() (start *RangeKey[Pair[K1, K2]], end *RangeKey[Pair[K1, K2]], order Order, err error)

func (*PairRange[K1, K2]) StartExclusive 

func (p *PairRange[K1, K2]) StartExclusive(k2 K2) *PairRange[K1, K2]

func (*PairRange[K1, K2]) StartInclusive 

func (p *PairRange[K1, K2]) StartInclusive(k2 K2) *PairRange[K1, K2]

type Prefix 

type Prefix []byte

Prefix defines a segregation bytes namespace for specific collections objects.

func NewPrefix 

func NewPrefix[T interface{ int | string | []byte }](identifier T) Prefix

NewPrefix returns a Prefix given the provided namespace identifier. In the same module, no prefixes should share the same starting bytes meaning that having two namespaces whose bytes representation is: p1 := []byte("prefix") p2 := []byte("prefix1") yields to iterations of p1 overlapping over p2. If a numeric prefix is provided, it must be between 0 and 255 (uint8). If out of bounds this function will panic. Reason for which this function is constrained to `int` instead of `uint8` is for API ergonomics, golang's type inference will infer int properly but not uint8 meaning that developers would need to write NewPrefix(uint8(number)) for numeric prefixes.

func (Prefix) Bytes 

func (n Prefix) Bytes() []byte

Bytes returns the raw Prefix bytes.

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() (start *RangeKey[K], end *RangeKey[K], order Order, err error)

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 RangeKey 

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

RangeKey wraps a generic range key K, acts as an enum which defines different ways to encode the wrapped key to bytes when it's being used in an iteration.

func RangeKeyExact 

func RangeKeyExact[K any](key K) *RangeKey[K]

RangeKeyExact instantiates a RangeKey that applies no modifications to the key K. So its bytes representation will not be altered.

func RangeKeyNext 

func RangeKeyNext[K any](key K) *RangeKey[K]

RangeKeyNext instantiates a RangeKey that when encoded to bytes identifies the next key after the provided key K. Example: given a string key "ABCD" the next key is bytes("ABCD\0") It's useful when defining inclusivity or exclusivity of a key in store iteration. Specifically: to make an Iterator start exclude key K I would return a RangeKeyNext(key) in the Ranger start.

func RangeKeyPrefixEnd 

func RangeKeyPrefixEnd[K any](key K) *RangeKey[K]

RangeKeyPrefixEnd instantiates a RangeKey that when encoded to bytes identifies the key that would end the prefix of the key K. Example: if the string key "ABCD" is provided, it would be encoded as bytes("ABCE").

type Ranger 

type Ranger[K any] interface {
	// RangeValues is defined by Ranger implementers.
	// The implementer can optionally return a start and an end.
	// If start is nil and end is not, the iteration will include all the keys
	// in the collection up until the provided end.
	// If start is defined and end is nil, the iteration will include all the keys
	// in the collection starting from the provided start.
	// If both are nil then the iteration will include all the possible keys in the
	// collection.
	// Order defines the order of the iteration, if order is OrderAscending then the
	// iteration will yield keys from the smallest to the biggest, if order
	// is OrderDescending then the iteration will yield keys from the biggest to the smallest.
	// Ordering is defined by the keys bytes representation, which is dependent on the KeyCodec used.
	RangeValues() (start *RangeKey[K], end *RangeKey[K], order Order, err error)
}

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

type Schema 

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

Schema specifies a group of collections stored within the storage specified by a single store key. All the collections within the schema must have a unique binary prefix and human-readable name. Schema will eventually include methods for importing/exporting genesis data and for schema reflection for clients.

func NewMemoryStoreSchema 

func NewMemoryStoreSchema(service store.MemoryStoreService) Schema

NewMemoryStoreSchema creates a new schema for the provided MemoryStoreService.

func NewSchema 

func NewSchema(service store.KVStoreService) Schema

NewSchema creates a new schema for the provided KVStoreService.

func NewSchemaFromAccessor 

func NewSchemaFromAccessor(accessor func(context.Context) store.KVStore) Schema
NewSchemaFromAccessor(func(ctx context.Context) store.KVStore {
		return sdk.UnwrapSDKContext(ctx).KVStore(kvStoreKey)
}

func (Schema) DefaultGenesis 

func (s Schema) DefaultGenesis(target appmodule.GenesisTarget) error

DefaultGenesis implements the appmodule.HasGenesis.DefaultGenesis method.

func (Schema) ExportGenesis 

func (s Schema) ExportGenesis(ctx context.Context, target appmodule.GenesisTarget) error

ExportGenesis implements the appmodule.HasGenesis.ExportGenesis method.

func (Schema) InitGenesis 

func (s Schema) InitGenesis(ctx context.Context, source appmodule.GenesisSource) error

InitGenesis implements the appmodule.HasGenesis.InitGenesis method.

func (Schema) ValidateGenesis 

func (s Schema) ValidateGenesis(source appmodule.GenesisSource) error

ValidateGenesis implements the appmodule.HasGenesis.ValidateGenesis method.

type SchemaBuilder 

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

SchemaBuilder is used for building schemas. The Build method should always be called after all collections have been initialized. Initializing new collections with the builder after initialization will result in panics.

func NewSchemaBuilder 

func NewSchemaBuilder(service store.KVStoreService) *SchemaBuilder

NewSchemaBuilder creates a new schema builder from the provided store key. Callers should always call the SchemaBuilder.Build method when they are done adding collections to the schema.

func NewSchemaBuilderFromAccessor 

func NewSchemaBuilderFromAccessor(accessorFunc func(ctx context.Context) store.KVStore) *SchemaBuilder

NewSchemaBuilderFromAccessor creates a new schema builder from the provided store accessor function.

func (*SchemaBuilder) Build 

func (s *SchemaBuilder) Build() (Schema, error)

Build should be called after all collections that are part of the schema have been initialized in order to get a reference to the Schema. It is important to check the returned error for any initialization errors. The SchemaBuilder CANNOT be used after Build is called - doing so will result in panics.

type Sequence 

type Sequence Item[uint64]

Sequence builds on top of an Item, and represents a monotonically increasing number.

func NewSequence 

func NewSequence(schema *SchemaBuilder, prefix Prefix, name string) Sequence

NewSequence instantiates a new sequence given a Schema, a Prefix and humanised name for the sequence.

func (Sequence) Next 

func (s Sequence) Next(ctx context.Context) (uint64, error)

Next returns the next sequence number, and sets the next expected sequence. Errors on encoding issues.

func (Sequence) Peek 

func (s Sequence) Peek(ctx context.Context) (uint64, error)

Peek returns the current sequence value, if no number is set then the DefaultSequenceStart is returned. Errors on encoding issues.

func (Sequence) Set 

func (s Sequence) Set(ctx context.Context, value uint64) error

Set hard resets the sequence to the provided value. Errors on encoding issues.

Source Files

View all Source files

Directories

Path Synopsis
Package codec defines how collections transform keys and values into and from bytes.
 Package codec defines how collections transform keys and values into and from bytes.
Package indexes contains the most common indexes types to be used with a collections.IndexedMap.
 Package indexes contains the most common indexes types to be used with a collections.IndexedMap.

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.