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}