Skip to main content
The zon-lib crate provides the core primitives for zero-copy reading and writing.

​
Installation

Cargo.toml
[dependencies]
zon-lib = "0.1.0"

​
ZonWriter

bulder-pattern struct for creating ZON binaries. It manages the byte buffer and ensures 64-byte alignment.

​
Constructor

​
new()
fn
Creates a new writer with an empty buffer.
let mut writer = ZonWriter::new();

​
Writing Primitives

​
write_u32(val: u32) -> u32
fn
Writes a 32-bit unsigned integer to the buffer.Returns: The offset (pointer) to the written value.
let offset = writer.write_u32(42);
​
write_string(val: &str) -> u32
fn
Writes a UTF-8 string to the buffer, prefixed by its length.Returns: The offset (pointer) to the length prefix.
let offset = writer.write_string("Hello World");

​
Finalizing

​
set_root(offset: u32)
fn
Sets the entry point of the ZON file. This writes the offset into the file header.Critical: Every ZON file must have a root set before it is valid.
writer.set_root(string_offset);
​
as_bytes() -> &[u8]
fn
Returns the underlying byte slice. Use this to write the file to disk.

​
ZonReader

Zero-copy reader that wraps a byte slice.

​
Constructor

​
new(buffer: &[u8]) -> Result<Self, &'static str>
fn
Validates the file header (Magic bytes ZON1) and creates a reader.Note: This operation is O(1). It does not scan the file.
let reader = ZonReader::new(buffer)?;

​
Reading Primitives

​
read_u32(offset: u32) -> Result<u32, &'static str>
fn
Reads a u32 from the absolute offset.
let val = reader.read_u32(offset)?;
​
read_string(offset: u32) -> Result<&str, &'static str>
fn
Reads a string from the offset. Returns a &str reference pointing directly into the original buffer (Zero-Copy).
let val = reader.read_string(offset)?;

​
Advanced: Nested Structures

To write a “Struct”, you simply write its fields first, then write pointers to them. 
// Simulating: struct User { id: u32, name: String }

// 1. Write the leaf data
let name_off = writer.write_string("Alice");
let id_off   = writer.write_u32(101);

// 2. Write the struct (just a sequence of pointers)
let struct_start = writer.len() as u32;
writer.write_u32(id_off);
writer.write_u32(name_off);

// 3. Set root to the struct start
writer.set_root(struct_start);