Skip to main content

ExtensionSet

Trait ExtensionSet 

Source
pub trait ExtensionSet {
    const PROTO_FQN: &'static str;

    // Required methods
    fn unknown_fields(&self) -> &UnknownFields;
    fn unknown_fields_mut(&mut self) -> &mut UnknownFields;

    // Provided methods
    fn extension<C: ExtensionCodec>(&self, ext: &Extension<C>) -> C::Output { ... }
    fn set_extension<C: ExtensionCodec>(
        &mut self,
        ext: &Extension<C>,
        value: C::Value,
    ) { ... }
    fn try_set_extension<C: ExtensionCodec>(
        &mut self,
        ext: &Extension<C>,
        value: C::Value,
    ) -> Result<(), EncodeError> { ... }
    fn has_extension<C: ExtensionCodec>(&self, ext: &Extension<C>) -> bool { ... }
    fn clear_extension<C: ExtensionCodec>(&mut self, ext: &Extension<C>) { ... }
    fn extension_or_default<C>(&self, ext: &Extension<C>) -> C::Value
       where C: ExtensionCodec<Output = Option<<C as ExtensionCodec>::Value>>,
             C::Value: Default { ... }
}
Expand description

Implemented by codegen on every message that preserves unknown fields.

The only required methods are the two unknown_fields* accessors; all extension operations are defaulted on top of them. The generated impl is therefore a two-line body.

Not object-safe (the default methods are generic over C). Extension access is always statically dispatched from a const descriptor.

Required Associated Constants§

Source

const PROTO_FQN: &'static str

Fully-qualified proto type name of this message (no leading dot), e.g. "google.protobuf.FieldOptions".

Checked against Extension::extendee on every call of an accessor that reads, writes or clears an extension; the module documentation lists them. A mismatch panics: passing an extension for the wrong message is a bug in the caller.

Equal to MessageName::FULL_NAME for generated messages — both come from the same proto_fqn in codegen. Hand-written impls that implement both traits must keep the two strings in sync; a mismatch surfaces as a runtime panic on extension access rather than at compile time.

If you only need the message’s full name (no extension access), prefer MessageName::FULL_NAME: it is a standalone trait that doesn’t require the extension machinery or the unknown_fields=true codegen option (which adds an __buffa_unknown_fields storage field to the generated struct).

Required Methods§

Source

fn unknown_fields(&self) -> &UnknownFields

Immutable access to the extendee’s unknown-field storage.

Source

fn unknown_fields_mut(&mut self) -> &mut UnknownFields

Mutable access to the extendee’s unknown-field storage.

Provided Methods§

Source

fn extension<C: ExtensionCodec>(&self, ext: &Extension<C>) -> C::Output

Read an extension value.

For singular extensions: Option<T> — None if absent, if the stored wire data is malformed for this codec, or if the extension’s records together exhaust the decode budget.

For repeated: Vec<T>, in wire order. A record that is malformed for this codec is skipped.

One decode budget covers every record of one extension. It is always the crate default, whatever DecodeOptions decoded the carrier. For a repeated message or group extension, each element’s size_of is charged to DEFAULT_ELEMENT_MEMORY_LIMIT before the element is built, and the elements of the repeated and map fields inside it are charged as it decodes. A charge is never refunded, also for an element that is skipped, so the budget bounds the element storage that one call builds. The contents of strings and bytes are outside this budget.

The getter stops at the first element that exceeds this budget and returns the elements decoded before it. An element that fails for another limit, the unknown-field allowance or the recursion limit, is skipped like a malformed one, so only the element budget ends the list.

For a message or group extension each record is one element. To learn whether elements are missing, compare the returned length with the number of records in unknown_fields whose number is ext.number().

§Panics

Panics if ext.extendee() does not match Self::PROTO_FQN.

Source

fn set_extension<C: ExtensionCodec>( &mut self, ext: &Extension<C>, value: C::Value, )

Write an extension value, replacing any prior occurrences.

§Panics

Panics if ext.extendee() does not match Self::PROTO_FQN.

Message-typed extension values are encoded to wire bytes on set, so this also panics if the value’s encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES) — see try_set_extension for the error-returning variant.

Source

fn try_set_extension<C: ExtensionCodec>( &mut self, ext: &Extension<C>, value: C::Value, ) -> Result<(), EncodeError>

Write an extension value, replacing any prior occurrences — returning an error instead of panicking if a message-typed value’s encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

On Err, the extendee’s unknown fields are unchanged — prior occurrences are retained.

§Errors

Returns EncodeError::MessageTooLarge if a message-typed value’s encoded size exceeds the limit. Scalar-typed extensions cannot fail.

§Panics

Panics if ext.extendee() does not match Self::PROTO_FQN — passing an extension for the wrong message is a bug in the caller, not a runtime condition.

Source

fn has_extension<C: ExtensionCodec>(&self, ext: &Extension<C>) -> bool

Returns true if any record at the extension’s field number is present.

Does not check wire-type validity — this is a fast presence test, not a decode. Also does not check extendee identity: asking “is this extension set here” when it can’t extend here has a legitimate answer (false). This matches protobuf-go’s HasExtension and protobuf-es’s hasExtension, both of which return false gracefully on mismatch.

Source

fn clear_extension<C: ExtensionCodec>(&mut self, ext: &Extension<C>)

Remove all records at the extension’s field number.

§Panics

Panics if ext.extendee() does not match Self::PROTO_FQN.

Source

fn extension_or_default<C>(&self, ext: &Extension<C>) -> C::Value
where C: ExtensionCodec<Output = Option<<C as ExtensionCodec>::Value>>, C::Value: Default,

Read a singular extension value, returning the proto2 [default = ...] value if absent, or the type’s Default if no proto default was declared.

Only meaningful for singular codecs (Output = Option<Value>). For repeated codecs use extension — there is no such thing as a repeated default.

Presence is still distinguishable via extension (returns None) or has_extension.

§Panics

Panics if ext.extendee() does not match Self::PROTO_FQN (transitively, via the inner extension() call).

Dyn Compatibility§

This trait is not dyn compatible.

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

Implementors§