cjson-bindings 0.5.0

Safe Rust bindings for the cJSON library - a lightweight JSON parser in C with support for JSON Pointer (RFC6901), JSON Patch (RFC6902), and JSON Merge Patch (RFC7386)
Documentation

cjson-bindings

Safe Rust bindings for the cJSON library - a lightweight JSON parser in C.

Overview

cjson-bindings provides idiomatic, safe Rust wrappers around the cJSON C library, offering:

  • Safe API: Memory-safe wrappers with automatic resource management (RAII)
  • Type-safe operations: Strong typing with Result types for error handling
  • JSON Pointer support (RFC6901): Navigate JSON documents using JSON Pointer syntax
  • JSON Patch support (RFC6902): Generate and apply JSON patches
  • JSON Merge Patch support (RFC7386): Generate and apply merge patches
  • no_std compatible: Suitable for embedded systems with built-in allocator and panic handler

Embedded & no_std Support

The library is designed for embedded systems and supports no_std environments:

  • Global Allocator: Uses C's malloc/free via FFI
  • Default Panic Handler: Provides a simple infinite loop panic handler
  • Custom Panic Handler: Use the disable_panic feature to provide your own

Cargo Features

  • std: Enables standard library support (required for tests)
  • disable_panic: Disables both the default allocator and panic handler, allowing you to provide your own

Example with custom allocator and panic handler:

[dependencies]
cjson-bindings = { version = "0.5.0", features = ["disable_panic"] }

Then provide your own in your application:

use core::alloc::{GlobalAlloc, Layout};

struct MyAllocator;

unsafe impl GlobalAlloc for MyAllocator {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        // Your custom allocation
    }
    
    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        // Your custom deallocation
    }
}

#[global_allocator]
static ALLOCATOR: MyAllocator = MyAllocator;

#[panic_handler]
fn my_panic(_info: &core::panic::PanicInfo) -> ! {
    // Your custom panic handling
    loop {}
}

Features

Core JSON Operations

  • Parse and print JSON with automatic memory management
  • Create and manipulate JSON objects, arrays, strings, numbers, booleans, and null values
  • Type checking and value retrieval with compile-time safety
  • Deep cloning and comparison

Advanced Features

  • JSON Pointer (RFC6901): Navigate JSON structures using paths like /foo/bar/0
  • JSON Patch (RFC6902): Generate and apply patch operations (add, remove, replace, move, copy, test)
  • JSON Merge Patch (RFC7386): Simpler patch format for common use cases
  • Sorting object keys alphabetically

Usage

Basic Example

use cjson_rs::{CJson, CJsonResult};

fn main() -> CJsonResult<()> {
    // Parse JSON
    let json = CJson::parse(r#"{"name": "John", "age": 30}"#)?;
    
    // Access values
    let name = json.get_object_item("name")?;
    println!("Name: {}", name.get_string_value()?);
    
    // Create new JSON
    let mut obj = CJson::create_object()?;
    obj.add_string_to_object("city", "New York")?;
    obj.add_number_to_object("population", 8_000_000.0)?;
    
    // Print JSON
    println!("{}", obj.print()?);
    
    Ok(())
}

JSON Pointer Example

use cjson_rs::{CJson, JsonPointer};

let json = CJson::parse(r#"{
    "users": [
        {"name": "Alice", "age": 25},
        {"name": "Bob", "age": 30}
    ]
}"#)?;

// Navigate using JSON Pointer
let bob = JsonPointer::get(&json, "/users/1/name")?;
println!("User: {}", bob.get_string_value()?); // "Bob"

JSON Patch Example

use cjson_rs::{CJson, JsonPatch};

let mut original = CJson::parse(r#"{"name": "John", "age": 30}"#)?;
let patches = CJson::parse(r#"[
    {"op": "replace", "path": "/age", "value": 31},
    {"op": "add", "path": "/city", "value": "NYC"}
]"#)?;

// Apply patches
JsonPatch::apply(&mut original, &patches)?;
println!("{}", original.print()?);
// Output: {"name":"John","age":31,"city":"NYC"}

JSON Merge Patch Example

use cjson_rs::{CJson, JsonMergePatch};

let mut target = CJson::parse(r#"{"name": "John", "age": 30}"#)?;
let patch = CJson::parse(r#"{"age": 31, "city": "NYC"}"#)?;

// Apply merge patch
let result = JsonMergePatch::apply(&mut target, &patch)?;
println!("{}", result.print()?);

API Types

Main Types

  • CJson: Owned JSON value with automatic memory management
  • CJsonRef: Borrowed reference to a JSON value (non-owning)
  • CJsonResult<T>: Result type for operations that can fail
  • CJsonError: Error enumeration for all possible errors

Utility Types

  • JsonPointer: JSON Pointer (RFC6901) operations
  • JsonPatch: JSON Patch (RFC6902) operations
  • JsonMergePatch: JSON Merge Patch (RFC7386) operations
  • JsonUtils: Additional utilities (e.g., sorting)

Error Handling

All operations that can fail return CJsonResult<T>, which is a type alias for Result<T, CJsonError>:

pub enum CJsonError {
    ParseError,
    NullPointer,
    InvalidUtf8,
    NotFound,
    TypeError,
    AllocationError,
    InvalidOperation,
}

Memory Safety

cjson-bindings ensures memory safety through:

  • RAII: CJson automatically frees memory when dropped
  • No manual memory management: All allocations/deallocations are handled automatically
  • Reference types: CJsonRef provides safe borrowing without ownership transfer
  • Clear ownership: into_raw() for explicit ownership transfer when needed

Dependencies

This crate links against the cJSON C library. You need to have cJSON installed or provide it as part of your build process.

License

This Rust wrapper is licensed under the GNU General Public License v3.0 (GPL-3.0).

The underlying cJSON library is licensed under the MIT License.

cJSON License

Copyright (c) 2009-2017 Dave Gamble and cJSON contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

See LICENSE for the full GPL-3.0 license text and cJSON's license for details.

Testing

The library includes comprehensive unit tests covering all major functionality. To run the tests:

cargo test --features std

Or use the provided alias:

cargo test-std

See TESTS.md for detailed test documentation and coverage information.

Test Requirements

  • cJSON library installed on your system (libcjson and libcjson_utils)
  • Standard library support (enabled via the std feature for testing)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

References