std/json

March 14, 2026 · View on GitHub

The std/json module provides a DOM-style JSON parser and builder implementation for Zen-C. It features a simple API for creating, manipulating, and serializing JSON data with automatic memory management.

Overview

DOM-style: Hierarchical tree structure of JsonValue nodes.
Type-safe Accessors: Check types (is_string, is_number) and unwrap values safely.
Automatic Cleanup: Implements the Drop trait for automatic, recursive memory management.
Standards Compliant: Supports standard JSON types including objects, arrays, strings, numbers, booleans, and null.

Usage

import "std/json.zc"

fn main() {
    // Building JSON
    let obj = JsonValue::object();
    obj.set("name", JsonValue::string("Alice"));
    obj.set("age", JsonValue::number(30.0));
    obj.set("active", JsonValue::bool(true));
    
    // Serialization
    let json_str = obj.to_string();
    println "Serialized: {json_str}";
    
    // Parsing
    let input = "{\"score\": 100}";
    match JsonValue::parse(input) {
        Ok(parsed) => {
            println "Score: {parsed.get(\"score\").unwrap().as_int().unwrap()}";
            // parsed is freed automatically when this block ends
        }
        Err(e) => println "Error: {e}"
    }
} // obj is freed automatically here

Struct Definition

struct JsonValue {
    kind: JsonType;
    // ... internal fields
}

Methods

Construction

Method	Signature	Description
null	`JsonValue::null() -> JsonValue`	Creates a null value.
bool	`JsonValue::bool(b: bool) -> JsonValue`	Creates a boolean value.
number	`JsonValue::number(n: double) -> JsonValue`	Creates a numeric value.
string	`JsonValue::string(s: char*) -> JsonValue`	Creates a string value.
array	`JsonValue::array() -> JsonValue`	Creates an empty JSON array.
object	`JsonValue::object() -> JsonValue`	Creates an empty JSON object.

Parsing

Method	Signature	Description
parse	`JsonValue::parse(json: char) -> Result<JsonValue>`	Parses a JSON string into a heap-allocated tree.

Accessors

Method	Signature	Description
is_null	`is_null(self) -> bool`	Returns true if the type is null.
is_bool	`is_bool(self) -> bool`	Returns true if the type is boolean.
is_number	`is_number(self) -> bool`	Returns true if the type is a number.
is_string	`is_string(self) -> bool`	Returns true if the type is a string.
is_array	`is_array(self) -> bool`	Returns true if the type is an array.
is_object	`is_object(self) -> bool`	Returns true if the type is an object.
as_string	`as_string(self) -> Option<char*>`	Returns the string pointer if applicable.
as_int	`as_int(self) -> Option<int>`	Returns the integer value if applicable.
as_float	`as_float(self) -> Option<double>`	Returns the numeric value if applicable.
as_bool	`as_bool(self) -> Option<bool>`	Returns the boolean value if applicable.

Modification

Method	Signature	Description
push	`push(self, val: JsonValue)`	Appends a child value to a JSON array.
set	`set(self, key: char*, val: JsonValue)`	Inserts or updates a key-value pair in a JSON object.
get	`get(self, key: char) -> Option<JsonValue>`	Retrieves a child value from an object by key.
at	`at(self, index: usize) -> Option<JsonValue*>`	Retrieves a child value from an array by index.

Serialization

Method	Signature	Description
to_string	`to_string(self) -> String`	Returns a serialized JSON string.

Memory Management

Method	Signature	Description
free	`free(self)`	Recursively frees the value and all descendant nodes.
Trait	`impl Drop for JsonValue`	Automatically triggers recursive `free()` when out of scope.