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
parseandto_string(plusparse_bytesandto_string_pretty): one call each, default budgets, duplicate keys refused.Parser: the same parse with your ownLimitsandDuplicateKeyspolicy, kept as aconstand reused.Reader: the document as a stream ofEvents, withread_rawto keep a value as its source text andread_valueto build just one part of it.
§What it guarantees
- Exactly RFC 8259. Everything the grammar allows is accepted;
everything else is refused with an
Errorthat 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
Numberkeeps its text; conversion toi64,u64, orf64happens 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
std(default): addsto_writerandto_writer_pretty. Without it the crate isno_stdand needs onlyalloc.
Macros§
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, fromObject::iter. - IterMut
- An iterator over an
Object’s members with mutable values, fromObject::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:
Limitsand aDuplicateKeyspolicy. - Reader
- A pull parser: reads a document one
Eventat a time, building nothing.
Enums§
- Duplicate
Keys - What to do when an object names the same key twice.
- Error
Kind - The kinds of
Error. - Event
- One step through a document, from
Reader::next_event. - Kind
- Which of JSON’s six kinds of value a
Valueis. - 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. SeeParser::parse_bytes. - to_
string - Serializes
valueas compact JSON: no whitespace at all. - to_
string_ pretty - Serializes
valueas indented JSON: two spaces per level, one member or item per line,": "after keys, empty containers as[]and{}, and no trailing newline. - to_
writer std - Writes
valueas compact JSON to anio::Write, through a buffer of a few kilobytes, so a large document is never held as one string. - to_
writer_ pretty std - Writes
valueas indented JSON (seeto_string_pretty) to anio::Write, through a buffer of a few kilobytes. - write_
string - Appends
texttooutas a JSON string literal, quotes included. - write_
value - Appends
valuetooutas compact JSON (seeto_string). Reusing one buffer across documents avoids an allocation per document. - write_
value_ pretty - Appends
valuetooutas indented JSON (seeto_string_pretty).