Struct TextEncoder 

pub struct TextEncoder<'a> { /* private fields */ }

Available on crate feature text only.

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

impl<'a> TextEncoder<'a>

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

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

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.

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.

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.

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.

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.

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

Write [type_url] { fields } for a registered Any type, or do nothing and return false if the URL isn’t registered.

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.

Consults the text-format Any map installed via set_type_registry.

Errors

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

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

Write registered extensions from fields as [full_name] { ... } entries. 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.

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 type	Output	Example
varint	decimal	1001: 42
fixed32 / fixed64	hex	1002: 0x3f800000
length-delimited	nested { } if parseable, else bytes	1003 { 1: 111 } or 1003: "hello"
group	nested { ... } (recursive)	1004 { 1: 0 }

Length-delimited bytes are speculatively parsed as wire-format records (same heuristic as C++ text_format.cc:2926 / Java TextFormat.java:87): if the parse succeeds, print nested; otherwise print as escaped bytes. Capped at 10 levels deep. 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.

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.

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.

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.

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.

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

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

Errors

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

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.

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.

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.

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.

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.

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.