store

Documentation

Overview

Package store implements KVStore getters and setters for various types.

Numerical getters and setters have a minimum value of zero, which will be interpreted as follows:

• Setters clear a KVStore entry when setting to exactly zero.
• Getters panic on unmarshal error, and interpret empty data as zero.

All functions which can fail require an errField parameter which is used when creating error messages. For example, the errField "balance" could appear in errors like "-12: cannot set negative balance". These errFields are cosmetic and do not affect the stored data (key or value) in any way.

Index

• func GetAddress(store sdk.KVStore, key []byte) sdk.AccAddress
• func GetBinValue[TPtr PtrBinMarshalable[T], T any](store sdk.KVStore, key []byte, errField string) (TPtr, error)
• func GetDec(store sdk.KVStore, key []byte, errField string) sdk.Dec
• func GetInt(store sdk.KVStore, key []byte, errField string) sdkmath.Int
• func GetInteger[T Integer](store sdk.KVStore, key []byte) T
• func GetObject(store sdk.KVStore, cdc codec.Codec, key []byte, object codec.ProtoMarshaler, ...) bool
• func GetValue[TPtr PtrMarshalable[T], T any](store sdk.KVStore, key []byte, errField string) TPtr
• func Int(bz []byte, errField string) sdkmath.Int
• func Iterate(store sdk.KVStore, prefix []byte, cb func(key, val []byte) error) error
• func IteratePaginated(store sdk.KVStore, prefix []byte, page, limit uint, ...) error
• func LoadAll[TPtr PtrMarshalable[T], T any](s storetypes.KVStore, prefix []byte) ([]T, error)
• func MustLoadAll[TPtr PtrMarshalable[T], T any](s storetypes.KVStore, prefix []byte) []T
• func SetAddress(store sdk.KVStore, key []byte, val sdk.AccAddress)
• func SetBinValue[T BinMarshalable](store sdk.KVStore, key []byte, value T, errField string) error
• func SetDec(store sdk.KVStore, key []byte, val sdk.Dec, errField string) error
• func SetInt(store sdk.KVStore, key []byte, val sdkmath.Int, errField string) error
• func SetInteger[T Integer](store sdk.KVStore, key []byte, v T)
• func SetObject(store sdk.KVStore, cdc codec.Codec, key []byte, object codec.ProtoMarshaler, ...) error
• func SetValue[T Marshalable](store sdk.KVStore, key []byte, value T, errField string) error
• func SumCoins(s storetypes.KVStore, f StrExtractor) sdk.Coins
• type BinMarshalable
• type Integer
• type Marshalable
• type PtrBinMarshalable
• type PtrMarshalable
• type StrExtractor

Functions

func GetAddress

func GetAddress(store sdk.KVStore, key []byte) sdk.AccAddress

GetAddress retrieves an sdk.AccAddress from a KVStore, or an empty address if no value is stored. Accepts an additional string which should describe the field being retrieved in custom error messages.

func GetBinValue

func GetBinValue[TPtr PtrBinMarshalable[T], T any](store sdk.KVStore, key []byte, errField string) (TPtr, error)

GetBinValue is similar to GetValue (loads value in the store), but uses UnmarshalBinary interface instead of protobuf

func GetDec

func GetDec(store sdk.KVStore, key []byte, errField string) sdk.Dec

GetDec retrieves an sdk.Dec from a KVStore, or returns zero if no value is stored. Accepts an additional string which should describe the field being retrieved in custom error messages.

func GetInt

func GetInt(store sdk.KVStore, key []byte, errField string) sdkmath.Int

GetInt retrieves an sdkmath.Int from a KVStore, or returns zero if no value is stored. It panics if a stored value fails to unmarshal or is negative. Accepts an additional string which should describe the field being retrieved in custom error messages.

func GetInteger

func GetInteger[T Integer](store sdk.KVStore, key []byte) T

func GetObject

func GetObject(store sdk.KVStore, cdc codec.Codec, key []byte, object codec.ProtoMarshaler, errField string) bool

GetObject gets and unmarshals a structure from KVstore. Panics on failure to decode, and returns a boolean indicating whether any data was found. If the return is false, the object might not be initialized with valid zero values for its type.

func GetValue

func GetValue[TPtr PtrMarshalable[T], T any](store sdk.KVStore, key []byte, errField string) TPtr

GetValue loads value from the store using default Unmarshaler

func Int

func Int(bz []byte, errField string) sdkmath.Int

Int converts bytes to sdk.Int, and panics on failure or negative value with a message which includes the name of the value being retrieved

func Iterate

func Iterate(store sdk.KVStore, prefix []byte, cb func(key, val []byte) error) error

Iterate through all keys in a kvStore that start with a given prefix using a provided function. If the provided function returns an error, iteration stops and the error is returned.

func IteratePaginated

func IteratePaginated(store sdk.KVStore, prefix []byte, page, limit uint, cb func(key, val []byte) error) error

IteratePaginated through keys in a kvStore that start with a given prefix using a provided function. If the provided function returns an error, iteration stops and the error is returned. Accepts pagination parameters: limit defines a number of keys per page, and page indicates what page to skip to when iterating. For example, page = 3 and limit = 10 will iterate over the 21st - 30th keys that would be found by a non-paginated iterator.

func LoadAll

func LoadAll[TPtr PtrMarshalable[T], T any](s storetypes.KVStore, prefix []byte) ([]T, error)

LoadAll iterates over all records in the prefix store and unmarshals value into the list.

func MustLoadAll

func MustLoadAll[TPtr PtrMarshalable[T], T any](s storetypes.KVStore, prefix []byte) []T

MustLoadAll executes LoadAll and panics on error

func SetAddress

func SetAddress(store sdk.KVStore, key []byte, val sdk.AccAddress)

SetAddress stores an sdk.AccAddress in a KVStore, or clears if setting to an empty or nil address. Accepts an additional string which should describe the field being set in custom error messages.

func SetBinValue

func SetBinValue[T BinMarshalable](store sdk.KVStore, key []byte, value T, errField string) error

SetBinValue is similar to SetValue (stores value in the store), but uses UnmarshalBinary interface instead of protobuf

func SetDec

func SetDec(store sdk.KVStore, key []byte, val sdk.Dec, errField string) error

SetDec stores an sdk.Dec in a KVStore, or clears if setting to zero or nil. Returns an error serialization failure. Accepts an additional string which should describe the field being set in custom error messages.

func SetInt

func SetInt(store sdk.KVStore, key []byte, val sdkmath.Int, errField string) error

SetInt stores an sdkmath.Int in a KVStore, or clears if setting to zero or nil. Returns an error on serialization error. Accepts an additional string which should describe the field being set in custom error messages.

func SetInteger

func SetInteger[T Integer](store sdk.KVStore, key []byte, v T)

func SetObject

func SetObject(store sdk.KVStore, cdc codec.Codec, key []byte, object codec.ProtoMarshaler, errField string) error

SetObject marshals and sets a structure in KVstore. Returns error on failure to encode.

func SetValue

func SetValue[T Marshalable](store sdk.KVStore, key []byte, value T, errField string) error

SetValue saves value in the store using default Marshaler

func SumCoins

func SumCoins(s storetypes.KVStore, f StrExtractor) sdk.Coins

SumCoins aggregates all coins saved as (denom: Int) pairs in store. Use store/prefix.NewStore to create a prefix store which will automatically look only at the given prefix.

Types

type BinMarshalable

type BinMarshalable interface {
	MarshalBinary() ([]byte, error)
	UnmarshalBinary(data []byte) error
}

type Integer

type Integer interface {
	~int32 | ~int64 | ~uint32 | ~uint64 | byte
}

type Marshalable

type Marshalable interface {
	Marshal() ([]byte, error)
	MarshalTo(data []byte) (n int, err error)
	Unmarshal(data []byte) error
}

type PtrBinMarshalable

type PtrBinMarshalable[T any] interface {
	BinMarshalable
	*T
}

type PtrMarshalable

type PtrMarshalable[T any] interface {
	Marshalable
	*T
}

type StrExtractor

type StrExtractor func([]byte) string

StrExtractor is a function type which will take a bytes string value and extracts string out of it.