Expand description
§nosj
Pull, push and fused-cursor JSON parsers plus a streaming writer, for hosts that build their own values (language runtimes, database engines, columnar loaders): any consumer that wants JSON events without a DOM, a tape, serde, or intermediate copies of the input. SIMD-accelerated throughout (NEON on aarch64; SSE2 baseline and runtime-detected AVX2 on x86-64; SWAR + table fallbacks elsewhere).
§Interfaces
Four interfaces, one per driving pattern:
| Direction | Host-driven | Library-driven |
|---|---|---|
| Parse | pull (Reader) | push (Sink via parse / parse_indexed) |
| Generate | write (Writer) | (none) |
parse(push): a fused single-pass byte cursor in the architectural lineage of yyjson, and the fastest path for building a full value tree. Flat containers are consumed in tight scalar loops with no frame-stack traffic.parse_indexed(push): SIMD stage-1 structural indexing (simdjson lineage), then one dispatch per token. The indexing phase is exposed separately (Buffers::preindex+parse_preindexed_utf8_unchecked) so hosts with a global interpreter lock (a GVL/GIL) can run it outside the lock.Reader(pull): grammar-enforcingnext_node()navigation for selective or partial consumption.Writer(write): a streaming, infallible push writer; the host emits events, the writer owns separators, depth, layout, and escaping.
§Parsing
use nosj::{Buffers, Node, Reader};
let mut bufs = Buffers::new();
let mut p = Reader::new(r#"{"a": [1, true]}"#, &mut bufs);
assert!(matches!(p.next_node().unwrap(), Node::ObjectStart));
assert_eq!(p.object_first_key().unwrap(), Some("a"));
assert!(matches!(p.next_node().unwrap(), Node::ArrayStart));
assert!(p.array_first().unwrap());
assert!(matches!(p.next_node().unwrap(), Node::Int(1)));
assert!(p.array_next().unwrap());
assert!(matches!(p.next_node().unwrap(), Node::Bool(true)));
assert!(!p.array_next().unwrap());
assert_eq!(p.object_next_key().unwrap(), None);
p.finish().unwrap();§Generating
use nosj::{WriteOptions, Writer};
let mut out = Vec::new();
let pretty = WriteOptions::pretty();
let mut w = Writer::new(&mut out, &pretty);
w.begin_object();
w.key("size");
w.int(3);
w.end_object();
assert_eq!(out, b"{\n \"size\": 3\n}");Number formatting is deliberately pinned: integers as plain decimal,
floats in the fpconv (Grisu2) format; see emit::write_f64 for why
that differs from Rust’s shortest-round-trip Display.
§Grammar extensions
Strict RFC 8259 by default. ParseOptions opts into extensions many
deployed parsers accept: NaN / Infinity / -Infinity literals and
trailing commas. All option checks sit on cold paths; the defaults cost
nothing per token.
§UTF-8 contract
&str entry points are safe. The *_utf8_unchecked entry points skip
whole-input validation for hosts whose runtime already tracks string
validity; string content is still validated structurally during the
parse. One deliberate leniency, matching widely deployed parsers: a lone
low surrogate escape decodes to its raw WTF-8 bytes and is delivered
via Sink::str_bytes (lossy-converted by default); a lone high
surrogate is an error.
Modules§
- emit
- JSON emission kernels: SIMD escape scanning and pinned-format number
writing. Pure computation over byte buffers:
crate::Writerlayers grammar state on top; hosts with bespoke needs can call these directly. - scalars
- Scalar token parsing for the pull parser: strings (zero-copy fast path + escape decoding), numbers (grammar-validating scan with i64/f64/bignum split), and literals. Pure computation, no host types, unit-testable.
Structs§
- Buffers
- Reusable allocations. Keep one per thread and hand it to each
Readerorcrate::parsecall to amortize allocations across parses. - Parse
Error - A parse failure with the byte offset where it was detected.
- Parse
Options - Grammar extensions beyond RFC 8259 that many deployed parsers accept. All checks sit on cold paths; the defaults cost nothing per token.
- Reader
- Pull cursor over one JSON document.
- Write
Options - Layout and escaping configuration for a
Writer. - Writer
- Streaming JSON writer over a byte buffer.
Enums§
- Drive
Error - Failure while driving a sink: either the document didn’t parse, or the sink aborted.
- Error
Kind - What went wrong, without position information (see
ParseError). - Float
Format - Float formatting for
Writer::float. - Node
- A single value-position token.
Traits§
- Sink
- Receives parse events in document order.
Functions§
- parse
- Parse
inputin a single fused pass, pushing events intosink. - parse_
indexed - Parse
input, pushing events intosink. - parse_
indexed_ ⚠utf8_ unchecked - Like
parse_indexed, for callers whose runtime vouches for UTF-8 validity. - parse_
preindexed_ ⚠utf8_ unchecked - Drive a sink over buffers already indexed by
Buffers::preindex, skipping the indexing phase. - parse_
utf8_ ⚠unchecked - Like
parse, for callers whose runtime vouches for UTF-8. - parse_
utf8_ ⚠unchecked_ with - Like
parse_utf8_unchecked, with grammar extensions. - parse_
with - Like
parse, with grammar extensions fromParseOptions. - pointer
- Resolve
pointeragainstinput, returning the raw text of the matched value (Noneif the pointer doesn’t match anything). - pointer_
utf8_ ⚠unchecked - Like
pointer(), for callers whose runtime vouches for UTF-8. - pointer_
utf8_ ⚠unchecked_ with - Like
pointer_utf8_unchecked, with grammar extensions fromParseOptions. - pointer_
with - Like
pointer(), with grammar extensions fromParseOptions. - pointers
- Resolve many pointers in one forward pass, returning raw slices
positionally aligned with
pointers(Nonewhere a pointer doesn’t match). Sequentialpointer()calls re-scan the document prefix per query; this walks it once, descending only into members some pointer still needs and skipping everything else at block speed. - pointers_
utf8_ ⚠unchecked - Like
pointers(), for callers whose runtime vouches for UTF-8. - pointers_
utf8_ ⚠unchecked_ with - Like
pointers_utf8_unchecked, with grammar extensions fromParseOptions. - pointers_
with - Like
pointers(), with grammar extensions fromParseOptions.