yyjson.rs

Overview

The [yyjson.rs](/projects/287/67743) file provides Rust FFI (Foreign Function Interface) bindings and related data structures for interacting with the underlying `yyjson` C library, a high-performance JSON parser and writer. The primary purpose of this file is to define the low-level Rust representations of core `yyjson` types and provide access to crucial functions for JSON reading and memory management via unsafe extern C calls.

This file exposes:

• Memory allocator customization structures (yyjson_alc).

• JSON value and document representations (yyjson_val, yyjson_doc).

• Error reporting during JSON read operations (yyjson_read_err).

• Constants and type aliases for read status codes.

• Function signatures for reading JSON documents and initializing memory pools.

The functionality in this file enables Rust code to utilize `yyjson`'s fast parsing capabilities with control over memory allocation, error handling, and document lifecycle management.

Detailed Documentation

Structs

yyjson_alc

#[repr(C)]
pub(crate) struct yyjson_alc {
    pub malloc: Option<unsafe extern "C" fn(ctx: *mut c_void, size: usize) -> *mut c_void>,
    pub realloc: Option<unsafe extern "C" fn(ctx: *mut c_void, ptr: *mut c_void, size: usize) -> *mut c_void>,
    pub free: Option<unsafe extern "C" fn(ctx: *mut c_void, ptr: *mut c_void)>,
    pub ctx: *mut c_void,
}

• Purpose: Defines a customizable memory allocator interface for yyjson. This allows the user to provide custom malloc, realloc, and free implementations, along with a context pointer (ctx).

• Fields:

  • malloc: Optional function pointer for allocating memory.

  • realloc: Optional function pointer for reallocating memory.

  • free: Optional function pointer for freeing memory.

  • ctx: User-defined context pointer passed to the allocator functions.

• Usage Example:

extern "C" fn my_malloc(ctx: *mut c_void, size: usize) -> *mut c_void {
    // Custom allocation logic here
}

extern "C" fn my_free(ctx: *mut c_void, ptr: *mut c_void) {
    // Custom free logic here
}

let alc = yyjson_alc {
    malloc: Some(my_malloc),
    realloc: None,
    free: Some(my_free),
    ctx: std::ptr::null_mut(),
};

yyjson_read_code

pub(crate) type yyjson_read_code = u32;
pub(crate) const YYJSON_READ_SUCCESS: yyjson_read_code = 0;

• Purpose: Alias for the JSON read status code.

• YYJSON_READ_SUCCESS indicates successful parsing (code 0).

yyjson_read_err

#[repr(C)]
pub(crate) struct yyjson_read_err {
    pub code: yyjson_read_code,
    pub msg: *const c_char,
    pub pos: usize,
}

• Purpose: Represents an error encountered during JSON parsing.

• Fields:

  • code: Error code indicating the type of error.

  • msg: Pointer to a null-terminated C string describing the error.

  • pos: Byte position in the JSON input where the error occurred.

• Usage: Passed to yyjson_read_opts to receive detailed error information on failure.

yyjson_val_uni (Union)

#[repr(C)]
pub(crate) union yyjson_val_uni {
    pub u64_: u64,
    pub i64_: i64,
    pub f64_: f64,
    pub str_: *const c_char,
    pub ptr: *mut c_void,
    pub ofs: usize,
}

• Purpose: Internal union representing the variant data of a JSON value.

• Variants:

  • u64_: Unsigned 64-bit integer.

  • i64_: Signed 64-bit integer.

  • f64_: 64-bit floating-point number.

  • str_: Pointer to a C string (for JSON strings).

  • ptr: Generic pointer (used internally).

  • ofs: Offset (used internally).

• Usage: Used inside yyjson_val to store the actual data of a JSON value.

yyjson_val

#[repr(C)]
pub(crate) struct yyjson_val {
    pub tag: u64,
    pub uni: yyjson_val_uni,
}

• Purpose: Represents a JSON value in the yyjson library.

• Fields:

  • tag: Encodes the type of JSON value and other metadata.

  • uni: Union containing the actual data for the value.

• Notes: The tag field helps determine the value type (e.g., number, string, array, object) and how to interpret the union data.

yyjson_doc

#[repr(C)]
pub(crate) struct yyjson_doc {
    pub root: *mut yyjson_val,
    pub alc: yyjson_alc,
    pub dat_read: usize,
    pub val_read: usize,
    pub str_pool: *mut c_char,
}

• Purpose: Represents a parsed JSON document.

• Fields:

  • root: Pointer to the root JSON value (yyjson_val) of the document.

  • alc: Allocator used by this document.

  • dat_read: Number of bytes read from input.

  • val_read: Number of JSON values read.

  • str_pool: Pointer to the internal string pool used to store JSON strings.

• Usage: Returned by yyjson_read_opts to represent the entire parsed JSON document.

Functions (Unsafe Extern "C")

yyjson_read_opts

pub unsafe extern "C" fn yyjson_read_opts(
    dat: *mut c_char,
    len: usize,
    alc: *const yyjson_alc,
    err: *mut yyjson_read_err,
) -> *mut yyjson_doc;

• Purpose: Parses a JSON document from a mutable character buffer with options for custom allocator and error reporting.

• Parameters:

  • dat: Pointer to JSON data buffer (mutable).

  • len: Length of the JSON data in bytes.

  • alc: Pointer to a yyjson_alc allocator struct (can be null for default allocator).

  • err: Pointer to a yyjson_read_err struct to receive error info (can be null).

• Returns: Pointer to a newly allocated yyjson_doc if successful; null pointer on failure.

• Usage Example:

let mut error = yyjson_read_err {
    code: 0,
    msg: std::ptr::null(),
    pos: 0,
};
let doc_ptr = unsafe {
    yyjson_read_opts(json_buffer_ptr, json_len, &alc as *const yyjson_alc, &mut error as *mut _)
};
if doc_ptr.is_null() {
    eprintln!("Parse error at position {}: {:?}", error.pos, CStr::from_ptr(error.msg));
} else {
    // Use doc_ptr
}

yyjson_alc_pool_init

pub unsafe extern "C" fn yyjson_alc_pool_init(
    alc: *mut yyjson_alc,
    buf: *mut c_void,
    size: usize,
) -> bool;

• Purpose: Initializes a memory pool allocator for yyjson with a pre-allocated buffer.

• Parameters:

  • alc: Mutable pointer to a yyjson_alc struct to initialize.

  • buf: Pointer to a memory buffer to be used as the pool.

  • size: Size of the buffer in bytes.

• Returns: true if initialization succeeded, false otherwise.

• Usage: Useful for high-performance or embedded scenarios where memory allocations must be tightly controlled.

Important Implementation Details

• Memory Management:
  yyjson_alc allows users to plug in custom memory allocation strategies. The allocator functions are unsafe C function pointers and require careful management to avoid undefined behavior.

• Data Representation:
  The yyjson_val struct employs a tagged union pattern (tag + uni) to represent multiple JSON value types efficiently in a compact memory layout.

• Error Handling:
  Parsing errors are communicated via the yyjson_read_err struct, enabling the caller to inspect error codes, messages, and positions for robust error reporting.

• FFI Safety:
  All exposed functions and data structures use #[repr(C)] to ensure ABI compatibility with the C library. The functions are declared unsafe due to raw pointer usage and the potential for invalid memory access.

Interaction with Other System Components

• This file acts as the Rust layer for the underlying C yyjson library, enabling JSON parsing functionality in Rust applications that require high-performance JSON processing.

• Higher-level Rust wrappers or safe abstractions may be built on top of these definitions to provide ergonomic APIs.

• The allocator structures can be integrated with Rust's custom allocator traits or external memory pools.

• The parsed JSON document (yyjson_doc) can be traversed or manipulated by other modules responsible for JSON data handling, validation, or serialization.

Visual Diagram

classDiagram
    class yyjson_alc {
        +malloc(ctx: *mut c_void, size: usize) -> *mut c_void
        +realloc(ctx: *mut c_void, ptr: *mut c_void, size: usize) -> *mut c_void
        +free(ctx: *mut c_void, ptr: *mut c_void)
        +ctx: *mut c_void
    }

    class yyjson_read_err {
        +code: yyjson_read_code
        +msg: *const c_char
        +pos: usize
    }

    class yyjson_val_uni {
        +u64_: u64
        +i64_: i64
        +f64_: f64
        +str_: *const c_char
        +ptr: *mut c_void
        +ofs: usize
    }

    class yyjson_val {
        +tag: u64
        +uni: yyjson_val_uni
    }

    class yyjson_doc {
        +root: *mut yyjson_val
        +alc: yyjson_alc
        +dat_read: usize
        +val_read: usize
        +str_pool: *mut c_char
    }

    classFunctions <|.. yyjson_alc : uses
    yyjson_doc --> yyjson_val : root
    yyjson_val --> yyjson_val_uni : contains

    %% Functions
    class yyjson_functions {
        +yyjson_read_opts(dat: *mut c_char, len: usize, alc: *const yyjson_alc, err: *mut yyjson_read_err) -> *mut yyjson_doc
        +yyjson_alc_pool_init(alc: *mut yyjson_alc, buf: *mut c_void, size: usize) -> bool
    }

Summary

The [yyjson.rs](/projects/287/67743) file provides essential low-level Rust bindings to the `yyjson` C library, wrapping its core data structures, error handling, and memory allocation interfaces. It enables Rust programs to efficiently parse JSON data with customizable memory management, exposing raw pointers and unsafe functions that facilitate high-performance JSON processing in Rust applications.