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.
- Parsed
File - The JSLB file contents, parsed from a slice of bytes.
- Root
Json Reader - Streaming reader exposing only the root JSON slab of a JSLB byte stream.
- Slab
Bytes - A reference to a slice of slab bytes, annotated with the slab type.
- Slab
Directory - Low-level alternative to
ParsedFile. ASlabDirectoryconsumes the entire front-part of the file, including the header. - Slab
Placeholder - A reference to a slab by its index in the file’s slab table.
- Slab
Table Entry - One slab-table entry, decoded but not yet bound to file/buffer data.
Enums§
- Decode
Error - Error from
ParsedFile::parseand theParsedFile::read*resolvers. - Parse
Error - Error reading the fixed header, slab table, or slab data extents.
Returned by
Header::parse,SlabTableEntry::parse, andParsedFile::parse. - Slab
Type - 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
.jslbfile. - 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§
- Slab
Primitive - Numeric primitive that can appear as the element type of a
typed-array slab, implemented by
i8,u8,i16, etc. - Streamed
Slab - A slab whose bytes are produced lazily at write time, for use
with
Builder::add_streamed_slab`.