Skip to main content

Crate json_slabs

Crate json_slabs 

Source
Expand description

A crate for reading and writing JsonSlabs (JSLB) files — a binary container format for JSON-shaped data with embedded typed-array slabs.

JSON slabs use placeholder objects of the form { "$s": <slab-index> } to refer to data that’s stored in other slabs.

This crate does not include any JSON parsing or JSON writing code; for JSON slabs, this crate only works with raw bytes and leaves the parsing / placeholder substitution to the consumer.

See FORMAT.md in the repo root for the on-disk layout.

Use Builder for writing and ParsedFile for reading.

§Writing

use json_slabs::Builder;

let mut b = Builder::new();
let numbers = b.add_slab(&[10i32, 20, 30]);
let sub_json = b.add_json_slab(br#"["hello", "world"]"#.to_vec());
// `{:#}` on a placeholder prints the whole `{"$s": N}` reference.
let skeleton = format!(r#"{{"numbers":{numbers:#},"splitOutArray":{sub_json:#}}}"#);
let bytes = b.finish(skeleton.as_bytes());

§Reading

use json_slabs::{ParsedFile, SlabPlaceholder};

let parsed = ParsedFile::parse(&bytes).unwrap();
// The root JSON slab (as raw JSON bytes).
let _root: &[u8] = parsed.root_json_bytes();
// Read a typed slab back. `SlabPlaceholder(1)` here matches the
// `{"$s": 1}` placeholder found in the root JSON; in practice
// you'd parse the JSON and get the slab index from the parsed
// placeholder.
let numbers_back: Vec<i32> = parsed.read(SlabPlaceholder(1)).unwrap();
assert_eq!(numbers_back, vec![10, 20, 30]);

Structs§

Builder
Create a JsonSlabs (JSLB) file for writing.
Header
Decoded form of the 20-byte fixed header.
ParsedFile
The JSLB file contents, parsed from a slice of bytes.
RootJsonReader
Streaming reader exposing only the root JSON slab of a JSLB byte stream.
SlabBytes
A reference to a slice of slab bytes, annotated with the slab type.
SlabDirectory
Low-level alternative to ParsedFile. A SlabDirectory consumes the entire front-part of the file, including the header.
SlabPlaceholder
A reference to a slab by its index in the file’s slab table.
SlabTableEntry
One slab-table entry, decoded but not yet bound to file/buffer data.

Enums§

DecodeError
Error from ParsedFile::parse and the ParsedFile::read* resolvers.
ParseError
Error reading the fixed header, slab table, or slab data extents. Returned by Header::parse, SlabTableEntry::parse, and ParsedFile::parse.
SlabType
The type of a slab, as stored in the file.

Constants§

FIXED_HEADER_SIZE
Size of the fixed file header in bytes.
MAGIC
Magic bytes at the start of every .jslb file.
SLAB_REF_KEY
The object key that marks a slab reference in a JSON slab.
SLAB_TABLE_ENTRY_SIZE
Size of one slab-table entry in bytes. These entries immediately follow the file header.
VERSION
On-disk format version this crate reads and writes.

Traits§

SlabPrimitive
Numeric primitive that can appear as the element type of a typed-array slab, implemented by i8, u8, i16, etc.
StreamedSlab
A slab whose bytes are produced lazily at write time, for use with Builder::add_streamed_slab`.