Skip to main content

jsonx_lib/
write.rs

1//! The writer: deterministic compact and pretty output with complete escaping.
2
3use alloc::{borrow::Cow, string::String};
4use core::{fmt, slice};
5
6use crate::{
7    Format, ToJson, Value,
8    encode::{Keep, Out, ValueWriter, Written},
9    scan,
10    tree::Member,
11};
12
13/// Spaces for indentation, copied in slices.
14const SPACES: &str = "                                                                ";
15
16/// Appends `text` to `out` as a JSON string literal, quotes included.
17///
18/// The escaping is complete and the same every time:
19///
20/// - `"` and `\` are escaped as `\"` and `\\`;
21/// - the control characters U+0000 to U+001F are escaped, with the short forms
22///   `\b \f \n \r \t` where JSON has one and `\u00XX` (lowercase hex)
23///   otherwise;
24/// - U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR are escaped as
25///   `\u2028` and `\u2029`: JSON allows them raw, but JavaScript before ES2019
26///   ends a line at them, so raw ones break JSON embedded in a script;
27/// - everything else, including `/`, DEL, and all other non-ASCII text, is
28///   copied unchanged as UTF-8.
29///
30/// This escaping is not HTML-safe: `<`, `>`, and `&` are copied, so
31/// `</script>` inside a string stays `</script>` in the output. For JSON
32/// placed inside HTML, write with [`Format::html_safe`] (and
33/// [`Format::ascii`] for a channel that is not 8-bit clean).
34///
35/// So no string can end the literal early or put a raw line break in it,
36/// whatever it contains: the output is always exactly one JSON string token
37/// that decodes back to `text`. Unescaped stretches are copied in bulk, found
38/// eight bytes at a time.
39///
40/// # Examples
41///
42/// ```
43/// let mut out = String::from("{\"msg\":");
44/// jsonx_lib::write_string(&mut out, "say \"hi\"\n\u{2028}");
45/// out.push('}');
46/// assert_eq!(out, r#"{"msg":"say \"hi\"\n\u2028"}"#);
47/// ```
48pub fn write_string(out: &mut String, text: &str) {
49    out.reserve(text.len() + 2);
50    out.push('"');
51    let bytes = text.as_bytes();
52    let mut from = 0;
53    let mut at = 0;
54    loop {
55        at = scan::find_write_special(bytes, at);
56        let Some(&b) = bytes.get(at) else { break };
57        let escape: &str = match b {
58            b'"' => "\\\"",
59            b'\\' => "\\\\",
60            b'\n' => "\\n",
61            b'\r' => "\\r",
62            b'\t' => "\\t",
63            0x08 => "\\b",
64            0x0C => "\\f",
65            0xE2 => match bytes.get(at + 1..at + 3) {
66                Some([0x80, 0xA8]) => "\\u2028",
67                Some([0x80, 0xA9]) => "\\u2029",
68                // Another character starting with 0xE2: copy it as is.
69                _ => {
70                    at += 1;
71                    continue;
72                }
73            },
74            control => {
75                out.push_str(text.get(from..at).unwrap_or(""));
76                out.push_str("\\u00");
77                out.push(char::from(scan::hex_digit(control >> 4)));
78                out.push(char::from(scan::hex_digit(control)));
79                at += 1;
80                from = at;
81                continue;
82            }
83        };
84        out.push_str(text.get(from..at).unwrap_or(""));
85        out.push_str(escape);
86        // The line separators are three bytes; every other escaped byte, one.
87        at += if b == 0xE2 { 3 } else { 1 };
88        from = at;
89    }
90    out.push_str(text.get(from..).unwrap_or(""));
91    out.push('"');
92}
93
94/// Appends `text` as a JSON string literal escaped as `format` asks:
95/// [`write_string`] unless the format is [`html_safe`](Format::html_safe)
96/// or [`ascii`](Format::ascii).
97#[inline]
98pub(crate) fn write_str(out: &mut String, text: &str, format: Format) {
99    if format.strict() {
100        write_string_strict(out, text, format);
101    } else {
102        write_string(out, text);
103    }
104}
105
106/// [`write_string`] with the stricter escaping of `format`: `<`, `>`, and
107/// `&` when HTML-safe, every non-ASCII character when ASCII-only.
108fn write_string_strict(out: &mut String, text: &str, format: Format) {
109    out.reserve(text.len() + 2);
110    out.push('"');
111    let mut from = 0;
112    for (at, ch) in text.char_indices() {
113        let escape = match ch {
114            '"' | '\\' | '\u{0}'..='\u{1f}' | '\u{2028}' | '\u{2029}' => true,
115            '<' | '>' | '&' => format.html,
116            _ => format.ascii && !ch.is_ascii(),
117        };
118        if !escape {
119            continue;
120        }
121        out.push_str(text.get(from..at).unwrap_or(""));
122        from = at + ch.len_utf8();
123        match ch {
124            '"' => out.push_str("\\\""),
125            '\\' => out.push_str("\\\\"),
126            '\n' => out.push_str("\\n"),
127            '\r' => out.push_str("\\r"),
128            '\t' => out.push_str("\\t"),
129            '\u{8}' => out.push_str("\\b"),
130            '\u{c}' => out.push_str("\\f"),
131            _ => {
132                let mut units = [0u16; 2];
133                for unit in ch.encode_utf16(&mut units) {
134                    push_unicode_escape(out, *unit);
135                }
136            }
137        }
138    }
139    out.push_str(text.get(from..).unwrap_or(""));
140    out.push('"');
141}
142
143/// Appends `raw`, the text of one valid JSON value, in `format`: unchanged
144/// in the plain formats; under a strict one, with every character that
145/// format escapes in strings (`<`, `>`, `&` when HTML-safe, anything
146/// non-ASCII when ASCII-only, U+2028 and U+2029 in both) written as its
147/// `\uXXXX` escape. In valid JSON those characters can only occur inside
148/// strings, where the escape stands for the same character, so the value is
149/// unchanged and the format's byte guarantees hold for raw text too.
150pub(crate) fn write_raw(out: &mut String, raw: &str, format: Format) {
151    if !format.strict() {
152        out.push_str(raw);
153        return;
154    }
155    out.reserve(raw.len());
156    let mut from = 0;
157    for (at, ch) in raw.char_indices() {
158        let escape = match ch {
159            '\u{2028}' | '\u{2029}' => true,
160            '<' | '>' | '&' => format.html,
161            _ => format.ascii && !ch.is_ascii(),
162        };
163        if !escape {
164            continue;
165        }
166        out.push_str(raw.get(from..at).unwrap_or(""));
167        from = at + ch.len_utf8();
168        let mut units = [0u16; 2];
169        for unit in ch.encode_utf16(&mut units) {
170            push_unicode_escape(out, *unit);
171        }
172    }
173    out.push_str(raw.get(from..).unwrap_or(""));
174}
175
176/// Appends the six-character escape for one UTF-16 code unit, lowercase.
177fn push_unicode_escape(out: &mut String, unit: u16) {
178    out.push('\\');
179    out.push('u');
180    for shift in [12, 8, 4, 0] {
181        // The nibble is below 16.
182        out.push(char::from(scan::hex_digit((unit >> shift) as u8)));
183    }
184}
185
186/// Serializes `value` as compact JSON: no whitespace at all.
187///
188/// `value` is anything that implements [`ToJson`]: a [`Value`], or your own
189/// type, written straight to text without building a `Value`. The output is
190/// deterministic: members in their order, numbers as their exact text,
191/// strings escaped as [`write_string`] describes. For a `Value`, parsing the
192/// output gives back an equal value.
193///
194/// # Examples
195///
196/// ```
197/// use jsonx_lib::{json, to_string};
198///
199/// let v = json!({ "id": 1, "tags": ["a", "b"], "none": null });
200/// assert_eq!(to_string(&v), r#"{"id":1,"tags":["a","b"],"none":null}"#);
201/// assert_eq!(to_string(&[Some(1), None]), "[1,null]");
202/// ```
203#[must_use]
204pub fn to_string<T: ToJson + ?Sized>(value: &T) -> String {
205    let mut out = String::new();
206    write_value(&mut out, value);
207    out
208}
209
210/// Serializes `value` as indented JSON: two spaces per level, one member or
211/// item per line, `": "` after keys, empty containers as `[]` and `{}`, and
212/// no trailing newline.
213///
214/// # Examples
215///
216/// ```
217/// use jsonx_lib::{json, to_string_pretty};
218///
219/// let v = json!({ "a": [1, 2], "b": {} });
220/// assert_eq!(to_string_pretty(&v), "{\n  \"a\": [\n    1,\n    2\n  ],\n  \"b\": {}\n}");
221/// ```
222#[must_use]
223pub fn to_string_pretty<T: ToJson + ?Sized>(value: &T) -> String {
224    let mut out = String::new();
225    write_value_pretty(&mut out, value);
226    out
227}
228
229/// Appends `value` to `out` as compact JSON (see [`to_string`]). Reusing one
230/// buffer across documents avoids an allocation per document.
231///
232/// # Examples
233///
234/// ```
235/// use jsonx_lib::{json, write_value};
236///
237/// let mut out = String::from("Content: ");
238/// write_value(&mut out, &json!([true]));
239/// assert_eq!(out, "Content: [true]");
240/// ```
241pub fn write_value<T: ToJson + ?Sized>(out: &mut String, value: &T) {
242    write_value_with(out, value, Format::compact());
243}
244
245/// Appends `value` to `out` as indented JSON (see [`to_string_pretty`]).
246///
247/// # Examples
248///
249/// ```
250/// use jsonx_lib::{json, write_value_pretty};
251///
252/// let mut out = String::new();
253/// write_value_pretty(&mut out, &json!([1]));
254/// assert_eq!(out, "[\n  1\n]");
255/// ```
256pub fn write_value_pretty<T: ToJson + ?Sized>(out: &mut String, value: &T) {
257    write_value_with(out, value, Format::pretty());
258}
259
260/// Serializes `value` in the given [`Format`].
261///
262/// # Examples
263///
264/// ```
265/// use jsonx_lib::{json, to_string_with, Format};
266///
267/// let v = json!({ "tag": "<b>" });
268/// assert_eq!(to_string_with(&v, Format::compact().html_safe(true)), r#"{"tag":"\u003cb\u003e"}"#);
269/// ```
270#[must_use]
271pub fn to_string_with<T: ToJson + ?Sized>(value: &T, format: Format) -> String {
272    let mut out = String::new();
273    write_value_with(&mut out, value, format);
274    out
275}
276
277/// Appends `value` to `out` in the given [`Format`].
278///
279/// # Examples
280///
281/// ```
282/// use jsonx_lib::{write_value_with, Format};
283///
284/// let mut out = String::from("data: ");
285/// write_value_with(&mut out, &[1, 2], Format::pretty().with_indent(0));
286/// assert_eq!(out, "data: [\n1,\n2\n]");
287/// ```
288pub fn write_value_with<T: ToJson + ?Sized>(out: &mut String, value: &T, format: Format) {
289    let mut keep = Keep;
290    let writer = ValueWriter::new(Out {
291        buf: out,
292        sink: &mut keep,
293        flush_at: usize::MAX,
294        format,
295        depth: 0,
296    });
297    let Written(()) = value.to_json(writer);
298}
299
300/// Writes `value` as compact JSON to an [`io::Write`](std::io::Write),
301/// through a buffer of a few kilobytes, so a large document is never held as
302/// one string.
303///
304/// # Errors
305///
306/// Any error from `writer`.
307///
308/// # Examples
309///
310/// ```
311/// let mut out = Vec::new();
312/// jsonx_lib::to_writer(&mut out, &jsonx_lib::json!({ "ok": true }))?;
313/// assert_eq!(out, br#"{"ok":true}"#);
314/// # Ok::<(), std::io::Error>(())
315/// ```
316#[cfg(feature = "std")]
317#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
318pub fn to_writer<W: std::io::Write, T: ToJson + ?Sized>(
319    writer: W,
320    value: &T,
321) -> std::io::Result<()> {
322    to_writer_with(writer, value, Format::compact())
323}
324
325/// Writes `value` as indented JSON (see [`to_string_pretty`]) to an
326/// [`io::Write`](std::io::Write), through a buffer of a few kilobytes.
327///
328/// # Errors
329///
330/// Any error from `writer`.
331///
332/// # Examples
333///
334/// ```
335/// let mut out = Vec::new();
336/// jsonx_lib::to_writer_pretty(&mut out, &jsonx_lib::json!([null]))?;
337/// assert_eq!(out, b"[\n  null\n]");
338/// # Ok::<(), std::io::Error>(())
339/// ```
340#[cfg(feature = "std")]
341#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
342pub fn to_writer_pretty<W: std::io::Write, T: ToJson + ?Sized>(
343    writer: W,
344    value: &T,
345) -> std::io::Result<()> {
346    to_writer_with(writer, value, Format::pretty())
347}
348
349/// How much output the streaming writers collect before passing it on.
350pub(crate) const CHUNK: usize = 8 * 1024;
351
352/// Writes `value` in the given [`Format`] to an [`io::Write`](std::io::Write),
353/// through a buffer of a few kilobytes.
354///
355/// # Errors
356///
357/// Any error from `writer`.
358///
359/// # Examples
360///
361/// ```
362/// use jsonx_lib::{json, to_writer_with, Format};
363///
364/// let mut out = Vec::new();
365/// to_writer_with(&mut out, &json!(["caf\u{e9}"]), Format::compact().ascii(true))?;
366/// assert_eq!(out, b"[\"caf\\u00e9\"]");
367/// # Ok::<(), std::io::Error>(())
368/// ```
369#[cfg(feature = "std")]
370#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
371pub fn to_writer_with<W: std::io::Write, T: ToJson + ?Sized>(
372    mut writer: W,
373    value: &T,
374    format: Format,
375) -> std::io::Result<()> {
376    let mut buf = String::with_capacity(CHUNK + 256);
377    let mut sink = crate::encode::IoSink {
378        writer: &mut writer,
379        error: None,
380    };
381    let out = Out {
382        buf: &mut buf,
383        sink: &mut sink,
384        flush_at: CHUNK,
385        format,
386        depth: 0,
387    };
388    let Written(()) = value.to_json(ValueWriter::new(out));
389    crate::encode::Flush::flush(&mut sink, &mut buf);
390    sink.error.map_or(Ok(()), Err)
391}
392
393/// Appends a newline and the indentation for `depth` levels.
394pub(crate) fn newline(out: &mut String, depth: usize, format: Format) {
395    out.push('\n');
396    let mut width = depth.saturating_mul(usize::from(format.indent));
397    while width > 0 {
398        let chunk = width.min(SPACES.len());
399        out.push_str(SPACES.get(..chunk).unwrap_or(""));
400        width -= chunk;
401    }
402}
403
404/// The children of an open container still to be written.
405enum Open<'r, 'a> {
406    Array(slice::Iter<'r, Value<'a>>),
407    Object(slice::Iter<'r, Member<'a>>),
408}
409
410/// Writes `value` into `out`, handing `out` to `flush` whenever it holds at
411/// least `flush_at` bytes (the flush is expected to empty it). In the pretty
412/// layout, the value starts at indentation level `base`.
413///
414/// Iterative: an explicit stack of open containers replaces recursion, so any
415/// depth is safe.
416pub(crate) fn emit<E>(
417    out: &mut String,
418    value: &Value<'_>,
419    format: Format,
420    base: usize,
421    flush_at: usize,
422    flush: &mut dyn FnMut(&mut String) -> Result<(), E>,
423) -> Result<(), E> {
424    // One copy of the loop per layout, so the common one (compact, plainly
425    // escaped) tests neither per value.
426    match (format.pretty, format.strict()) {
427        (false, false) => emit_as::<E, false, false>(out, value, format, base, flush_at, flush),
428        (false, true) => emit_as::<E, false, true>(out, value, format, base, flush_at, flush),
429        (true, false) => emit_as::<E, true, false>(out, value, format, base, flush_at, flush),
430        (true, true) => emit_as::<E, true, true>(out, value, format, base, flush_at, flush),
431    }
432}
433
434/// [`emit`] for one layout: `PRETTY` is `format.pretty`, `STRICT` is
435/// `format.strict()`.
436fn emit_as<E, const PRETTY: bool, const STRICT: bool>(
437    out: &mut String,
438    value: &Value<'_>,
439    format: Format,
440    base: usize,
441    flush_at: usize,
442    flush: &mut dyn FnMut(&mut String) -> Result<(), E>,
443) -> Result<(), E> {
444    let write_text = |out: &mut String, text: &str| {
445        if STRICT {
446            write_string_strict(out, text, format);
447        } else {
448            write_string(out, text);
449        }
450    };
451    let mut stack: alloc::vec::Vec<(Open<'_, '_>, bool)> = alloc::vec::Vec::new();
452    let mut next = Some(value);
453    loop {
454        if let Some(value) = next.take() {
455            match value {
456                Value::Null => out.push_str("null"),
457                Value::Bool(true) => out.push_str("true"),
458                Value::Bool(false) => out.push_str("false"),
459                Value::Number(n) => out.push_str(n.as_str()),
460                Value::String(s) => write_text(out, s),
461                Value::Array(a) if a.is_empty() => out.push_str("[]"),
462                Value::Object(o) if o.is_empty() => out.push_str("{}"),
463                Value::Array(a) => {
464                    out.push('[');
465                    stack.push((Open::Array(a.iter()), true));
466                }
467                Value::Object(o) => {
468                    out.push('{');
469                    stack.push((Open::Object(o.as_slice().iter()), true));
470                }
471            }
472            if out.len() >= flush_at {
473                flush(out)?;
474            }
475        }
476        let depth = stack.len();
477        let Some((open, first)) = stack.last_mut() else {
478            return Ok(());
479        };
480        let (child, key): (Option<&Value<'_>>, Option<&Cow<'_, str>>) = match open {
481            Open::Array(it) => (it.next(), None),
482            Open::Object(it) => match it.next() {
483                Some((k, v)) => (Some(v), Some(k)),
484                None => (None, None),
485            },
486        };
487        let Some(child) = child else {
488            let close = if matches!(open, Open::Array(_)) {
489                ']'
490            } else {
491                '}'
492            };
493            let _closed = stack.pop();
494            if PRETTY {
495                newline(out, base + depth - 1, format);
496            }
497            out.push(close);
498            continue;
499        };
500        if !*first {
501            out.push(',');
502        }
503        *first = false;
504        if PRETTY {
505            newline(out, base + depth, format);
506        }
507        if let Some(key) = key {
508            write_text(out, key);
509            out.push_str(if PRETTY { ": " } else { ":" });
510        }
511        next = Some(child);
512    }
513}
514
515impl fmt::Display for Value<'_> {
516    /// Writes the value as compact JSON, or as indented JSON with the
517    /// alternate flag (`{:#}`).
518    ///
519    /// # Examples
520    ///
521    /// ```
522    /// let v = jsonx_lib::json!({ "a": [1] });
523    /// assert_eq!(format!("{v}"), r#"{"a":[1]}"#);
524    /// assert_eq!(format!("{v:#}"), "{\n  \"a\": [\n    1\n  ]\n}");
525    /// ```
526    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
527        const CHUNK: usize = 4 * 1024;
528        let mut buf = String::new();
529        emit(
530            &mut buf,
531            self,
532            if f.alternate() {
533                Format::pretty()
534            } else {
535                Format::compact()
536            },
537            0,
538            CHUNK,
539            &mut |chunk: &mut String| {
540                let result = f.write_str(chunk);
541                chunk.clear();
542                result
543            },
544        )?;
545        f.write_str(&buf)
546    }
547}
548
549impl fmt::Debug for Value<'_> {
550    /// Writes the value as compact JSON.
551    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
552        fmt::Display::fmt(self, f)
553    }
554}
555
556#[cfg(test)]
557mod tests {
558    use alloc::string::ToString;
559
560    use super::*;
561
562    fn quoted(text: &str) -> String {
563        let mut out = String::new();
564        write_string(&mut out, text);
565        out
566    }
567
568    #[test]
569    fn test_write_string_escapes_exactly() {
570        assert_eq!(quoted(""), r#""""#);
571        assert_eq!(quoted("plain/text"), r#""plain/text""#);
572        assert_eq!(quoted("\"\\"), r#""\"\\""#);
573        assert_eq!(quoted("\u{8}\u{c}\n\r\t"), r#""\b\f\n\r\t""#);
574        assert_eq!(
575            quoted("\u{0}\u{1}\u{1f}\u{7f}"),
576            "\"\\u0000\\u0001\\u001f\u{7f}\""
577        );
578        assert_eq!(quoted("a\u{2028}b\u{2029}c"), r#""a\u2028b\u2029c""#);
579        // Other characters starting with 0xE2 pass through.
580        assert_eq!(
581            quoted("\u{20ac}\u{2027}\u{202a}"),
582            "\"\u{20ac}\u{2027}\u{202a}\""
583        );
584        assert_eq!(
585            quoted("long run of text then \" quote"),
586            r#""long run of text then \" quote""#
587        );
588    }
589
590    #[test]
591    fn test_pretty_layout_nested_and_empty() {
592        let v = crate::parse(r#"{"a":[],"b":{},"c":[{"d":null}]}"#).unwrap_or_default();
593        assert_eq!(
594            to_string_pretty(&v),
595            "{\n  \"a\": [],\n  \"b\": {},\n  \"c\": [\n    {\n      \"d\": null\n    }\n  ]\n}"
596        );
597        assert_eq!(to_string_pretty(&Value::from(1)), "1");
598    }
599
600    #[test]
601    fn test_display_flushes_in_chunks_identically() {
602        let mut big = String::from("[");
603        for i in 0..5000 {
604            big.push_str(&alloc::format!("{i},"));
605        }
606        big.push_str("0]");
607        let v = crate::parse(&big).unwrap_or_default();
608        assert_eq!(v.to_string(), big);
609    }
610
611    #[test]
612    fn test_deep_indent_beyond_spaces_buffer() {
613        let depth = 40;
614        let text = "[".repeat(depth) + &"]".repeat(depth);
615        let v = crate::parse(&text).unwrap_or_default();
616        let pretty = to_string_pretty(&v);
617        assert!(pretty.contains(&alloc::format!("\n{}[]", " ".repeat((depth - 1) * 2))));
618    }
619}