UCE Docs / DValue

Signature

DValue

DValue is UCE's general-purpose structured value type. It is the runtime's default container for nested data such as configuration trees, call payloads, decoded JSON, connection state, and metadata returned by runtime helpers.

Value Kinds

DValue can hold:

  • String

  • f64

  • bool

  • pointer values

  • nested child DValue values in a map-shaped container

Map-shaped DValue values can also represent list-like data when their keys are numeric strings in sequence.

Where It Appears

You will encounter DValue throughout the runtime, especially in:

  • context.cfg

  • context.props

  • context.connection

  • json_decode() results

  • unit_call() return values

  • unit_info()

Reading Values

  • ["key"] accesses or creates a child node.

  • .has("key") checks whether a child exists without creating it.

  • .key("key") returns a child pointer when it already exists.

  • .get_or_create("key") returns a child pointer and creates it when missing.

  • .get_by_path("a/b/c") traverses nested children without creating missing keys.

  • .to_string(default) reads scalar content as text.

  • .to_s64(default), .to_u64(default), and .to_f64(default) perform best-effort numeric conversion.

  • .to_bool(default) performs best-effort boolean conversion.

  • .to_stringmap() converts a map-shaped tree into StringMap.

All read accessors are const and never modify the tree; they work directly on const DValue& values such as each() callback parameters. Every to_* conversion takes an optional default that is returned when the value is missing or cannot be converted — see the individual pages (2_DValue_to_string, 2_DValue_to_s64, 2_DValue_to_u64, 2_DValue_to_f64, 2_DValue_to_bool) for the exact rules:

operator[] creates missing entries, just like std::map. .has() and .key() are the non-mutating lookup helpers, and .get_by_path() is the non-creating traversal helper.

json_decode() currently stores JSON numbers as string-valued DValue nodes, so typed numeric conversion is the normal way to consume those values.

References are dereferenced automatically in most normal reads.

Conversion Rules

  • Scalar-looking strings are trimmed before numeric and boolean parsing.

  • .to_bool() understands common textual forms such as true, false, yes, no, 1, and 0.

  • bool values convert numerically to 1 and 0.

  • Pointer values convert numerically when read as numbers.

  • Single-value maps can act as scalar wrappers for numeric and boolean conversion.

  • Missing values and invalid numeric input fall back to the accessor's default_value argument (0, "", or false when not given).

  • .to_stringmap() converts map children key-by-key using each child's to_string().

Writing Values

Common mutating helpers include:

  • .set(String)

  • .set(f64)

  • .set_bool(bool)

  • .set(StringMap)

  • .set_array()

  • .push(...)

  • .pop()

  • .remove(key)

  • .clear()

Use .set_array() when you want list-style behavior with push() and pop().

Inspection Helpers

Useful inspection helpers include:

  • .has(key)

  • .key(key)

  • .get_or_create(key)

  • .get_type_name()

  • .is_array()

  • .is_list()

  • .to_json()

each()

each(std::function<void (const DValue& t, String key)> f) iterates over the current tree value (see 2_DValue_each for details).

For map-shaped DValue values, the callback runs once per child entry and receives:

  • t as the child value, by const reference (no copy)

  • key as the child key

For non-map values, each() still invokes the callback once:

  • t is the current value

  • key is an empty string

Examples

Example

DValue user;
user["name"] = "Ada";
user["active"] = true;
print(user["name"].to_string(), "\n");
Output
Ada