Examples

All examples assume:

#include <ikvxx/ikvxx.hpp>

See iKv2 Text Examples for complete text-file examples matching these C++ workflows.

Player save

ikv::Value save(ikv::objectValue, "player_save");
save["version"] = 2;
save["timestamp"] = std::int64_t{1712345678};

auto player = save.makeObject("player");
player["name"] = "Ada";
player["health"] = 95;
player["speed"] = 7.5;
player["alive"] = true;

auto inventory = save.makeArray("inventory", ikv::stringValue);
inventory.append("wrench");
inventory.append("battery");

save.write("player.ikv");
save.writeBinary("player.ikvb");

Read with validation

auto save = ikv::Value::load("player.ikv");

if (!save.isObject() || !save.isMember("player"))
    throw std::runtime_error("invalid save");

auto player = save["player"];
if (!player["name"].isString() || !player["health"].isInt())
    throw std::runtime_error("invalid player");

std::string name = player["name"].asString();
int health = player["health"].asInt();

Default object

ikv::Value fallback(ikv::objectValue, "defaults");
fallback["enabled"] = false;

const ikv::Value& config = root;
auto feature = config.get("feature", fallback);
bool enabled = feature["enabled"].asBool();

Mixed event list

ikv::Value log(ikv::objectValue, "events");
auto values = log.makeArray("values");
values.append("started");
values.append(std::int64_t{42});
values.append(true);
values.append(3.5);

Object array

ikv::Value root;
auto users = root.makeArray("users", ikv::objectValue);

for (int i = 0; i < 3; ++i) {
    auto user = users.appendObject();
    user["id"] = i;
    user["active"] = (i % 2 == 0);
}

for (ikv::Value::ArrayIndex i = 0; i < users.size(); ++i) {
    int id = users[i]["id"].asInt();
}

Network binary round trip

std::vector<std::uint8_t> encoded = root.toBinary();
send(encoded.data(), encoded.size());

std::vector<std::uint8_t> received = receive();
auto decoded = ikv::Value::fromBinary(received.data(), received.size());

Hot reload

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

while (running) {
    if (fileChanged("settings.ikv")) {
        try {
            settings.refresh("settings.ikv");
        } catch (const ikv::Error& error) {
            // Existing settings remain intact.
        }
    }
}

Complete settings program

#include <ikvxx/ikvxx.hpp>

#include <iostream>

int main()
{
    try {
        ikv::Value settings(ikv::objectValue, "settings");
        settings["fullscreen"] = true;
        settings["width"] = 1920;
        settings["height"] = 1080;

        auto audio = settings.makeObject("audio");
        audio["volume"] = 0.8;
        audio["muted"] = false;

        settings.write("settings.ikv");

        const auto loaded = ikv::Value::load("settings.ikv");
        std::cout << loaded["width"].asInt() << 'x'
                  << loaded["height"].asInt() << '\n';
        return 0;
    } catch (const ikv::Error& error) {
        std::cerr << "iKv error: " << error.what() << '\n';
        return 1;
    }
}

Parse embedded iKv2 text

const std::string source = R"ikv(
ikv2 "feature_flags"
{
    "new_menu" true
    "max_items" 25
    "label" "Preview"
}
)ikv";

auto flags = ikv::Value::parse(source);
bool show_new_menu = flags["new_menu"].asBool();
int max_items = flags["max_items"].asInt();

Inspect values before reading

auto config = ikv::Value::load("config.ikv");

if (config["host"].isString()) {
    std::string host = config["host"].asString();
}

if (config["port"].isInt()) {
    int port = config["port"].asInt();
}

if (config["tls"].isBool()) {
    bool tls = config["tls"].asBool();
}

Read a typed array

auto document = ikv::Value::load("scores.ikv");
auto scores = document["scores"];

if (!scores.isArray())
    throw std::runtime_error("scores must be an array");

std::int64_t total = 0;
for (ikv::Value::ArrayIndex i = 0; i < scores.size(); ++i)
    total += scores[i].asInt64();

Pass read-only values to helpers

void printPlayer(const ikv::Value& player)
{
    std::cout << player["name"].asString()
              << ": " << player["score"].asInt() << '\n';
}

auto save = ikv::Value::load("save.ikv");
printPlayer(save["player"]);

Write both format versions

ikv::Value root(ikv::objectValue, "compatibility");
root["message"] = "hello";

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

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

Handle missing members

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

if (!settings.isMember("language"))
    settings["language"] = "en-US";

if (settings["telemetry"].isNull())
    settings["telemetry"] = false;

settings.write("settings.ikv");

Examples

Player save

Read with validation

Default object

Mixed event list

Object array

Network binary round trip

Hot reload

Complete settings program

Parse embedded iKv2 text

Inspect values before reading

Read a typed array

Pass read-only values to helpers

Write both format versions

Handle missing members

iKvxx Wiki

Format Reference

C++ API

Development