Skip to main content

SingularCodec

Trait SingularCodec 

Source
pub trait SingularCodec {
    type Value;

    // Required methods
    fn decode_one(data: &UnknownFieldData) -> Option<Self::Value>;
    fn decode_packed(bytes: &[u8], out: &mut Vec<Self::Value>);
    fn try_encode_one(
        value: &Self::Value,
    ) -> Result<UnknownFieldData, EncodeError>;

    // Provided methods
    fn decode_one_ctx(
        data: &UnknownFieldData,
        _ctx: DecodeContext<'_>,
    ) -> Option<Self::Value> { ... }
    fn encode_one(value: &Self::Value) -> UnknownFieldData { ... }
}
Expand description

Codecs that can appear as elements of Repeated / PackedRepeated.

Separated from ExtensionCodec because the singular decode semantics differ by type: scalars use last-wins, but singular messages merge all records. This trait provides the per-record primitives; each codec assembles them into its own ExtensionCodec::decode.

Required Associated Types§

Required Methods§

Source

fn decode_one(data: &UnknownFieldData) -> Option<Self::Value>

Decode one value from one unknown-field record’s data.

Returns None on wire-type mismatch (and, for string/message, on malformed payload).

Source

fn decode_packed(bytes: &[u8], out: &mut Vec<Self::Value>)

Decode all values from a packed LengthDelimited payload.

Non-packable types (string, bytes, message) must leave out unmodified: decode_repeated falls through to this method when decode_one returns None for a LengthDelimited record, relying on the no-op to skip malformed elements. A LengthDelimited record at their field number IS the single value — there is no packed form.

Source

fn try_encode_one(value: &Self::Value) -> Result<UnknownFieldData, EncodeError>

Encode one value as a single unknown-field record.

The one required encode method — same fallible-required contract as ExtensionCodec::try_encode: infallible codecs (every scalar) end with Ok(...), and the message/group codecs surface an over-limit value as an error. Do not implement this in terms of encode_one — that provided wrapper calls back here.

§Errors

Returns EncodeError::MessageTooLarge if a message-typed value’s encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

Provided Methods§

Source

fn decode_one_ctx( data: &UnknownFieldData, _ctx: DecodeContext<'_>, ) -> Option<Self::Value>

Decode one value under a decode context shared with the other records of the same field.

Defaults to decode_one, which is correct for any codec whose per-record cost is fixed — every scalar, string, and bytes codec. A codec whose value can materialize an unbounded subtree must override this, or each record silently gets its own full allowance of the crate-default limits.

Such an override should also charge the value’s size_of with ctx.register_element_memory before it builds the value, as MessageCodec and GroupCodec do. That charge bounds the Vec a repeated extension returns.

For a repeated extension, a None returned while ctx.remaining_element_memory() is Some(0) ends the whole list: the records after this one are not read. With budget left, a None skips this record only. The built-in message and group codecs end the list at the first element that exceeds the element budget, including when a charge inside the element’s own decode fails. A failed charge leaves the budget unchanged, so an override gets the same stop by spending what is left before it returns None: it passes the value of remaining_element_memory() to register_element_memory.

Source

fn encode_one(value: &Self::Value) -> UnknownFieldData

Panicking wrapper over try_encode_one.

§Panics

Panics if try_encode_one fails — i.e. a message-typed value’s encoded size exceeds the 2 GiB protobuf limit.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§