nested_map

Overview

A cbeam::container::nested_map<Key, Value> is a hierarchical data structure suited for configuration trees, DOM-like data, or JSON-like representations. It maintains:

  • A map of keys to values (data).
  • A map of keys to further nested maps (sub_tables).

You can think of it as a “tree” of maps, allowing you to nest data arbitrarily deep. Typical use cases include configuration trees, serialization of complex data (e.g., JSON-like structures), or interprocess data sharing.

With Cbeam’s serialization and JSON modules, you can serialize nested_map in two ways:

  1. Binary or stable reference (via cbeam::serialization), suitable for interprocess or on-disk storage.
  2. JSON-like text (via cbeam::json), which generates a textual, brace-and-comma-based representation.

Below we outline both approaches, with extended examples.

Quick Recap of Basic Usage

#include <cbeam/container/nested_map.hpp>

int main() {
    // A simple nested_map with string keys and values
    cbeam::container::nested_map<std::string, std::string> config;

    // 1) Store direct key-value pairs in 'data'
    config.data["username"] = "alice";
    config.data["password"] = "secret";

    // 2) Create a nested table and add to 'sub_tables'
    cbeam::container::nested_map<std::string, std::string> advanced;
    advanced.data["logging"] = "debug";
    config.sub_tables["advanced"] = advanced;

    // 3) Retrieve a value
    auto user = config.get_mapped_value_or_default<std::string>("username");
    // user == "alice"

    return 0;
}

Serialization with xpod::type

For maximum flexibility, you can use xpod::type (a std::variant<long long, double, bool, memory::pointer, std::string>) as Key and/or Value:

#include <cbeam/container/nested_map.hpp>
#include <cbeam/container/xpod.hpp>

int main() {
    using cbeam::container::xpod::type;

    // nested_map with xpod::type as both Key and Value
    cbeam::container::nested_map<type, type> xmap;

    xmap.data["foo"]   = 42LL;               // store an integer
    xmap.data[false]   = "Bar";              // store a string
    xmap.data[1.0]     = true;               // store a bool
    xmap.data["addr"]  = cbeam::memory::pointer("0xABCDE"); // store a pointer

    // sub_tables can hold further nested_map
    cbeam::container::nested_map<type, type> nested;
    nested.data["level"] = "innermost";
    xmap.sub_tables["sub"] = nested;

    return 0;
}

By including the relevant headers from cbeam::serialization (e.g., xpod.hpp, nested_map.hpp), you gain the ability to serialize and deserialize this data.

Binary or Stable Reference Serialization

Please refer to Interprocess Containers for details about Cbeam’s concept of "stable" containers.

Headers Needed

  • cbeam/serialization/nested_map.hpp
  • cbeam/serialization/xpod.hpp (if using xpod::type)

Example

#include <cbeam/container/nested_map.hpp>
#include <cbeam/container/xpod.hpp>
#include <cbeam/container/stable_reference_buffer.hpp>  // for cbeam::container::stable_reference_buffer
#include <cbeam/serialization/nested_map.hpp>           // nested_map serialization
#include <cbeam/serialization/xpod.hpp>                 // xpod::type serialization
#include <cbeam/serialization/traits.hpp>               // for cbeam::serialization::traits<>

// For demonstration
#include <cassert>
#include <iostream>

int main() {
    using cbeam::container::xpod::type;
    using NestedMap = cbeam::container::nested_map<type, type>;

    // 1) Construct a nested map
    NestedMap subTable;
    subTable.data["middle"] = 1LL;

    NestedMap root;
    root.data["outer"] = 1.0;
    root.sub_tables["inner"] = subTable;

    // 2) Serialize to a buffer
    cbeam::container::stable_reference_buffer buffer;
    cbeam::serialization::traits<NestedMap>::serialize(root, buffer);

    // 3) Deserialize from buffer
    NestedMap restored;
    auto it = (cbeam::serialization::serialized_object)buffer.get();
    cbeam::serialization::traits<NestedMap>::deserialize(it, restored);

    // 4) Validate
    assert(restored == root);
    std::cout << "Binary serialization round trip succeeded.\n";
    return 0;
}

This uses the binary-based approach. Internally, the library writes the map structure, including recursion for sub_tables. If your keys/values are xpod::type, they too are serialized according to their active variant.

JSON-Like Serialization

Cbeam also offers text-based JSON-like output via the cbeam::json module. This approach writes data as unquoted keys and values separated by colons (:) and commas (,), enclosed in braces ({}), giving a pseudo-JSON format.

Headers Needed

  • cbeam/json/nested_map.hpp
  • (If storing xpod::type as keys/values) also include cbeam/json/xpod.hpp (analogous to serialization/xpod.hpp, though you would define or adapt your own JSON printing traits for xpod::type if needed).

Example

#include <cbeam/container/nested_map.hpp>
#include <cbeam/json/nested_map.hpp>     // for the JSON-like serializer
#include <cbeam/container/buffer.hpp>    // a dynamic buffer to store text

#include <iostream>
#include <string>

int main() {
    // Suppose we have a nested_map with string keys and values
    cbeam::container::nested_map<std::string, std::string> config;
    config.data["username"] = "alice";
    config.data["password"] = "secret";

    cbeam::container::nested_map<std::string, std::string> advanced;
    advanced.data["logging"]   = "debug";
    advanced.data["verbosity"] = "high";
    config.sub_tables["advanced"] = advanced;

    // 1) Serialize to JSON-like text
    cbeam::container::buffer output;
    cbeam::json::traits<decltype(config)>::serialize(config, output);

    // 2) Convert buffer to std::string for printing
    std::string jsonLike{output.data(), output.size()};
    std::cout << "JSON-like output:\n" << jsonLike << "\n";

    return 0;
}

The above code demonstrates how you can produce a minimal, JSON string:

{username:alice,password:secret,advanced:{logging:debug,verbosity:high}}

Summary

  • Data Structure: nested_map<Key, Value> can store complex, hierarchical data of any type.
  • Binary Serialization: By including the cbeam::serialization headers, you get easy, recursive binary serialization.
  • JSON-Like Output: By including the cbeam::json headers, you can produce a bracket-and-comma-based text representation, useful for debugging or simplistic JSON-like output.
  • Integration with xpod::type: For storing heterogeneous data (ints, doubles, bools, pointers, strings), combine nested_map with xpod::type.
  • Interprocess: If needed, you can place serialized data into a shared memory segment for cross-process communication, or simply store it on disk.

Thus, nested_map offers a powerful, flexible container for tree-structured data. With the right Cbeam modules, you can serialize it either as binary or JSON-like text, making it suitable for in-memory or persistent usage scenarios.