Skip to main content

Crate jsonx_lib

Crate jsonx_lib 

Source
Expand description

§jsonx_lib

Strict RFC 8259 JSON: a parser that borrows from its input, a pull reader, and a deterministic writer, with budgets that refuse hostile input before it costs memory. No dependencies; no_std with alloc.

§Quick start

use jsonx_lib::{json, parse, to_string};

let doc = parse(r#"{"name": "jsonx", "version": [0, 2, 0], "stable": false}"#)?;
assert_eq!(doc["name"], "jsonx");
assert_eq!(doc["version"][1].as_u64(), Some(2));

let reply = json!({ "ok": true, "items": [1, 2, 3] });
assert_eq!(to_string(&reply), r#"{"ok":true,"items":[1,2,3]}"#);

§The three ways in

  1. parse and to_string (plus parse_bytes and to_string_pretty): one call each, default budgets, duplicate keys refused.
  2. Parser: the same parse with your own Limits and DuplicateKeys policy, kept as a const and reused.
  3. Reader: the document as a stream of Events, with read_raw to keep a value as its source text and read_value to build just one part of it.

§What it guarantees

  • Exactly RFC 8259. Everything the grammar allows is accepted; everything else is refused with an Error that names the first byte at which the input stops being valid. Unpaired UTF-16 surrogate escapes, which the grammar allows but which decode to no Unicode text, are refused too.
  • Borrowing. Strings without escapes and every number are slices of the input; only strings with escapes are copied, once, into a buffer of exactly the right size.
  • Exact numbers. A Number keeps its text; conversion to i64, u64, or f64 happens when asked and never rounds silently into an integer.
  • Budgets before allocation. Depth, input size, string length, number length, and value count are all checked before the memory they guard is used (Limits).
  • No recursion on depth. Parsing, writing, cloning, and comparing loop over explicit stacks; dropping recurses at most a fixed 32 levels. A million levels of nesting cannot overflow the stack.
  • Round trip. Written output parses back to an equal value, and the escaping cannot be broken out of by any string (write_string).
  • No panics on any input, and #![forbid(unsafe_code)].

§Feature flags

Macros§

json
Builds a Value from JSON-like syntax.

Structs§

Array
A JSON array: a list of values in document order.
Error
Why a document was rejected, and where.
Iter
An iterator over an Object’s members, from Object::iter.
IterMut
An iterator over an Object’s members with mutable values, from Object::iter_mut.
Limits
Budgets on the work and memory a document may cost.
Number
A JSON number, kept as the exact text of the document.
Object
A JSON object: its members in document order.
Parser
A configured parser: Limits and a DuplicateKeys policy.
Reader
A pull parser: reads a document one Event at a time, building nothing.

Enums§

DuplicateKeys
What to do when an object names the same key twice.
ErrorKind
The kinds of Error.
Event
One step through a document, from Reader::next_event.
Kind
Which of JSON’s six kinds of value a Value is.
Value
A JSON value, borrowing from the text it was parsed from.

Functions§

parse
Parses one JSON document with the default Limits, refusing duplicate keys.
parse_bytes
Parses one JSON document from bytes, which must be UTF-8, with the default Limits. See Parser::parse_bytes.
to_string
Serializes value as compact JSON: no whitespace at all.
to_string_pretty
Serializes value as indented JSON: two spaces per level, one member or item per line, ": " after keys, empty containers as [] and {}, and no trailing newline.
to_writerstd
Writes value as compact JSON to an io::Write, through a buffer of a few kilobytes, so a large document is never held as one string.
to_writer_prettystd
Writes value as indented JSON (see to_string_pretty) to an io::Write, through a buffer of a few kilobytes.
write_string
Appends text to out as a JSON string literal, quotes included.
write_value
Appends value to out as compact JSON (see to_string). Reusing one buffer across documents avoids an allocation per document.
write_value_pretty
Appends value to out as indented JSON (see to_string_pretty).