Skip to main content

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}