codec

Documentation

Overview

Package codec defines how collections transform keys and values into and from bytes.

Index

• Constants
• Variables
• type AltValueCodec
  • func (a AltValueCodec[V]) Decode(b []byte) (V, error)
  • func (a AltValueCodec[V]) DecodeJSON(b []byte) (V, error)
  • func (a AltValueCodec[V]) Encode(value V) ([]byte, error)
  • func (a AltValueCodec[V]) EncodeJSON(value V) ([]byte, error)
  • func (a AltValueCodec[V]) Stringify(value V) string
  • func (a AltValueCodec[V]) ValueType() string
• type KeyCodec
  • func NewBoolKey[T ~bool]() KeyCodec[T]
  • func NewBytesKey[T ~[]byte]() KeyCodec[T]
  • func NewInt32Key[T ~int32]() KeyCodec[T]
  • func NewInt64Key[T ~int64]() KeyCodec[T]
  • func NewStringKeyCodec[T ~string]() KeyCodec[T]
  • func NewUint16Key[T ~uint16]() KeyCodec[T]
  • func NewUint32Key[T ~uint32]() KeyCodec[T]
  • func NewUint64Key[T ~uint64]() KeyCodec[T]
• type UntypedValueCodec
  • func NewUntypedValueCodec[V any](v ValueCodec[V]) UntypedValueCodec
• type ValueCodec
  • func KeyToValueCodec[K any](keyCodec KeyCodec[K]) ValueCodec[K]
  • func NewAltValueCodec[V any](canonicalValueCodec ValueCodec[V], alternativeDecoder func([]byte) (V, error)) ValueCodec[V]

Constants

const MaxBytesKeyNonTerminalSize = math.MaxUint8

MaxBytesKeyNonTerminalSize defines the maximum length of a bytes key encoded using the BytesKey KeyCodec.

const (
	// StringDelimiter defines the delimiter of a string key when used in non-terminal encodings.
	StringDelimiter uint8 = 0x0
)

Variables

var ErrEncoding = errors.New("collections: encoding error")

Types

type AltValueCodec

type AltValueCodec[V any] struct {
	// contains filtered or unexported fields
}

AltValueCodec is a codec that can decode a value from state in an alternative format. This is useful for migrating data from one format to another. For example, in x/bank balances were initially encoded as sdk.Coin, now they are encoded as math.Int. The AltValueCodec will be trying to decode the value as math.Int, and if that fails, it will attempt to decode it as sdk.Coin. NOTE: if the canonical format can also decode the alternative format, then this codec will produce undefined and undesirable behavior.

func (AltValueCodec[V]) Decode

func (a AltValueCodec[V]) Decode(b []byte) (V, error)

Decode will attempt to decode the value from state using the canonical value codec. If it fails to decode, it will attempt to decode the value using the alternative decoder.

func (AltValueCodec[V]) DecodeJSON

func (a AltValueCodec[V]) DecodeJSON(b []byte) (V, error)

func (AltValueCodec[V]) Encode

func (a AltValueCodec[V]) Encode(value V) ([]byte, error)

func (AltValueCodec[V]) EncodeJSON

func (a AltValueCodec[V]) EncodeJSON(value V) ([]byte, error)

func (AltValueCodec[V]) Stringify

func (a AltValueCodec[V]) Stringify(value V) string

func (AltValueCodec[V]) ValueType

func (a AltValueCodec[V]) ValueType() string

type KeyCodec

type KeyCodec[T any] interface {
	// Encode writes the key bytes into the buffer. Returns the number of
	// bytes written. The implementer must expect the buffer to be at least
	// of length equal to Size(K) for all encodings.
	// It must also return the number of written bytes which must be
	// equal to Size(K) for all encodings not involving varints.
	// In case of encodings involving varints then the returned
	// number of written bytes is allowed to be smaller than Size(K).
	Encode(buffer []byte, key T) (int, error)
	// Decode reads from the provided bytes buffer to decode
	// the key T. Returns the number of bytes read, the type T
	// or an error in case of decoding failure.
	Decode(buffer []byte) (int, T, error)
	// Size returns the buffer size need to encode key T in binary format.
	// The returned value must match what is computed by Encode for all
	// encodings except the ones involving varints. Varints are expected
	// to return the maximum varint bytes buffer length, at the risk of
	// over-estimating in order to pick the most performant path.
	Size(key T) int
	// EncodeJSON encodes the value as JSON.
	EncodeJSON(value T) ([]byte, error)
	// DecodeJSON decodes the provided JSON bytes into an instance of T.
	DecodeJSON(b []byte) (T, error)
	// Stringify returns a string representation of T.
	Stringify(key T) string
	// KeyType returns a string identifier for the type of the key.
	KeyType() string

	// EncodeNonTerminal writes the key bytes into the buffer.
	// EncodeNonTerminal is used in multipart keys like Pair
	// when the part of the key being encoded is not the last one,
	// and there needs to be a way to distinguish after how many bytes
	// the first part of the key is finished. The buffer is expected to be
	// at least as big as SizeNonTerminal(key) returns. It returns
	// the amount of bytes written.
	EncodeNonTerminal(buffer []byte, key T) (int, error)
	// DecodeNonTerminal reads the buffer provided and returns
	// the key T. DecodeNonTerminal is used in multipart keys
	// like Pair when the part of the key being decoded is not the
	// last one. It returns the amount of bytes read.
	DecodeNonTerminal(buffer []byte) (int, T, error)
	// SizeNonTerminal returns the maximum size of the key K when used in
	// multipart keys like Pair.
	SizeNonTerminal(key T) int
}

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

func NewBoolKey

func NewBoolKey[T ~bool]() KeyCodec[T]

func NewBytesKey

func NewBytesKey[T ~[]byte]() KeyCodec[T]

func NewInt32Key

func NewInt32Key[T ~int32]() KeyCodec[T]

func NewInt64Key

func NewInt64Key[T ~int64]() KeyCodec[T]

func NewStringKeyCodec

func NewStringKeyCodec[T ~string]() KeyCodec[T]

func NewUint16Key

func NewUint16Key[T ~uint16]() KeyCodec[T]

func NewUint32Key

func NewUint32Key[T ~uint32]() KeyCodec[T]

func NewUint64Key

func NewUint64Key[T ~uint64]() KeyCodec[T]

type UntypedValueCodec

type UntypedValueCodec struct {
	Decode     func(b []byte) (interface{}, error)
	Encode     func(value interface{}) ([]byte, error)
	DecodeJSON func(b []byte) (interface{}, error)
	EncodeJSON func(value interface{}) ([]byte, error)
	Stringify  func(value interface{}) (string, error)
	ValueType  func() string
}

UntypedValueCodec wraps a ValueCodec to expose an untyped API for encoding and decoding values.

func NewUntypedValueCodec

func NewUntypedValueCodec[V any](v ValueCodec[V]) UntypedValueCodec

NewUntypedValueCodec returns an UntypedValueCodec for the provided ValueCodec.

type ValueCodec

type ValueCodec[T any] interface {
	// Encode encodes the value T into binary format.
	Encode(value T) ([]byte, error)
	// Decode returns the type T given its binary representation.
	Decode(b []byte) (T, error)
	// EncodeJSON encodes the value as JSON.
	EncodeJSON(value T) ([]byte, error)
	// DecodeJSON decodes the provided JSON bytes into an instance of T.
	DecodeJSON(b []byte) (T, error)
	// Stringify returns a string representation of T.
	Stringify(value T) string
	// ValueType returns the identifier for the type.
	ValueType() string
}

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

func KeyToValueCodec

func KeyToValueCodec[K any](keyCodec KeyCodec[K]) ValueCodec[K]

KeyToValueCodec converts a KeyCodec into a ValueCodec.

func NewAltValueCodec

func NewAltValueCodec[V any](canonicalValueCodec ValueCodec[V], alternativeDecoder func([]byte) (V, error)) ValueCodec[V]

NewAltValueCodec returns a new AltValueCodec. canonicalValueCodec is the codec that you want the value to be encoded and decoded as, alternativeDecoder is a function that will attempt to decode the value in case the canonicalValueCodec fails to decode it.