Ownership, Errors, and Limits

Shared tree ownership

ikv::Value is a lightweight handle backed by shared ownership of the root C node:

auto root = ikv::Value::load("data.ikv");
auto copy = root;
auto child = root["child"];

root, copy, and child keep the same tree alive. Copying does not deep-clone data.

Handle invalidation

A child handle points at a node inside the shared tree. Reacquire it after:

replacing that member with scalar assignment
replacing it with makeObject or makeArray
refreshing the root

Do not dereference a stale child handle.

Const behavior

A handle derived through a const root is read-only. Mutation attempts throw ikv::Error, including mutations through nested temporary handles.

Exceptions

ikv::Error derives from std::runtime_error and reports:

parse failures
file open/read/write failures
incompatible value types
unsupported root or array structure
typed-array append rejection
invalid mutation targets
refresh failures

Standard exceptions are used where they are more precise:

std::out_of_range for invalid array indexes
std::out_of_range when asInt() cannot represent an int64_t

try {
    auto root = ikv::Value::load("settings.ikv");
    int width = root["width"].asInt();
} catch (const ikv::Error& error) {
    // Parse, I/O, or type error.
} catch (const std::out_of_range& error) {
    // Index or integer-range error.
}

Current API limits

Roots constructed through iKvxx must be objects or arrays.
The iKv2 indexed binary writer requires an object root.
Arrays of arrays cannot be built through the current public C API.
Existing array elements cannot be replaced in place.
Value-to-Value structural assignment is deleted.
Object iteration is not exposed because the public C API does not expose key iteration.
Null scalar assignment is not exposed by the current C mutation API.

These constraints are explicit: operations throw or fail to compile instead of silently producing an incomplete tree.

Ownership, Errors, and Limits

Shared tree ownership

Handle invalidation

Const behavior

Exceptions

Current API limits

iKvxx Wiki

Format Reference

C++ API

Development