pub struct TextEncoder<'a> { /* private fields */ }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>
impl<'a> TextEncoder<'a>
Sourcepub fn new(w: &'a mut dyn Write) -> Self
pub fn new(w: &'a mut dyn Write) -> Self
Create a single-line encoder: fields separated by spaces, no newlines.
Sourcepub fn new_pretty(w: &'a mut dyn Write) -> Self
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.
Sourcepub fn emit_unknown(self, yes: bool) -> Self
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.
Sourcepub fn write_field_name(&mut self, name: &str) -> Result
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.
Sourcepub fn write_extension_name(&mut self, name: &str) -> Result
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.
Sourcepub fn write_message<M: TextFormat>(&mut self, msg: &M) -> Result
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.
Sourcepub fn try_write_any_expanded(
&mut self,
type_url: &str,
value: &[u8],
) -> Result<bool, Error>
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.
Sourcepub fn write_extension_fields(
&mut self,
extendee: &str,
fields: &UnknownFields,
) -> Result
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.
Sourcepub fn write_unknown_fields(&mut self, fields: &UnknownFields) -> Result
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: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.
Sourcepub fn write_i32(&mut self, v: i32) -> Result
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.
Sourcepub fn write_i64(&mut self, v: i64) -> Result
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.
Sourcepub fn write_u32(&mut self, v: u32) -> Result
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.
Sourcepub fn write_u64(&mut self, v: u64) -> Result
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.
Sourcepub fn write_f32(&mut self, v: f32) -> Result
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.
Sourcepub fn write_f64(&mut self, v: f64) -> Result
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.
Sourcepub fn write_bool(&mut self, v: bool) -> Result
pub fn write_bool(&mut self, v: bool) -> Result
Sourcepub fn write_string(&mut self, v: &str) -> Result
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.
Sourcepub fn write_bytes(&mut self, v: &[u8]) -> Result
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.
Sourcepub fn write_enum_name(&mut self, name: &str) -> Result
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.
Sourcepub fn write_enum_number(&mut self, v: i32) -> Result
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.