Skip to main content

ViewEncode

Trait ViewEncode 

Source
pub trait ViewEncode<'a>: MessageView<'a> {
Show 16 methods // Required methods fn compute_size(&self, cache: &mut SizeCache) -> u32; fn write_to(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink); // Provided methods fn encode(&self, buf: &mut impl EncodeSink) { ... } fn try_encode(&self, buf: &mut impl EncodeSink) -> Result<(), EncodeError> { ... } fn encode_with_cache( &self, cache: &mut SizeCache, buf: &mut impl EncodeSink, ) { ... } fn try_encode_with_cache( &self, cache: &mut SizeCache, buf: &mut impl EncodeSink, ) -> Result<(), EncodeError> { ... } fn try_encode_bounded( &self, max_bytes: u32, buf: &mut impl EncodeSink, ) -> Result<u32, EncodeError> { ... } fn try_encode_bounded_with_cache( &self, max_bytes: u32, cache: &mut SizeCache, buf: &mut impl EncodeSink, ) -> Result<u32, EncodeError> { ... } fn encoded_len(&self) -> u32 { ... } fn try_encoded_len(&self) -> Result<u32, EncodeError> { ... } fn encode_length_delimited(&self, buf: &mut impl EncodeSink) { ... } fn try_encode_length_delimited( &self, buf: &mut impl EncodeSink, ) -> Result<(), EncodeError> { ... } fn encode_to_vec(&self) -> Vec<u8> ⓘ { ... } fn try_encode_to_vec(&self) -> Result<Vec<u8>, EncodeError> { ... } fn encode_to_bytes(&self) -> Bytes { ... } fn try_encode_to_bytes(&self) -> Result<Bytes, EncodeError> { ... }
}
Expand description

Serialize a MessageView directly from its borrowed fields.

Symmetric with Message’s two-pass compute_size / write_to model, but the &'a str / &'a [u8] / MapView / RepeatedView fields are written by borrow — no owned-struct intermediary, no per-field String/Vec<u8> allocations.

Generated *View<'a> types implement this trait whenever views are generated (generate_views(true), the default). Serialization state lives in the external SizeCache, not the view — view structs hold no interior mutability and remain Send + Sync.

§When to use

Reach for ViewEncode when the source data is already in memory and you would otherwise allocate an owned message just to encode-then-drop it — e.g. an RPC handler serializing from app state. If you already hold the owned message, use Message::encode instead; the wire output is identical.

ⓘ
let view = PersonView {
    name: "borrowed",
    tags: ["a", "b"].iter().copied().collect(),
    ..Default::default()
};
let bytes = view.encode_to_vec();

Required Methods§

Source

fn compute_size(&self, cache: &mut SizeCache) -> u32

Compute the encoded byte size of this view, recording nested sub-message sizes in cache for write_to to consume.

Most callers should use encode instead, which runs both passes with a fresh cache.

Source

fn write_to(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink)

Write this view’s encoded bytes to a buffer, consuming nested-message sizes from cache (populated by a prior compute_size call on the same cache).

Most callers should use encode instead. This is a low-level primitive: the 2 GiB size check (MAX_MESSAGE_BYTES) lives in the provided encode entry points, so callers driving compute_size / write_to directly must validate the size themselves (via checked_encode_size).

An implementation must write exactly the number of bytes compute_size returned. The provided encode methods write a BufMut into space sized by compute_size and panic if write_to writes more; in debug builds they also panic if it writes fewer.

Provided Methods§

Source

fn encode(&self, buf: &mut impl EncodeSink)

Compute size, then write. Primary view-encode entry point.

The sink can be any BufMut (contiguous output) or a Rope; a rope constructed with with_backing on the view’s source buffer re-encodes large borrowed fields zero-copy.

§Panics

Panics if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES) — see try_encode for the error-returning variant. Also panics, when buf is a BufMut, if a manual implementation’s write_to produces more bytes than its compute_size declared, and in debug builds if it produces a different number.

Source

fn try_encode(&self, buf: &mut impl EncodeSink) -> Result<(), EncodeError>

Encode, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

On Err, nothing is written to buf.

§Errors

Returns EncodeError::MessageTooLarge if the encoded size exceeds the limit.

Source

fn encode_with_cache(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink)

Encode using a caller-supplied SizeCache, for reuse across many encodes in a hot loop. Clears the cache first.

§Panics

Panics if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES) — see try_encode_with_cache for the error-returning variant. Also panics, when buf is a BufMut, if a manual implementation’s write_to produces more bytes than its compute_size declared, and in debug builds if it produces a different number.

Source

fn try_encode_with_cache( &self, cache: &mut SizeCache, buf: &mut impl EncodeSink, ) -> Result<(), EncodeError>

Encode with a caller-supplied SizeCache, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES). Clears the cache first.

On Err, nothing is written to buf.

§Errors

Returns EncodeError::MessageTooLarge if the encoded size exceeds the limit.

Source

fn try_encode_bounded( &self, max_bytes: u32, buf: &mut impl EncodeSink, ) -> Result<u32, EncodeError>

Encode this view into buf only if its encoded size fits within max_bytes, using a single size pass that is then reused for the write.

This avoids the double tree-walk that try_encoded_len + encode would require: one compute_size pass populates the SizeCache; the budget check happens before write_to runs, so on Err nothing is written to buf.

Returns the encoded body length on success (excludes any length prefix you add for framing) — useful for metrics or frame sizing. Note that this return type is u32, unlike try_encode’s (). max_bytes is also u32; callers with a usize budget can cast with u32::try_from(budget).unwrap_or(u32::MAX).

§Errors
Source

fn try_encode_bounded_with_cache( &self, max_bytes: u32, cache: &mut SizeCache, buf: &mut impl EncodeSink, ) -> Result<u32, EncodeError>

Like try_encode_bounded but reuses an existing SizeCache, clearing it first.

Prefer SizeCachePool::try_encode_view_bounded for hot-loop use — the pool amortizes the cache’s spill allocation.

§Errors

Same as try_encode_bounded.

Source

fn encoded_len(&self) -> u32

Compute the encoded byte size of this view.

Walks the view tree, discarding the intermediate SizeCache. If you also intend to encode, prefer encode or encode_to_vec — they do a single size pass and reuse the cache for the write.

§Panics

Panics if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES) — see try_encoded_len for the error-returning variant.

Source

fn try_encoded_len(&self) -> Result<u32, EncodeError>

Compute the encoded byte size, returning an error instead of panicking if it exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

§Errors

Returns EncodeError::MessageTooLarge if the encoded size exceeds the limit.

Source

fn encode_length_delimited(&self, buf: &mut impl EncodeSink)

Encode this view as a length-delimited byte sequence.

§Panics

Panics if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES); the check runs before the length prefix is written, so nothing reaches buf on failure. See try_encode_length_delimited for the error-returning variant. Also panics, when buf is a BufMut, if a manual implementation’s write_to produces more bytes than its compute_size declared, and in debug builds if it produces a different number.

Source

fn try_encode_length_delimited( &self, buf: &mut impl EncodeSink, ) -> Result<(), EncodeError>

Encode as a length-delimited byte sequence, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

On Err, nothing is written to buf.

§Errors

Returns EncodeError::MessageTooLarge if the encoded size exceeds the limit.

Source

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

Encode this view to a new Vec<u8>.

§Panics

Panics if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES) — see try_encode_to_vec for the error-returning variant. Also panics if a manual implementation’s write_to produces more bytes than its compute_size declared, and in debug builds if it produces a different number.

Source

fn try_encode_to_vec(&self) -> Result<Vec<u8>, EncodeError>

Encode to a new Vec<u8>, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

§Errors

Returns EncodeError::MessageTooLarge if the encoded size exceeds the limit.

§Panics

Panics if a manual implementation’s write_to produces more bytes than its compute_size declared, and in debug builds if it produces a different number.

Source

fn encode_to_bytes(&self) -> Bytes

Encode this view to a new bytes::Bytes.

This is Bytes::from(self.encode_to_vec()), zero-copy for the exactly-sized vector; an implementation overriding encode_to_vec must not call this from it.

§Panics

Panics if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES) — see try_encode_to_bytes for the error-returning variant. Also panics if a manual implementation’s write_to produces more bytes than its compute_size declared, and in debug builds if it produces a different number.

Source

fn try_encode_to_bytes(&self) -> Result<Bytes, EncodeError>

Encode to a new bytes::Bytes, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

§Errors

Returns EncodeError::MessageTooLarge if the encoded size exceeds the limit.

§Panics

Panics if a manual implementation’s write_to produces more bytes than its compute_size declared, and in debug builds if it produces a different number.

Dyn Compatibility§

This trait is not dyn compatible.

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

Implementors§