codec

Documentation

Overview

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

Index

• Constants
• Variables
• 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 ValueCodec
  • func KeyToValueCodec[K any](keyCodec KeyCodec[K]) ValueCodec[K]

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