buffa/text/encoder.rs
1//! Textproto encoder.
2//!
3//! A thin wrapper around a [`core::fmt::Write`] sink that emits fields in
4//! textproto syntax. Generated `encode_text` implementations call
5//! [`write_field_name`](TextEncoder::write_field_name) followed by exactly one
6//! `write_*` value method per field; the encoder tracks whether to emit a `:`
7//! (scalars) or ` ` (messages) between them, and handles indentation in
8//! pretty mode.
9//!
10//! Output uses `{` `}` for message delimiters. Single-line mode separates
11//! fields with a single space; pretty mode puts each field on its own line
12//! indented by two spaces per nesting level.
13
14use core::fmt::Write;
15
16use super::string::{escape_bytes, escape_str};
17use crate::type_registry::MAX_ANY_EXPANSION_DEPTH;
18use crate::unknown_fields::{UnknownFieldData, UnknownFields};
19
20/// Depth cap for heuristically parsing length-delimited unknown fields as
21/// nested messages. Matches C++ `kUnknownFieldRecursionLimit`
22/// (text_format.cc:2494). Independent of the parse-time [`RECURSION_LIMIT`]
23/// — this bounds an encode-time *printing* heuristic, not wire decode.
24///
25/// [`RECURSION_LIMIT`]: crate::RECURSION_LIMIT
26const UNKNOWN_LD_RECURSE_BUDGET: u32 = 10;
27
28/// Maximum group nesting the unknown-field printer will traverse. Decoded
29/// groups already respect this limit; public `UnknownFields::push` can also
30/// construct deeper trees directly.
31const UNKNOWN_GROUP_RECURSE_BUDGET: u32 = crate::RECURSION_LIMIT;
32
33/// What the encoder last emitted — drives separator logic in
34/// [`prepare`](TextEncoder::prepare).
35#[derive(Clone, Copy, PartialEq, Eq)]
36enum Last {
37 /// Nothing yet, or just after an open brace.
38 Open,
39 /// A field name. Next write is the value.
40 Name,
41 /// A scalar value or a close brace. Next write starts a new field.
42 Value,
43}
44
45/// Stateful textproto writer.
46///
47/// Writes to any [`core::fmt::Write`] — a `String`, an adapter over an
48/// `io::Write`, etc. Holds no buffer of its own.
49///
50/// All `write_*` methods return [`core::fmt::Result`]; failure is only
51/// possible if the underlying writer fails. When writing to a `String`, the
52/// result is always `Ok`.
53pub struct TextEncoder<'a> {
54 w: &'a mut dyn Write,
55 depth: u32,
56 /// Nesting depth of `Any` expansions on the current path, bounded by
57 /// [`MAX_ANY_EXPANSION_DEPTH`]. Separate from `depth`, which counts
58 /// textproto braces for indentation and is not a bound.
59 any_depth: u32,
60 pretty: bool,
61 emit_unknown: bool,
62 last: Last,
63 /// The extension name that
64 /// [`write_extension_fields`](Self::write_extension_fields) wrote. It is
65 /// set only while that entry's `text_encode` runs and the name is still
66 /// the last thing written: the next write clears it, and so does the
67 /// return of `text_encode`.
68 /// [`write_repeated_extension`](Self::write_repeated_extension) writes it
69 /// again before each element after the first.
70 ext_name: Option<&'static str>,
71}
72
73impl<'a> TextEncoder<'a> {
74 /// Create a single-line encoder: fields separated by spaces, no newlines.
75 pub fn new(w: &'a mut dyn Write) -> Self {
76 Self {
77 w,
78 depth: 0,
79 any_depth: 0,
80 pretty: false,
81 emit_unknown: false,
82 last: Last::Open,
83 ext_name: None,
84 }
85 }
86
87 /// Create a multi-line encoder: one field per line, 2-space indent per
88 /// nesting level.
89 pub fn new_pretty(w: &'a mut dyn Write) -> Self {
90 Self {
91 w,
92 depth: 0,
93 any_depth: 0,
94 pretty: true,
95 emit_unknown: false,
96 last: Last::Open,
97 ext_name: None,
98 }
99 }
100
101 /// Enable printing of unknown fields (by field number). Off by default:
102 /// unknowns are debug-only — the output may not roundtrip because field
103 /// number and wire type aren't enough to determine the proto type.
104 ///
105 /// When off, [`write_unknown_fields`](Self::write_unknown_fields) is a
106 /// no-op; generated `encode_text` impls call it unconditionally.
107 #[must_use]
108 pub fn emit_unknown(mut self, yes: bool) -> Self {
109 self.emit_unknown = yes;
110 self
111 }
112
113 /// Emit inter-token separator and indentation appropriate for the last
114 /// thing written and the next thing about to be written.
115 ///
116 /// Reference: protobuf-go `encode.go` `prepareNext`.
117 fn prepare(&mut self, next: Last) -> core::fmt::Result {
118 let prev = self.last;
119 self.last = next;
120 self.ext_name = None;
121 if !self.pretty {
122 // Single line: space between end-of-field and start of next name.
123 if prev == Last::Value && next == Last::Name {
124 self.w.write_char(' ')?;
125 }
126 return Ok(());
127 }
128 // Multi-line.
129 match (prev, next) {
130 (Last::Name, _) => {
131 // Nothing: each scalar write_* emits `": "` and write_message
132 // emits a space itself. Avoid doubling up.
133 }
134 (Last::Open, Last::Name) => {
135 // First field after an open brace. At top level (depth 0) the
136 // "open" is virtual — no brace was written — so no newline.
137 if self.depth > 0 {
138 self.w.write_char('\n')?;
139 self.write_indent()?;
140 }
141 }
142 (Last::Value, Last::Name) | (Last::Value, Last::Value) => {
143 // Next field, or close brace dedenting below its contents.
144 self.w.write_char('\n')?;
145 self.write_indent()?;
146 }
147 (Last::Open, Last::Value) | (Last::Open, Last::Open) | (Last::Value, Last::Open) => {
148 // Empty message body (`{}`) or nothing to separate.
149 }
150 }
151 Ok(())
152 }
153
154 fn write_indent(&mut self) -> core::fmt::Result {
155 for _ in 0..self.depth {
156 self.w.write_str(" ")?;
157 }
158 Ok(())
159 }
160
161 /// Write a field name. The next `write_*` call supplies the value.
162 ///
163 /// Does **not** write a `:` — each `write_*` scalar method writes its own
164 /// `": "`, and `write_message` writes `" "` before the `{`. This is the
165 /// simplest way to implement the "colon required for scalars, optional
166 /// for messages" rule.
167 ///
168 /// # Errors
169 ///
170 /// Propagates [`core::fmt::Error`] from the underlying writer.
171 pub fn write_field_name(&mut self, name: &str) -> core::fmt::Result {
172 self.prepare(Last::Name)?;
173 self.w.write_str(name)
174 }
175
176 /// Write an extension field name wrapped in brackets: `[pkg.ext]`.
177 ///
178 /// # Errors
179 ///
180 /// Propagates [`core::fmt::Error`] from the underlying writer.
181 pub fn write_extension_name(&mut self, name: &str) -> core::fmt::Result {
182 self.prepare(Last::Name)?;
183 self.w.write_char('[')?;
184 self.w.write_str(name)?;
185 self.w.write_char(']')
186 }
187
188 /// Write a nested message value: `{ ... }` (or `{}` if empty).
189 ///
190 /// Calls `msg.encode_text(self)` with `depth` incremented and `last`
191 /// reset so the inner encoder starts fresh.
192 ///
193 /// # Errors
194 ///
195 /// Propagates [`core::fmt::Error`] from the underlying writer, or from
196 /// `msg.encode_text`.
197 pub fn write_message<M: super::TextFormat>(&mut self, msg: &M) -> core::fmt::Result {
198 self.write_map_entry(|enc| msg.encode_text(enc))
199 }
200
201 /// Write a `{ ... }` block via a closure instead of a [`TextFormat`] impl.
202 ///
203 /// Exists so generated map-entry encoding doesn't need a full
204 /// [`Message`](crate::Message) type per `map<K, V>` field. [`TextFormat`]
205 /// has a `Message` supertrait bound, and `Message` requires `Default +
206 /// 'static + Clone + PartialEq + Send + Sync` — bounds that a
207 /// closure-over-references adapter can't satisfy. Taking a closure
208 /// directly here sidesteps the bound entirely.
209 ///
210 /// `#[doc(hidden)]` — codegen support, not public API.
211 ///
212 /// # Errors
213 ///
214 /// Propagates [`core::fmt::Error`] from the underlying writer or from `f`.
215 #[doc(hidden)]
216 pub fn write_map_entry(
217 &mut self,
218 f: impl FnOnce(&mut Self) -> core::fmt::Result,
219 ) -> core::fmt::Result {
220 // No `:` before a message value — just a space before `{`.
221 self.prepare(Last::Value)?;
222 self.w.write_char(' ')?;
223 self.write_message_body(f)
224 }
225
226 /// Write the elements of a repeated message or group extension, after
227 /// the caller has written the extension's bracketed name once.
228 ///
229 /// The two forms are documented on
230 /// [`repeated_message_encode_text`](crate::type_registry::repeated_message_encode_text).
231 /// The per-element form is preferred because a parser reads it without
232 /// support for message lists.
233 pub(crate) fn write_repeated_extension<M: super::TextFormat>(
234 &mut self,
235 messages: &[M],
236 ) -> core::fmt::Result {
237 debug_assert!(self.ext_name.is_none() || self.last == Last::Name);
238 match (self.ext_name, messages) {
239 (Some(name), [first, rest @ ..]) => {
240 self.write_message(first)?;
241 for message in rest {
242 self.write_extension_name(name)?;
243 self.write_message(message)?;
244 }
245 Ok(())
246 }
247 (None, _) | (Some(_), []) => self.write_message_list(messages),
248 }
249 }
250
251 fn write_message_list<M: super::TextFormat>(&mut self, messages: &[M]) -> core::fmt::Result {
252 self.prepare(Last::Value)?;
253 self.w.write_str(": [")?;
254 for (index, message) in messages.iter().enumerate() {
255 if index > 0 {
256 self.w.write_str(", ")?;
257 }
258 self.write_message_body(|enc| message.encode_text(enc))?;
259 }
260 self.w.write_char(']')
261 }
262
263 fn write_message_body(
264 &mut self,
265 f: impl FnOnce(&mut Self) -> core::fmt::Result,
266 ) -> core::fmt::Result {
267 self.w.write_char('{')?;
268 self.depth += 1;
269 let outer_last = self.last;
270 self.last = Last::Open;
271 f(self)?;
272 // Close brace: dedent first.
273 self.depth -= 1;
274 if self.pretty && self.last != Last::Open {
275 self.w.write_char('\n')?;
276 self.write_indent()?;
277 }
278 self.last = outer_last;
279 self.w.write_char('}')
280 }
281
282 /// Write `[type_url] { fields }` when the registry has an entry for
283 /// `type_url` or for its message full name; otherwise write nothing and
284 /// return `false`.
285 ///
286 /// `true` means the expanded form was written — the caller skips its
287 /// vanilla `type_url: "..." value: "..."` fallback. `false` means
288 /// nothing was written — the caller should fall through.
289 ///
290 /// The URL is written between the brackets as given, with no escaping,
291 /// so it is expanded only when it is made of ASCII letters, digits and
292 /// `-._~/:%`. Any other URL returns `false`, and the caller's quoted
293 /// `type_url` field carries it exactly.
294 ///
295 /// Consults the text-format `Any` map installed via
296 /// [`set_type_registry`](crate::type_registry::set_type_registry).
297 ///
298 /// # Errors
299 ///
300 /// Propagates [`core::fmt::Error`] from the underlying writer.
301 pub fn try_write_any_expanded(
302 &mut self,
303 type_url: &str,
304 value: &[u8],
305 ) -> Result<bool, core::fmt::Error> {
306 // `type_url` is input data: a URL with any prefix resolves by its
307 // message name. A `]` would end the bracketed name early and let the
308 // rest of the URL be read as further fields, and whitespace or `#`
309 // would not survive the trip back through the decoder.
310 if !type_url.bytes().all(is_bracket_safe_url_byte) {
311 return Ok(false);
312 }
313 let Some(entry) = crate::type_registry::global_text_any(type_url) else {
314 return Ok(false);
315 };
316 // An `Any` whose payload is another `Any` re-enters here through the
317 // registered encoder. Past the cap, fall back to the vanilla
318 // `type_url`/`value` form: still valid textproto, and finite.
319 if self.any_depth >= MAX_ANY_EXPANSION_DEPTH {
320 return Ok(false);
321 }
322 self.write_extension_name(type_url)?;
323 self.any_depth += 1;
324 let r = (entry.text_encode)(value, self);
325 self.any_depth -= 1;
326 r?;
327 Ok(true)
328 }
329
330 /// Write registered extensions from `fields` as `[full_name] { ... }`
331 /// entries: one entry per extension, or one per element for a repeated
332 /// message or group extension.
333 /// Unregistered field numbers are left for the caller's
334 /// [`write_unknown_fields`](Self::write_unknown_fields) (debug-only,
335 /// default off).
336 ///
337 /// Called by generated `encode_text` on messages with extension ranges.
338 /// Never a no-op in the way `write_unknown_fields` is — extensions in
339 /// text format are part of the canonical output, not debug-only.
340 ///
341 /// Consults the text-format extension map installed via
342 /// [`set_type_registry`](crate::type_registry::set_type_registry).
343 ///
344 /// # Errors
345 ///
346 /// Propagates [`core::fmt::Error`] from the underlying writer.
347 pub fn write_extension_fields(
348 &mut self,
349 extendee: &str,
350 fields: &UnknownFields,
351 ) -> core::fmt::Result {
352 if fields.is_empty() {
353 return Ok(());
354 }
355 // One `text_encode` call per field number: the entry reads every
356 // record at that number. Mirrors JSON's `serialize_extensions` dedup
357 // loop.
358 let mut seen = alloc::collections::BTreeSet::new();
359 for uf in fields.iter() {
360 if !seen.insert(uf.number) {
361 continue;
362 }
363 let Some(entry) = crate::type_registry::global_text_ext_by_number(extendee, uf.number)
364 else {
365 continue;
366 };
367 self.write_extension_name(entry.full_name)?;
368 self.ext_name = Some(entry.full_name);
369 (entry.text_encode)(uf.number, fields, self)?;
370 self.ext_name = None;
371 }
372 Ok(())
373 }
374
375 /// Write a message's preserved unknown fields by field number.
376 ///
377 /// No-op unless [`emit_unknown`](Self::emit_unknown) was set. Generated
378 /// `encode_text` impls call this unconditionally at the end of each
379 /// message, after the known fields.
380 ///
381 /// Format per wire type (matches protobuf C++ `TextFormat::Printer::PrintUnknownFields`):
382 ///
383 /// | Wire type | Output | Example |
384 /// |---|---|---|
385 /// | varint | decimal | `1001: 42` |
386 /// | fixed32 / fixed64 | hex | `1002: 0x3f800000` |
387 /// | length-delimited | nested `{ }` if parseable, else bytes | `1003 { 1: 111 }` or `1003: "hello"` |
388 /// | group | nested `{ ... }` (recursive) | `1004 { 1: 0 }` |
389 ///
390 /// Length-delimited bytes are speculatively parsed as wire-format records
391 /// (same heuristic as C++ text_format.cc:3121 / Java TextFormat.java:87):
392 /// if the parse succeeds, print nested; otherwise print as escaped bytes.
393 /// Capped at 10 levels deep. Group nesting is capped at
394 /// [`RECURSION_LIMIT`](crate::RECURSION_LIMIT). A group nested past that
395 /// depth is written with an empty body, so the text can omit a subtree,
396 /// and such a group reads the same as an empty one. False positives are
397 /// possible — a string that happens to look like valid wire format will be
398 /// printed as `{ }`.
399 ///
400 /// This is debug output: the parser can't round-trip it because wire type
401 /// doesn't determine proto type (a varint could be int32, sint64, bool, an
402 /// enum, …).
403 ///
404 /// # Errors
405 ///
406 /// Propagates [`core::fmt::Error`] from the underlying writer.
407 pub fn write_unknown_fields(&mut self, fields: &UnknownFields) -> core::fmt::Result {
408 if !self.emit_unknown {
409 return Ok(());
410 }
411 self.write_unknown_inner(
412 fields,
413 UNKNOWN_LD_RECURSE_BUDGET,
414 UNKNOWN_GROUP_RECURSE_BUDGET,
415 )
416 }
417
418 fn write_unknown_inner(
419 &mut self,
420 fields: &UnknownFields,
421 ld_budget: u32,
422 group_budget: u32,
423 ) -> core::fmt::Result {
424 for f in fields.iter() {
425 self.prepare(Last::Name)?;
426 write!(self.w, "{}", f.number)?;
427 match &f.data {
428 UnknownFieldData::Varint(v) => {
429 self.prepare(Last::Value)?;
430 write!(self.w, ": {v}")?;
431 }
432 UnknownFieldData::Fixed32(v) => {
433 self.prepare(Last::Value)?;
434 write!(self.w, ": 0x{v:x}")?;
435 }
436 UnknownFieldData::Fixed64(v) => {
437 self.prepare(Last::Value)?;
438 write!(self.w, ": 0x{v:x}")?;
439 }
440 UnknownFieldData::LengthDelimited(bytes) => {
441 // Heuristic: try to parse the bytes as wire-format records.
442 // If it parses, it's probably a sub-message — print nested.
443 // If not (or we're out of budget), print as escaped bytes.
444 // Matches C++ text_format.cc:3121-3160 and Java
445 // TextFormat.java:87-102.
446 if ld_budget > 0 && !bytes.is_empty() {
447 if let Ok(inner) = UnknownFields::decode_from_slice(bytes) {
448 self.write_map_entry(|enc| {
449 enc.write_unknown_inner(&inner, ld_budget - 1, group_budget)
450 })?;
451 continue;
452 }
453 }
454 self.prepare(Last::Value)?;
455 self.w.write_str(": ")?;
456 escape_bytes(bytes, self.w)?;
457 }
458 UnknownFieldData::Group(inner) => {
459 // Limit public, manually constructed groups as well as
460 // groups that came through the bounded decoder.
461 self.write_map_entry(|enc| {
462 if group_budget == 0 {
463 Ok(())
464 } else {
465 enc.write_unknown_inner(inner, ld_budget, group_budget - 1)
466 }
467 })?;
468 }
469 }
470 }
471 Ok(())
472 }
473
474 // ── scalar writers ──────────────────────────────────────────────────────
475
476 /// Write an `i32` value with a `": "` prefix.
477 ///
478 /// # Errors
479 ///
480 /// Propagates [`core::fmt::Error`] from the underlying writer.
481 pub fn write_i32(&mut self, v: i32) -> core::fmt::Result {
482 self.prepare(Last::Value)?;
483 write!(self.w, ": {v}")
484 }
485
486 /// Write an `i64` value with a `": "` prefix.
487 ///
488 /// # Errors
489 ///
490 /// Propagates [`core::fmt::Error`] from the underlying writer.
491 pub fn write_i64(&mut self, v: i64) -> core::fmt::Result {
492 self.prepare(Last::Value)?;
493 write!(self.w, ": {v}")
494 }
495
496 /// Write a `u32` value with a `": "` prefix.
497 ///
498 /// # Errors
499 ///
500 /// Propagates [`core::fmt::Error`] from the underlying writer.
501 pub fn write_u32(&mut self, v: u32) -> core::fmt::Result {
502 self.prepare(Last::Value)?;
503 write!(self.w, ": {v}")
504 }
505
506 /// Write a `u64` value with a `": "` prefix.
507 ///
508 /// # Errors
509 ///
510 /// Propagates [`core::fmt::Error`] from the underlying writer.
511 pub fn write_u64(&mut self, v: u64) -> core::fmt::Result {
512 self.prepare(Last::Value)?;
513 write!(self.w, ": {v}")
514 }
515
516 /// Write an `f32` value as the shortest decimal that reads back as the
517 /// same `f32`, in positional notation (`0.1`, not `0.10000000149011612`).
518 /// NaN is `nan` and the infinities are `inf` and `-inf`.
519 ///
520 /// Where a reader that parses an `f64` and narrows it would take those
521 /// digits to a neighbouring `f32`, the value is written with its `f64`
522 /// digits instead.
523 ///
524 /// # Errors
525 ///
526 /// Propagates [`core::fmt::Error`] from the underlying writer.
527 pub fn write_f32(&mut self, v: f32) -> core::fmt::Result {
528 self.prepare(Last::Value)?;
529 self.w.write_str(": ")?;
530 if v.is_finite() {
531 let mut digits = F32Digits::new();
532 if write!(digits, "{v}").is_ok() {
533 // A reader that parses a `float` as an `f64` and narrows it,
534 // as protobuf C++ and protobuf-go do, rounds twice. For two
535 // values, ±7.038531e-26, that takes the shortest `f32` digits
536 // one ulp away from `v`. They get the widened digits, which
537 // every reader takes back to `v`.
538 if let Some(short) = digits.as_str().filter(|s| narrows_to(s, v)) {
539 return self.w.write_str(short);
540 }
541 }
542 }
543 write_float(self.w, f64::from(v))
544 }
545
546 /// Write an `f64` value. NaN → `nan`, infinities → `inf`/`-inf`.
547 ///
548 /// # Errors
549 ///
550 /// Propagates [`core::fmt::Error`] from the underlying writer.
551 pub fn write_f64(&mut self, v: f64) -> core::fmt::Result {
552 self.prepare(Last::Value)?;
553 self.w.write_str(": ")?;
554 write_float(self.w, v)
555 }
556
557 /// Write a `bool` value: `true` or `false`.
558 ///
559 /// # Errors
560 ///
561 /// Propagates [`core::fmt::Error`] from the underlying writer.
562 pub fn write_bool(&mut self, v: bool) -> core::fmt::Result {
563 self.prepare(Last::Value)?;
564 self.w.write_str(if v { ": true" } else { ": false" })
565 }
566
567 /// Write a `string` value as a quoted literal. UTF-8 codepoints pass
568 /// through as-is; control characters are escaped.
569 ///
570 /// # Errors
571 ///
572 /// Propagates [`core::fmt::Error`] from the underlying writer.
573 pub fn write_string(&mut self, v: &str) -> core::fmt::Result {
574 self.prepare(Last::Value)?;
575 self.w.write_str(": ")?;
576 escape_str(v, self.w)
577 }
578
579 /// Write a `bytes` value as a quoted literal with non-printable bytes
580 /// escaped as octal `\NNN`.
581 ///
582 /// # Errors
583 ///
584 /// Propagates [`core::fmt::Error`] from the underlying writer.
585 pub fn write_bytes(&mut self, v: &[u8]) -> core::fmt::Result {
586 self.prepare(Last::Value)?;
587 self.w.write_str(": ")?;
588 escape_bytes(v, self.w)
589 }
590
591 /// Write an enum variant name as a bare identifier (no quotes).
592 ///
593 /// # Errors
594 ///
595 /// Propagates [`core::fmt::Error`] from the underlying writer.
596 pub fn write_enum_name(&mut self, name: &str) -> core::fmt::Result {
597 self.prepare(Last::Value)?;
598 self.w.write_str(": ")?;
599 self.w.write_str(name)
600 }
601
602 /// Write an enum value as its numeric `i32`. Fallback for unknown
603 /// variants.
604 ///
605 /// # Errors
606 ///
607 /// Propagates [`core::fmt::Error`] from the underlying writer.
608 pub fn write_enum_number(&mut self, v: i32) -> core::fmt::Result {
609 self.write_i32(v)
610 }
611}
612
613/// The `Display` text of one finite `f32`, held on the stack.
614struct F32Digits {
615 buf: [u8; Self::CAPACITY],
616 len: usize,
617}
618
619impl F32Digits {
620 /// Buffer length in bytes. A finite `f32` prints as at most 48 bytes (a
621 /// sign and `0.` before 45 decimal places, for example the negative
622 /// subnormal nearest zero), so 64 leaves a margin. A longer text fails
623 /// the write, and `write_f32` then prints the `f64` digits.
624 const CAPACITY: usize = 64;
625
626 const fn new() -> Self {
627 Self {
628 buf: [0; Self::CAPACITY],
629 len: 0,
630 }
631 }
632
633 fn as_str(&self) -> Option<&str> {
634 core::str::from_utf8(self.buf.get(..self.len)?).ok()
635 }
636}
637
638impl Write for F32Digits {
639 fn write_str(&mut self, s: &str) -> core::fmt::Result {
640 let end = self.len + s.len();
641 let dst = self.buf.get_mut(self.len..end).ok_or(core::fmt::Error)?;
642 dst.copy_from_slice(s.as_bytes());
643 self.len = end;
644 Ok(())
645 }
646}
647
648/// Whether `digits`, parsed as an `f64` and narrowed, is exactly `v`.
649fn narrows_to(digits: &str, v: f32) -> bool {
650 digits
651 .parse::<f64>()
652 .is_ok_and(|wide| (wide as f32).to_bits() == v.to_bits())
653}
654
655/// Write a float with textproto conventions for non-finites.
656fn write_float(w: &mut dyn Write, v: f64) -> core::fmt::Result {
657 if v.is_nan() {
658 w.write_str("nan")
659 } else if v.is_infinite() {
660 if v > 0.0 {
661 w.write_str("inf")
662 } else {
663 w.write_str("-inf")
664 }
665 } else {
666 // Rust's default float Display uses the shortest round-trip
667 // representation, which is what we want here.
668 write!(w, "{v}")
669 }
670}
671
672/// Whether `b` can stand in a type URL written between brackets and be read
673/// back unchanged: an ASCII letter or digit, or one of `-._~/:%`.
674fn is_bracket_safe_url_byte(b: u8) -> bool {
675 b.is_ascii_alphanumeric() || matches!(b, b'-' | b'.' | b'_' | b'~' | b'/' | b':' | b'%')
676}
677
678#[cfg(test)]
679mod tests {
680 use super::*;
681 use alloc::string::String;
682
683 #[test]
684 fn bracket_safe_url_bytes() {
685 let safe = "type.googleapis.com/pkg.Msg_1~-:%";
686 assert!(safe.bytes().all(is_bracket_safe_url_byte));
687 for unsafe_byte in *b"[]{}#\"' \t\n\\<>," {
688 assert!(!is_bracket_safe_url_byte(unsafe_byte), "{unsafe_byte:#04x}");
689 }
690 assert!(!"é".bytes().any(is_bracket_safe_url_byte));
691 }
692
693 #[test]
694 fn single_line_scalars() {
695 let mut s = String::new();
696 let mut enc = TextEncoder::new(&mut s);
697 enc.write_field_name("a").unwrap();
698 enc.write_i32(42).unwrap();
699 enc.write_field_name("b").unwrap();
700 enc.write_string("hello").unwrap();
701 assert_eq!(s, r#"a: 42 b: "hello""#);
702 }
703
704 #[test]
705 fn pretty_scalars() {
706 let mut s = String::new();
707 let mut enc = TextEncoder::new_pretty(&mut s);
708 enc.write_field_name("a").unwrap();
709 enc.write_i32(42).unwrap();
710 enc.write_field_name("b").unwrap();
711 enc.write_i32(7).unwrap();
712 assert_eq!(s, "a: 42\nb: 7");
713 }
714
715 #[test]
716 fn all_scalar_types() {
717 #[rustfmt::skip]
718 let cases: &[(&str, &str)] = &[
719 ("i32", "f: -7"),
720 ("i64", "f: 9000000000"),
721 ("u32", "f: 42"),
722 ("u64", "f: 18000000000000000000"),
723 ("bool", "f: true"),
724 ("str", r#"f: "hi""#),
725 ("bytes", r#"f: "\377""#),
726 ("enum", "f: FOO_BAR"),
727 ];
728 for &(which, want) in cases {
729 let mut s = String::new();
730 let mut enc = TextEncoder::new(&mut s);
731 enc.write_field_name("f").unwrap();
732 match which {
733 "i32" => enc.write_i32(-7).unwrap(),
734 "i64" => enc.write_i64(9_000_000_000).unwrap(),
735 "u32" => enc.write_u32(42).unwrap(),
736 "u64" => enc.write_u64(18_000_000_000_000_000_000).unwrap(),
737 "bool" => enc.write_bool(true).unwrap(),
738 "str" => enc.write_string("hi").unwrap(),
739 "bytes" => enc.write_bytes(&[0xFF]).unwrap(),
740 "enum" => enc.write_enum_name("FOO_BAR").unwrap(),
741 _ => unreachable!(),
742 }
743 assert_eq!(s, want, "type: {which}");
744 }
745 }
746
747 #[test]
748 fn float_specials() {
749 #[rustfmt::skip]
750 let cases: &[(f64, &str)] = &[
751 (1.5, "f: 1.5"),
752 (0.0, "f: 0"),
753 (f64::NAN, "f: nan"),
754 (f64::INFINITY, "f: inf"),
755 (f64::NEG_INFINITY, "f: -inf"),
756 ];
757 for &(v, want) in cases {
758 let mut s = String::new();
759 let mut enc = TextEncoder::new(&mut s);
760 enc.write_field_name("f").unwrap();
761 enc.write_f64(v).unwrap();
762 assert_eq!(s, want, "value: {v}");
763 }
764 }
765
766 fn f32_text(v: f32) -> String {
767 let mut s = String::new();
768 let mut enc = TextEncoder::new(&mut s);
769 enc.write_field_name("f").unwrap();
770 enc.write_f32(v).unwrap();
771 s
772 }
773
774 #[test]
775 fn f32_uses_its_own_shortest_digits() {
776 #[rustfmt::skip]
777 let cases: &[(f32, &str)] = &[
778 (0.1, "f: 0.1"),
779 (-2.2, "f: -2.2"),
780 (1.5, "f: 1.5"),
781 (-0.0, "f: -0"),
782 // Nine significant digits, the most an `f32` needs.
783 (10.000_010_5, "f: 10.0000105"),
784 (f32::MAX, "f: 340282350000000000000000000000000000000"),
785 (f32::NAN, "f: nan"),
786 (f32::NEG_INFINITY, "f: -inf"),
787 ];
788 for &(v, want) in cases {
789 assert_eq!(f32_text(v), want, "value: {v}");
790 }
791 }
792
793 #[test]
794 fn f32_digits_hold_the_longest_values() {
795 // No `f32` is longer than the negative subnormal nearest zero, 48
796 // bytes. A value that outgrew the buffer would print its widened
797 // digits.
798 for v in [
799 -f32::from_bits(1),
800 -f32::MIN_POSITIVE,
801 f32::MIN,
802 -f32::from_bits(0x007f_ffff),
803 ] {
804 let short = alloc::format!("{v}");
805 assert!(short.len() <= F32Digits::CAPACITY, "value: {v}");
806 assert_eq!(f32_text(v), alloc::format!("f: {short}"), "value: {v}");
807 }
808 assert_eq!(alloc::format!("{}", -f32::from_bits(1)).len(), 48);
809 }
810
811 #[test]
812 fn f32_digits_reject_text_past_the_capacity() {
813 let mut digits = F32Digits::new();
814 for _ in 0..F32Digits::CAPACITY {
815 digits.write_str("1").unwrap();
816 }
817 assert!(digits.write_str("1").is_err());
818 assert_eq!(digits.as_str().map(str::len), Some(F32Digits::CAPACITY));
819 }
820
821 #[test]
822 fn f32_keeps_widened_digits_where_a_narrowing_reader_would_miss() {
823 // The shortest digits of this value are `7.038531e-26`. Read as an
824 // `f64` and narrowed, they give its neighbour 0x15ae_43fe.
825 // `f32_fallback_values_exhaustive` shows that this value and its
826 // negation are the only ones.
827 for v in [f32::from_bits(0x15ae_43fd), -f32::from_bits(0x15ae_43fd)] {
828 let short = alloc::format!("{v}");
829 assert!(!narrows_to(&short, v));
830
831 let text = f32_text(v);
832 let digits = text.strip_prefix("f: ").unwrap();
833 assert_ne!(digits, short);
834 assert_eq!(digits, alloc::format!("{}", f64::from(v)));
835 // Both kinds of reader take the widened digits back to `v`.
836 assert!(narrows_to(digits, v));
837 assert_eq!(digits.parse::<f32>().unwrap().to_bits(), v.to_bits());
838 }
839 }
840
841 #[test]
842 #[ignore = "visits every f32; run with --release"]
843 fn f32_fallback_values_exhaustive() {
844 let mut fallbacks = alloc::vec::Vec::new();
845 for bits in 0..=u32::MAX {
846 let v = f32::from_bits(bits);
847 if !v.is_finite() {
848 continue;
849 }
850 let mut digits = F32Digits::new();
851 write!(digits, "{v}").unwrap();
852 let short = digits.as_str().unwrap();
853 assert_eq!(short.parse::<f32>().unwrap().to_bits(), bits);
854 if !narrows_to(short, v) {
855 fallbacks.push(bits);
856 }
857 }
858 assert_eq!(fallbacks, [0x15ae_43fd, 0x95ae_43fd]);
859 }
860
861 #[test]
862 fn extension_name() {
863 let mut s = String::new();
864 let mut enc = TextEncoder::new(&mut s);
865 enc.write_extension_name("pkg.ext").unwrap();
866 enc.write_i32(1).unwrap();
867 assert_eq!(s, "[pkg.ext]: 1");
868 }
869
870 // write_message is exercised by the integration tests in decoder.rs,
871 // which need a TextFormat-implementing struct.
872
873 #[test]
874 fn unknown_fields_default_noop() {
875 use crate::unknown_fields::UnknownField;
876 let mut fields = UnknownFields::new();
877 fields.push(UnknownField {
878 number: 1001,
879 data: UnknownFieldData::Varint(42),
880 });
881
882 let mut s = String::new();
883 let mut enc = TextEncoder::new(&mut s);
884 enc.write_unknown_fields(&fields).unwrap();
885 assert_eq!(s, ""); // emit_unknown off → nothing
886 }
887
888 #[test]
889 fn unknown_fields_all_wire_types() {
890 use crate::unknown_fields::UnknownField;
891 use alloc::vec;
892 let mut group_inner = UnknownFields::new();
893 group_inner.push(UnknownField {
894 number: 1,
895 data: UnknownFieldData::Varint(7),
896 });
897
898 let mut fields = UnknownFields::new();
899 fields.push(UnknownField {
900 number: 1001,
901 data: UnknownFieldData::Varint(42),
902 });
903 fields.push(UnknownField {
904 number: 1002,
905 data: UnknownFieldData::Fixed32(0x3F80_0000),
906 });
907 fields.push(UnknownField {
908 number: 1003,
909 data: UnknownFieldData::Fixed64(0xDEAD_BEEF),
910 });
911 fields.push(UnknownField {
912 number: 1004,
913 data: UnknownFieldData::LengthDelimited(vec![0x01, 0xFF]),
914 });
915 fields.push(UnknownField {
916 number: 1005,
917 data: UnknownFieldData::Group(group_inner),
918 });
919
920 let mut s = String::new();
921 let mut enc = TextEncoder::new(&mut s).emit_unknown(true);
922 enc.write_unknown_fields(&fields).unwrap();
923 assert_eq!(
924 s,
925 r#"1001: 42 1002: 0x3f800000 1003: 0xdeadbeef 1004: "\001\377" 1005 {1: 7}"#
926 );
927 }
928
929 #[test]
930 fn unknown_group_depth_is_bounded() {
931 use crate::unknown_fields::UnknownField;
932
933 fn group_chain(depth: u32) -> UnknownFields {
934 let mut nested = UnknownFields::new();
935 nested.push(UnknownField {
936 number: 2,
937 data: UnknownFieldData::Varint(7),
938 });
939 for _ in 0..depth {
940 let mut parent = UnknownFields::new();
941 parent.push(UnknownField {
942 number: 1,
943 data: UnknownFieldData::Group(nested),
944 });
945 nested = parent;
946 }
947 nested
948 }
949
950 fn render(fields: &UnknownFields) -> String {
951 let mut s = String::new();
952 TextEncoder::new(&mut s)
953 .emit_unknown(true)
954 .write_unknown_fields(fields)
955 .unwrap();
956 s
957 }
958
959 let at_limit = render(&group_chain(crate::RECURSION_LIMIT));
960 assert_eq!(
961 at_limit.matches('{').count(),
962 crate::RECURSION_LIMIT as usize
963 );
964 assert!(
965 at_limit.contains(": 7"),
966 "the limit-depth body was not printed"
967 );
968
969 let too_deep = render(&group_chain(crate::RECURSION_LIMIT + 25));
970 assert_eq!(
971 too_deep.matches('{').count(),
972 crate::RECURSION_LIMIT as usize + 1,
973 "over-depth groups should stop at the recursion limit: {too_deep}"
974 );
975 assert!(
976 !too_deep.contains(": 7"),
977 "the over-depth group body was printed"
978 );
979 }
980
981 #[test]
982 fn unknown_fields_after_known_fields() {
983 // The common case: generated encode_text writes known fields first,
984 // then calls write_unknown_fields. Separator must be correct.
985 use crate::unknown_fields::UnknownField;
986 let mut fields = UnknownFields::new();
987 fields.push(UnknownField {
988 number: 99,
989 data: UnknownFieldData::Varint(1),
990 });
991
992 let mut s = String::new();
993 let mut enc = TextEncoder::new(&mut s).emit_unknown(true);
994 enc.write_field_name("known").unwrap();
995 enc.write_i32(5).unwrap();
996 enc.write_unknown_fields(&fields).unwrap();
997 assert_eq!(s, "known: 5 99: 1");
998 }
999
1000 #[test]
1001 fn unknown_ld_heuristic_prints_nested() {
1002 // [0x08, 0x6F] is field-1-varint-111 — the conformance test case.
1003 // Heuristic parses it and emits nested `{ 1: 111 }` instead of bytes.
1004 use crate::unknown_fields::UnknownField;
1005 use alloc::vec;
1006 let mut fields = UnknownFields::new();
1007 fields.push(UnknownField {
1008 number: 1003,
1009 data: UnknownFieldData::LengthDelimited(vec![0x08, 0x6F]),
1010 });
1011
1012 let mut s = String::new();
1013 let mut enc = TextEncoder::new(&mut s).emit_unknown(true);
1014 enc.write_unknown_fields(&fields).unwrap();
1015 assert_eq!(s, "1003 {1: 111}");
1016 }
1017
1018 #[test]
1019 fn unknown_ld_heuristic_falls_back_to_bytes() {
1020 // Empty bytes and unparseable bytes both fall back to the escaped
1021 // string form — the heuristic only fires when decode_from_slice
1022 // succeeds on non-empty input.
1023 use crate::unknown_fields::UnknownField;
1024 #[rustfmt::skip]
1025 let cases: &[(&[u8], &str)] = &[
1026 (&[], r#"1: """#), // empty → never nested
1027 (&[0x01, 0xFF], r#"1: "\001\377""#), // field 0 / bad wire → bytes
1028 (&[0x08], r#"1: "\010""#), // truncated varint → bytes
1029 (b"hello", r#"1: "hello""#), // 0x6C = wire type 4 (end-group)
1030 // without a start → parse error,
1031 // so readable ASCII stays readable
1032 ];
1033 for &(bytes, want) in cases {
1034 let mut fields = UnknownFields::new();
1035 fields.push(UnknownField {
1036 number: 1,
1037 data: UnknownFieldData::LengthDelimited(bytes.to_vec()),
1038 });
1039 let mut s = String::new();
1040 let mut enc = TextEncoder::new(&mut s).emit_unknown(true);
1041 enc.write_unknown_fields(&fields).unwrap();
1042 assert_eq!(s, want, "bytes: {bytes:02X?}");
1043 }
1044 }
1045
1046 #[test]
1047 fn unknown_ld_heuristic_budget_caps_depth() {
1048 // Nest a valid sub-message 12 levels deep (budget is 10). The 11th
1049 // level should print as bytes, not nested.
1050 use crate::unknown_fields::UnknownField;
1051 use alloc::vec;
1052 // innermost: field 1, varint 7 → [0x08, 0x07]
1053 let mut bytes = vec![0x08, 0x07];
1054 for _ in 0..12 {
1055 let len = bytes.len() as u8;
1056 let mut wrapper = vec![0x0A, len]; // field 1, LD, length
1057 wrapper.extend_from_slice(&bytes);
1058 bytes = wrapper;
1059 }
1060 let mut fields = UnknownFields::new();
1061 fields.push(UnknownField {
1062 number: 99,
1063 data: UnknownFieldData::LengthDelimited(bytes),
1064 });
1065
1066 let mut s = String::new();
1067 let mut enc = TextEncoder::new(&mut s).emit_unknown(true);
1068 enc.write_unknown_fields(&fields).unwrap();
1069 // 10 levels of `{` then a bytes fallback — count open braces.
1070 assert_eq!(s.matches('{').count(), 10, "output: {s}");
1071 assert!(
1072 s.contains(r#": ""#),
1073 "expected bytes fallback at floor: {s}"
1074 );
1075 }
1076}