Parsing and Serialization

Text input

static Value parse(const std::string& text);
static Value load(const std::string& path);

Both methods auto-detect iKv1 and iKv2. parse reads an in-memory string; load reads a text file.

auto memory = ikv::Value::parse(R"(
ikv2 "settings"
{
    "enabled" true
}
)");

auto file = ikv::Value::load("settings.ikv");

Binary input

static Value fromBinary(const void* data, std::size_t size);
static Value loadBinary(const std::string& path);

The parsed tree owns or copies all data required after the call returns. The caller may release its source buffer.

std::vector<std::uint8_t> bytes = receiveData();
auto value = ikv::Value::fromBinary(bytes.data(), bytes.size());

Text output

void write(const std::string& path,
           ikv::Version version = ikv::Version::v2) const;

root.write("current.ikv");
root.write("legacy.ikv", ikv::Version::v1);

Binary output

void writeBinary(const std::string& path,
                 ikv::Version version = ikv::Version::v2) const;

std::vector<std::uint8_t> toBinary(
    ikv::Version version = ikv::Version::v2) const;

root.writeBinary("current.ikvb");
auto bytes = root.toBinary();
auto legacy = root.toBinary(ikv::Version::v1);

Refresh

void refresh(const std::string& path);

Refresh replaces an existing root in place from a text or binary path. Format detection is automatic.

auto settings = ikv::Value::load("settings.ikv");
auto shared = settings;

settings.refresh("updated-settings.ikvb");
// shared observes the same refreshed root.

Rules:

Only a mutable root handle can be refreshed.
A failed refresh preserves the existing tree.
Reacquire child handles after refresh.
Other root copies continue sharing the refreshed tree.

Version selection

enum class Version : unsigned { v1 = 1, v2 = 2 };

Version arguments affect output only. Input functions detect the version from text tags or binary headers.

Parsing and Serialization

Text input

Binary input

Text output

Binary output

Refresh

Version selection

iKvxx Wiki

Format Reference

C++ API

Development