Skip to main content

Crate nosj

Crate nosj 

Source
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:

DirectionHost-drivenLibrary-driven
Parsepull (Reader)push (Sink via parse / parse_indexed)
Generatewrite (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-enforcing next_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::Writer layers 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 Reader or crate::parse call to amortize allocations across parses.
ParseError
A parse failure with the byte offset where it was detected.
ParseOptions
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.
WriteOptions
Layout and escaping configuration for a Writer.
Writer
Streaming JSON writer over a byte buffer.

Enums§

DriveError
Failure while driving a sink: either the document didn’t parse, or the sink aborted.
ErrorKind
What went wrong, without position information (see ParseError).
FloatFormat
Float formatting for Writer::float.
Node
A single value-position token.

Traits§

Sink
Receives parse events in document order.

Functions§

parse
Parse input in a single fused pass, pushing events into sink.
parse_indexed
Parse input, pushing events into sink.
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 from ParseOptions.
pointer
Resolve pointer against input, returning the raw text of the matched value (None if 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 from ParseOptions.
pointer_with
Like pointer(), with grammar extensions from ParseOptions.
pointers
Resolve many pointers in one forward pass, returning raw slices positionally aligned with pointers (None where a pointer doesn’t match). Sequential pointer() 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 from ParseOptions.
pointers_with
Like pointers(), with grammar extensions from ParseOptions.