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