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 HasSchemaCodec
• type KeyCodec
• type NameableKeyCodec
  • func NewBoolKey[T ~bool]() NameableKeyCodec[T]
  • func NewBytesKey[T ~[]byte]() NameableKeyCodec[T]
  • func NewInt32Key[T ~int32]() NameableKeyCodec[T]
  • func NewInt64Key[T ~int64]() NameableKeyCodec[T]
  • func NewStringKeyCodec[T ~string]() NameableKeyCodec[T]
  • func NewUint16Key[T ~uint16]() NameableKeyCodec[T]
  • func NewUint32Key[T ~uint32]() NameableKeyCodec[T]
  • func NewUint64Key[T ~uint64]() NameableKeyCodec[T]
• type NameableValueCodec
  • func KeyToValueCodec[K any](keyCodec KeyCodec[K]) NameableValueCodec[K]
• type NamedKeyCodec
  • func (n NamedKeyCodec[T]) SchemaCodec() (SchemaCodec[T], error)
• type NamedValueCodec
  • func (n NamedValueCodec[T]) SchemaCodec() (SchemaCodec[T], error)
• type SchemaCodec
  • func FallbackSchemaCodec[T any]() SchemaCodec[T]
  • func KeySchemaCodec[K any](cdc KeyCodec[K]) (SchemaCodec[K], error)
  • func ValueSchemaCodec[V any](cdc ValueCodec[V]) (SchemaCodec[V], error)
• type UntypedValueCodec
  • func NewUntypedValueCodec[V any](v ValueCodec[V]) UntypedValueCodec
• type ValueCodec
  • 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 HasSchemaCodec

type HasSchemaCodec[T any] interface {
	// SchemaCodec returns the schema codec for the collections codec.
	SchemaCodec() (SchemaCodec[T], error)
}

HasSchemaCodec is an interface that all codec's should implement in order to properly support indexing. It is not required by KeyCodec or ValueCodec in order to preserve backwards compatibility, but a future version of collections may make it required and all codec's should aim to implement it. If it is not implemented, fallback defaults will be used for indexing that may be sub-optimal.

Implementations of HasSchemaCodec should test that they are conformant using schema.ValidateObjectKey or schema.ValidateObjectValue depending on whether the codec is a KeyCodec or ValueCodec respectively.

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.

type NameableKeyCodec

type NameableKeyCodec[T any] interface {
	KeyCodec[T]

	// WithName returns the KeyCodec with the provided name.
	WithName(name string) KeyCodec[T]
}

NameableKeyCodec is a KeyCodec that can be named.

func NewBoolKey

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

func NewBytesKey

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

func NewInt32Key

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

func NewInt64Key

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

func NewStringKeyCodec

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

func NewUint16Key

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

func NewUint32Key

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

func NewUint64Key

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

type NameableValueCodec

type NameableValueCodec[T any] interface {
	ValueCodec[T]

	// WithName returns the ValueCodec with the provided name.
	WithName(name string) ValueCodec[T]
}

NameableValueCodec is a ValueCodec that can be named.

func KeyToValueCodec

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

KeyToValueCodec converts a KeyCodec into a ValueCodec.

type NamedKeyCodec

type NamedKeyCodec[T any] struct {
	KeyCodec[T]

	// Name is the name of the KeyCodec in the schema.
	Name string
}

NamedKeyCodec wraps a KeyCodec with a name. The underlying key codec MUST have exactly one field in its schema.

func (NamedKeyCodec[T]) SchemaCodec

func (n NamedKeyCodec[T]) SchemaCodec() (SchemaCodec[T], error)

SchemaCodec returns the schema codec for the named key codec.

type NamedValueCodec

type NamedValueCodec[T any] struct {
	ValueCodec[T]

	// Name is the name of the ValueCodec in the schema.
	Name string
}

NamedValueCodec wraps a ValueCodec with a name. The underlying value codec MUST have exactly one field in its schema.

func (NamedValueCodec[T]) SchemaCodec

func (n NamedValueCodec[T]) SchemaCodec() (SchemaCodec[T], error)

SchemaCodec returns the schema codec for the named value codec.

type SchemaCodec

type SchemaCodec[T any] struct {
	// Fields are the schema fields that the codec represents. If this is empty,
	// it will be assumed that this codec represents no value (such as an item key
	// or key set value).
	Fields []schema.Field

	// ToSchemaType converts a codec value of type T to a value corresponding to
	// a schema object key or value (depending on whether this is a key or value
	// codec). The returned value should pass validation with schema.ValidateObjectKey
	// or schema.ValidateObjectValue with the fields specified in Fields.
	// If this function is nil, it will be assumed that T already represents a
	// value that conforms to a schema value without any further conversion.
	ToSchemaType func(T) (any, error)

	// FromSchemaType converts a schema object key or value to T.
	// If this function is nil, it will be assumed that T already represents a
	// value that conforms to a schema value without any further conversion.
	FromSchemaType func(any) (T, error)
}

SchemaCodec is a codec that supports converting collection codec values to and from schema codec values.

func FallbackSchemaCodec

func FallbackSchemaCodec[T any]() SchemaCodec[T]

FallbackSchemaCodec returns a fallback schema codec for T when one isn't explicitly specified with HasSchemaCodec. It maps all simple types directly to schema kinds and converts everything else to JSON String.

func KeySchemaCodec

func KeySchemaCodec[K any](cdc KeyCodec[K]) (SchemaCodec[K], error)

KeySchemaCodec gets the schema codec for the provided KeyCodec either by casting to HasSchemaCodec or returning a fallback codec.

func ValueSchemaCodec

func ValueSchemaCodec[V any](cdc ValueCodec[V]) (SchemaCodec[V], error)

ValueSchemaCodec gets the schema codec for the provided ValueCodec either by casting to HasSchemaCodec or returning a fallback codec.

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 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.