Skip to main content

TextEncoder

Struct TextEncoder 

Source
pub struct TextEncoder<'a> { /* private fields */ }
Available on crate feature text only.
Expand description

Stateful textproto writer.

Writes to any core::fmt::Write — a String, an adapter over an io::Write, etc. Holds no buffer of its own.

All write_* methods return core::fmt::Result; failure is only possible if the underlying writer fails. When writing to a String, the result is always Ok.

Implementations§

Source§

impl<'a> TextEncoder<'a>

Source

pub fn new(w: &'a mut dyn Write) -> Self

Create a single-line encoder: fields separated by spaces, no newlines.

Source

pub fn new_pretty(w: &'a mut dyn Write) -> Self

Create a multi-line encoder: one field per line, 2-space indent per nesting level.

Source

pub fn emit_unknown(self, yes: bool) -> Self

Enable printing of unknown fields (by field number). Off by default: unknowns are debug-only — the output may not roundtrip because field number and wire type aren’t enough to determine the proto type.

When off, write_unknown_fields is a no-op; generated encode_text impls call it unconditionally.

Source

pub fn write_field_name(&mut self, name: &str) -> Result

Write a field name. The next write_* call supplies the value.

Does not write a : — each write_* scalar method writes its own ": ", and write_message writes " " before the {. This is the simplest way to implement the “colon required for scalars, optional for messages” rule.

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_extension_name(&mut self, name: &str) -> Result

Write an extension field name wrapped in brackets: [pkg.ext].

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_message<M: TextFormat>(&mut self, msg: &M) -> Result

Write a nested message value: { ... } (or {} if empty).

Calls msg.encode_text(self) with depth incremented and last reset so the inner encoder starts fresh.

§Errors

Propagates core::fmt::Error from the underlying writer, or from msg.encode_text.

Source

pub fn try_write_any_expanded( &mut self, type_url: &str, value: &[u8], ) -> Result<bool, Error>

Write [type_url] { fields } when the registry has an entry for type_url or for its message full name; otherwise write nothing and return false.

true means the expanded form was written — the caller skips its vanilla type_url: "..." value: "..." fallback. false means nothing was written — the caller should fall through.

The URL is written between the brackets as given, with no escaping, so it is expanded only when it is made of ASCII letters, digits and -._~/:%. Any other URL returns false, and the caller’s quoted type_url field carries it exactly.

Consults the text-format Any map installed via set_type_registry.

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_extension_fields( &mut self, extendee: &str, fields: &UnknownFields, ) -> Result

Write registered extensions from fields as [full_name] { ... } entries: one entry per extension, or one per element for a repeated message or group extension. Unregistered field numbers are left for the caller’s write_unknown_fields (debug-only, default off).

Called by generated encode_text on messages with extension ranges. Never a no-op in the way write_unknown_fields is — extensions in text format are part of the canonical output, not debug-only.

Consults the text-format extension map installed via set_type_registry.

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_unknown_fields(&mut self, fields: &UnknownFields) -> Result

Write a message’s preserved unknown fields by field number.

No-op unless emit_unknown was set. Generated encode_text impls call this unconditionally at the end of each message, after the known fields.

Format per wire type (matches protobuf C++ TextFormat::Printer::PrintUnknownFields):

Wire typeOutputExample
varintdecimal1001: 42
fixed32 / fixed64hex1002: 0x3f800000
length-delimitednested { } if parseable, else bytes1003 { 1: 111 } or 1003: "hello"
groupnested { ... } (recursive)1004 { 1: 0 }

Length-delimited bytes are speculatively parsed as wire-format records (same heuristic as C++ text_format.cc:3121 / Java TextFormat.java:87): if the parse succeeds, print nested; otherwise print as escaped bytes. Capped at 10 levels deep. Group nesting is capped at RECURSION_LIMIT. A group nested past that depth is written with an empty body, so the text can omit a subtree, and such a group reads the same as an empty one. False positives are possible — a string that happens to look like valid wire format will be printed as { }.

This is debug output: the parser can’t round-trip it because wire type doesn’t determine proto type (a varint could be int32, sint64, bool, an enum, …).

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_i32(&mut self, v: i32) -> Result

Write an i32 value with a ": " prefix.

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_i64(&mut self, v: i64) -> Result

Write an i64 value with a ": " prefix.

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_u32(&mut self, v: u32) -> Result

Write a u32 value with a ": " prefix.

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_u64(&mut self, v: u64) -> Result

Write a u64 value with a ": " prefix.

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_f32(&mut self, v: f32) -> Result

Write an f32 value as the shortest decimal that reads back as the same f32, in positional notation (0.1, not 0.10000000149011612). NaN is nan and the infinities are inf and -inf.

Where a reader that parses an f64 and narrows it would take those digits to a neighbouring f32, the value is written with its f64 digits instead.

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_f64(&mut self, v: f64) -> Result

Write an f64 value. NaN → nan, infinities → inf/-inf.

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_bool(&mut self, v: bool) -> Result

Write a bool value: true or false.

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_string(&mut self, v: &str) -> Result

Write a string value as a quoted literal. UTF-8 codepoints pass through as-is; control characters are escaped.

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_bytes(&mut self, v: &[u8]) -> Result

Write a bytes value as a quoted literal with non-printable bytes escaped as octal \NNN.

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_enum_name(&mut self, name: &str) -> Result

Write an enum variant name as a bare identifier (no quotes).

§Errors

Propagates core::fmt::Error from the underlying writer.

Source

pub fn write_enum_number(&mut self, v: i32) -> Result

Write an enum value as its numeric i32. Fallback for unknown variants.

§Errors

Propagates core::fmt::Error from the underlying writer.

Auto Trait Implementations§

§

impl<'a> !RefUnwindSafe for TextEncoder<'a>

§

impl<'a> !Send for TextEncoder<'a>

§

impl<'a> !Sync for TextEncoder<'a>

§

impl<'a> !UnwindSafe for TextEncoder<'a>

§

impl<'a> Forget for TextEncoder<'a>

§

impl<'a> Freeze for TextEncoder<'a>

§

impl<'a> Move for TextEncoder<'a>

§

impl<'a> Unpin for TextEncoder<'a>

§

impl<'a> UnsafeUnpin for TextEncoder<'a>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.