The model
Three ways in, simplest first:
parseandto_string(plusparse_bytesandto_string_pretty): one call each, default budgets, duplicate keys refused.Parser: the same parse with your ownLimitsandDuplicateKeyspolicy, defined once as aconst.Reader: the document as a stream ofEvents, withread_rawto keep a value as its exact source text andread_valueto build just one part.
A parsed Value borrows from its input; Number keeps exact text with lazy i64/u64/f64 conversion; Object keeps members in document order; json! builds values in code.
What it guarantees, and how each guarantee is checked:
| Guarantee | How it is held |
|---|---|
| Accepts exactly RFC 8259; refuses the rest at the first byte that cannot continue a valid text. | Property tests run random token soup and mutated documents through the crate and an independent strict reference parser written from the RFC grammar: verdict, value, and exact error offset agree. 234 JSONTestSuite-style cases written as data (73 accept, 127 refuse, 34 implementation-defined) pin the kind and offset of every refusal. |
| Written output parses back to the same value. | Round-trip properties over arbitrary documents, compact and pretty, checked by both parsers. |
| No string can change the structure of the output. | Arbitrary strings (rich in quotes, backslashes, control characters, U+2028/U+2029) written as values and keys always read back, under the reference parser, as exactly themselves. |
| Budgets refuse before allocating. | A counting allocator measures peak heap growth: an 8 MiB string over a 1 KiB budget is refused with under 1 KiB allocated; over-size input with none. |
| No stack overflow, no panic. | A million levels of nesting parse, write, clone, compare, and drop on a thread with a 256 KiB stack; arbitrary bytes through every entry point never panic. |
| Duplicate keys cannot smuggle a second value. | Refused by default, compared after unescaping, in O(n log n); every policy checked against a naive reference. |
Installation
[]
= "0.2"
Without the standard library:
[]
= { = "0.2", = false }
Quick start
use ;
let doc = parse?;
assert_eq!;
assert_eq!;
assert!; // indexing never panics
let reply = json!;
assert_eq!;
let err = parse.unwrap_err;
assert_eq!;
# Ok::
Budgets and duplicate keys
use ;
const WIRE: Parser = new
.limits
.duplicate_keys;
let err = WIRE.parse.unwrap_err;
assert_eq!;
let err = WIRE.parse.unwrap_err;
assert_eq!;
Reading a message without building a tree
use ;
let message = r#"{"jsonrpc": "2.0", "id": 4, "method": "hover", "params": {"line": 3}}"#;
let mut reader = new;
let = ;
assert_eq!;
while let Some = reader.next_event?
reader.finish?;
assert_eq!;
assert_eq!;
# Ok::
Performance
Latest local Criterion means (cargo bench --bench bench, release profile, Windows x86_64, one run on a busy machine; run-to-run noise of 10–30% was observed) on an LSP-shaped document of completion items with ranges, escaped strings, floats, and small arrays:
| Benchmark | 1 MB | 100 MB |
|---|---|---|
parse into a Value (duplicate keys refused) |
~122 MiB/s | ~81 MiB/s |
parse with DuplicateKeys::KeepAll |
~150 MiB/s | ~82 MiB/s |
Reader: every event, no tree |
~372 MiB/s | ~368 MiB/s |
Reader::read_raw: validate the whole document |
~454 MiB/s | ~429 MiB/s |
to_string |
~548 MiB/s | ~229 MiB/s |
to_string_pretty |
~291 MiB/s | ~157 MiB/s |
Deep clone |
~257 MiB/s | ~110 MiB/s |
Strings (1 MB): parsing a string with few escapes ~4.7 GiB/s, with dense escapes ~187 MiB/s; write_string ~5.2 GiB/s and ~325 MiB/s. Numbers: Number::from_f64 ~5.0 M/s, as_f64 ~47 M/s, as_i64 ~92 M/s. No comparison against other JSON crates has been run yet (planned for 0.9).
Building a tree is bound by the allocator (about eight allocations per completion item, freed again on drop); the event reader and read_raw show what the scanner itself costs.
Documentation
- API reference: every public item, with examples.
- Release notes for 0.2.0.
- Roadmap and engineering directives.
Contributing
See dev/DIRECTIVES.md for engineering standards and the definition of done. Before a PR: cargo fmt --all, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features must be clean.