Trait Codec

pub trait Codec:
    Default
    + Sized
    + PartialEq
    + 'static {
    type Schema: Schema2<Self> + PartialEq;
    type Storage: Default;

    // Required methods
    fn codec_name() -> String;
    fn encode<B>(&self, buf: &mut B)
       where B: BufMut;
    fn decode<'a>(buf: &'a [u8], schema: &Self::Schema) -> Result<Self, String>;
    fn encode_schema(schema: &Self::Schema) -> Bytes;
    fn decode_schema(buf: &Bytes) -> Self::Schema;

    // Provided methods
    fn encode_to_vec(&self) -> Vec<u8>  { ... }
    fn decode_from<'a>(
        &mut self,
        buf: &'a [u8],
        _storage: &mut Option<Self::Storage>,
        schema: &Self::Schema,
    ) -> Result<(), String> { ... }
    fn validate(_val: &Self, _schema: &Self::Schema) -> Result<(), String> { ... }
}

Encoding and decoding operations for a type usable as a persisted key or value.

Required Associated Types

type Schema: Schema2<Self> + PartialEq

The type of the associated schema for Self.

This is a separate type because Row is not self-describing. For Row, you need a RelationDesc to determine the types of any columns that are Datum::Null.

type Storage: Default

A type used with Self::decode_from for allocation reuse. Set to () if unnecessary.

Required Methods

fn codec_name() -> String

Name of the codec.

This name is stored for the key and value when a stream is first created and the same key and value codec must be used for that stream afterward.

fn encode<B>(&self, buf: &mut B)

where B: BufMut,

Encode a key or value for permanent storage.

This must perfectly round-trip Self through Codec::decode. If the encode function for this codec ever changes, decode must be able to handle bytes output by all previous versions of encode.

fn decode<'a>(buf: &'a [u8], schema: &Self::Schema) -> Result<Self, String>

Decode a key or value previous encoded with this codec’s Codec::encode.

This must perfectly round-trip Self through Codec::encode. If the encode function for this codec ever changes, decode must be able to handle bytes output by all previous versions of encode.

It should also gracefully handle data encoded by future versions of encode (likely with an error).

fn encode_schema(schema: &Self::Schema) -> Bytes

Encode a schema for permanent storage.

This must perfectly round-trip the schema through Self::decode_schema. If the encode_schema function ever changes, decode_schema must be able to handle bytes output by all previous versions of encode_schema.

TODO: Move this to instead be a new trait that is required by Self::Schema?

fn decode_schema(buf: &Bytes) -> Self::Schema

Decode a schema previous encoded with this codec’s Self::encode_schema.

This must perfectly round-trip the schema through Self::encode_schema. If the encode_schema function ever changes, decode_schema must be able to handle bytes output by all previous versions of encode_schema.

Provided Methods

fn encode_to_vec(&self) -> Vec<u8>

Encode a key or value to a Vec.

This is a convenience function for calling Self::encode with a fresh Vec each time. Reuse an allocation when performance matters!

fn decode_from<'a>( &mut self, buf: &'a [u8], _storage: &mut Option<Self::Storage>, schema: &Self::Schema, ) -> Result<(), String>

An alternate form of Self::decode which enables amortizing allocs.

First, instead of returning Self, it takes &mut Self as a parameter, allowing for reuse of the internal Row/SourceData allocations.

Second, it adds a type Storage to Codec and also passes it in as &mut Option<Self::Storage>, allowing for reuse of ProtoRow/ProtoSourceData allocations. If Some, this impl may attempt to reuse allocations with it. It may also leave allocations in it for use in future calls to decode_from.

A default implementation is provided for Codec impls that can’t take advantage of this.

fn validate(_val: &Self, _schema: &Self::Schema) -> Result<(), String>

Checks that the given value matches the provided schema.

A no-op default implementation is provided for convenience.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl Codec for ()

type Storage = ()

type Schema = UnitSchema

fn codec_name() -> String

fn encode<B>(&self, _buf: &mut B)

where B: BufMut,

fn decode<'a>(buf: &'a [u8], _schema: &UnitSchema) -> Result<Self, String>

fn encode_schema(_schema: &Self::Schema) -> Bytes

fn decode_schema(buf: &Bytes) -> Self::Schema

impl Codec for String

type Storage = ()

type Schema = StringSchema

fn codec_name() -> String

fn encode<B>(&self, buf: &mut B)

where B: BufMut,

fn decode<'a>(buf: &'a [u8], _schema: &StringSchema) -> Result<Self, String>

fn encode_schema(_schema: &Self::Schema) -> Bytes

fn decode_schema(buf: &Bytes) -> Self::Schema

impl Codec for Vec<u8>

type Storage = ()

type Schema = VecU8Schema

fn codec_name() -> String

fn encode<B>(&self, buf: &mut B)

where B: BufMut,

fn decode<'a>(buf: &'a [u8], _schema: &VecU8Schema) -> Result<Self, String>

fn encode_schema(_schema: &Self::Schema) -> Bytes

fn decode_schema(buf: &Bytes) -> Self::Schema

Implementors

impl Codec for ShardId

type Storage = ()

type Schema = ShardIdSchema