ddn.var

struct var
class VarException VarIndexException VarKeyException VarTypeException

Types 5

classVarException : Exception

Base exception type for ddn.var runtime misuse.

Constructors
this(string msg, string file = __FILE__, size_t line = __LINE__)
classVarTypeException : VarException

Thrown when an operation requires a specific runtime var.Type.

Constructors
this(string op, var.Type expected, var.Type actual, string details = null, string file = __FILE__, size_t line = __LINE__)
classVarKeyException : VarException

Thrown when an object key is missing for an operation that requires it.

Constructors
this(string op, string key, string file = __FILE__, size_t line = __LINE__)
classVarIndexException : VarException

Thrown when an array index is out of range for an operation that requires it.

Constructors
this(string op, size_t index, size_t length, string file = __FILE__, size_t line = __LINE__)
structvar

ddn.var — a compact, dynamic value type.

Error handling strategy:

  • By default, wrong-type use of container APIs throws exceptions (e.g. indexing a non-object or

using array APIs on non-arrays). This is enforced in both debug and -release builds.

  • If compiled with version(DDN_VAR_TYPE_COERCE), var becomes permissive:
  • Mutating/ref-returning array/object APIs will auto-coerce the value to the required container

type (overwriting the previous value).

  • Read-only accessors return neutral values on mismatch (no hidden mutation).
  • In debug builds, coercions emit warnings via std.logger.
  • No I/O is performed inside this module; formatting is provided by toString().

Thread-safety notes:

  • var itself does not perform any internal synchronization. Concurrent mutation of the same

instance from multiple threads is a data race and is not supported.

  • Independent copies may be used in different threads; however, keep in mind that string is

immutable (safe to share) while arrays/maps inside var are reference-backed containers owned by each var instance.

Note

copying/assignment of var values is shallow for Type.ARRAY and Type.OBJECT (it aliases

the underlying containers). Use dup() / idup() when you need an independent deep copy.

  • Recommended patterns: message passing of var values; publishing immutable(var) snapshots; or

guarding shared access with user-provided synchronization (e.g., a Mutex).

Fields
Data _data
Type _type
private size_t _MAX_JSON_DEPTHMaximum recursion depth for JSON-like formatting to avoid runaway recursion.
private size_t _VAR_MAX_SIZESize and layout notes:
Methods
var opAssign(T)(T rhs) @safeAssign from an arbitrary value `rhs`, setting the internal type and payload accordingly.
var opIndex(string key) ref @safeAccess a child value by key, turning this instance into a map on first use.
const(var) opIndex(string key) ref const @safeConst overload of `opIndex` for read-only map access.
void opIndexAssign(T)(T rhs, string key) @safeAssign a value to a child by key (map-style assignment).
bool remove(string key) @safe Remove a child by key from the map. Returns: `true` if the key existed and was removed, `false` otherwise. When this value is `Type.NULL`, removal is a no-op and returns `false`. If this v...
void clear() @safeReset this `var` to `Type.NULL`, releasing any held resources.
var dup() const @safeCreate a deep copy of this `var`.
var idup() const @safeCreate an immutable deep copy of this `var`.
var merge(const var other, bool deepMerge = false) ref return @safeMerge another object into this one.
var opDispatch(string name)() ref @safeDynamic field access for map values via D's `opDispatch`.
const(var) opDispatch(string name)() ref const @safeConst overload of `opDispatch` for read-only access (no insertion).
private string _typeName(Type t) @safe pure nothrowGet a human-readable name for a Type value.
private void _warnCoercion(string op, Type from, Type to, string details = null) @safeEmit a debug-only warning for semantic-changing coercions.
private const(var) _nullConstRef() ref @safe nothrowA shared `NULL` value returned by reference for safe "neutral" `ref const(var)` APIs.
private void _requireType(string op, Type expected, string details = null) const @safe
private void _requireArray(string op, string details = null) const @safe
private void _requireObject(string op, string details = null) const @safe
private void _ensureArrayForMutation(string op, size_t indexHint = size_t.max) @safe
private void _ensureObjectForMutation(string op, string keyHint = null) @safe
var getField(T)(const string key, T defaultValue) const @safeSafely get a field value with a default fallback.
var get(const string key) const @safeSafely get a field value, returning NULL if missing.
var path(const string[] pathParts) const @safeAccess a nested value using an array of path components.
var path(const string pathStr) const @safeAccess a nested value using dot-notation or slash-notation path string.
ElementRange byElement() @safeGet a forward range over the elements of this array.
ConstElementRange byElement() const @safeConst overload: get a forward range over the elements of this array.
KeyRange byKey() @safeGet a forward range over the keys of this object.
ValueRange byValue() @safeGet a forward range over the values of this object.
PairRange byPair() @safeGet a forward range over the key-value pairs of this object.
string toString() const @safeConvert the stored value to a human-readable string.
void toStringTo(Sink)(ref Sink sink) if (is(typeof(sink.put("test"))) || is(typeof(sink.put('c')))) const @safeWrite the string representation of this value to an output range.
private void _toStringSink(Sink)(ref Sink sink, size_t depth) if (is(typeof(sink.put("test"))) || is(typeof(sink.put('c')))) const @safeInternal sink-based string formatter with depth tracking.
private void _toJSONStringSink(Sink)(ref Sink sink, size_t depth) if (is(typeof(sink.put("test"))) || is(typeof(sink.put('c')))) const @safeInternal JSON sink formatter for arrays and objects.
private void _toJSONElementSink(Sink)(ref Sink sink, size_t depth) if (is(typeof(sink.put("test"))) || is(typeof(sink.put('c')))) const @safeInternal JSON element sink formatter (quotes strings).
T as(T)() const @safeConvert the stored value to type `T`.
Nullable!T tryAs(T)() const @safeAttempt to convert the stored value to type `T`, returning a `Nullable!T`.
T opCall(T)() const @safeConvenience call operator that forwards to `as!T()`.
private string _escapeJSONString(const string s) @safeEscape a string for inclusion into JSON-like output.
private var _arrayElemAt(size_t index) ref @trustedIndex into the array payload and return a reference to the element.
var opIndex(size_t index) ref @safe
const(var) opIndex(size_t index) ref const @safeConst overload of `opIndex` for read-only array access.
size_t opDollar() @property const @safeSupport `$` in slice expressions for arrays.
var opSlice(size_t start, size_t end) const @safeSlice an array to create a new `var` containing a subrange of elements.
size_t length() @property const @safeGet the number of elements when the value holds an array.
void append(T)(T rhs) @safeAppend a value to the array. Converts `Type.NULL` to an empty array on first use.
void extend(T)(T rhs) @safeExtend this array with elements from another array (flat concatenation).
void opOpAssign(string op, T)(T rhs) if (op == "~") @safeOperator `~=` for append or string concatenation.
bool contains(const string key) const @safeCheck whether the map contains `key`.
var get(TDefault)(const string key, TDefault defaultValue) const @safeGet the value for `key` or return `defaultValue` if missing.
string[] keys() @property const @safeReturn an array of keys. For `Type.NULL`, returns an empty array.
var[] values() @property const @safeReturn an array of values. For `Type.NULL`, returns an empty array.
size_t count() @property const @safeNumber of key/value pairs stored. Returns 0 for `Type.NULL`.
int opApply(scope int delegate(const string, ref var) dg)Iterate over map entries as `(key, ref value)` pairs. For non-map types, iteration yields zero elements.
bool insert(T)(size_t index, T rhs) @safeInsert `rhs` at position `index` (0..length). Converts `Type.NULL` to empty array. Returns `true` on success, `false` if index is out of range.
bool removeAt(size_t index) @safeRemove the element at `index`. Returns `true` if removed, `false` if `index` is out of range or the value is `Type.NULL`. Asserts if the current type is neither `NULL` nor `ARRAY`.
int opApply(scope int delegate(ref var) dg)Foreach iteration support over array elements.
int opApply(scope int delegate(size_t, ref var) dg)Foreach iteration with index over array elements.
bool opEquals(const scope var rhs) const @trustedStructural equality.
var opBinary(string op)(const var rhs) if (op == "+" || op == "-" || op == "*" || op == "/" || op == "%") const @safeBinary arithmetic operators for `var`.
var opBinary(string op)(const var rhs) if (op == "~") const @safeString concatenation operator for `var`.
var opUnary(string op)() if (op == "-" || op == "!") const @safeUnary operators for `var`.
private bool _isNumericType(Type t) @safe pure nothrow @nogcCheck if a type is numeric (integer or floating point).
private bool _isSignedIntegerType(Type t) @safe pure nothrow @nogcCheck if a type is a signed integer type.
private bool _isUnsignedIntegerType(Type t) @safe pure nothrow @nogcCheck if a type is an unsigned integer type.
private bool _isFloatingType(Type t) @safe pure nothrow @nogcCheck if a type is floating point.
private double _toDouble() const @safeConvert the stored value to double for arithmetic.
private long _toLong() const @safeConvert the stored value to long for arithmetic.
private bool _tryToLong(out long outValue) const @safeAttempt to convert an integer value to `long` without overflow.
private bool _tryToUlong(out ulong outValue) const @safeAttempt to convert an integer value to `ulong` without wrapping.
private ulong _toUlong() const @safeConvert the stored value to `ulong` for arithmetic.
private bool _toBool() const @safeConvert the stored value to bool for logical operations.
private T _applyOp(string op, T)(T a, T b) @safe pure nothrow @nogcApply a binary arithmetic operation.
int opCmp(const var rhs) const @safeThree-way comparison operator for `var`.
private dchar _toCodePoint(const var v) @safeHelper to extract code point from char types.
size_t toHash() const @safeCompute a structural hash value consistent with `opEquals`.
private bool _floatEqual(float a, float b) @safe
private bool _doubleEqual(double a, double b) @safe
private size_t _hashCombine(size_t h, size_t v) @safe pure nothrow @nogc
private size_t _hashString(const string s) @safe pure nothrow @nogc
private size_t _hashFloat(float a) @trusted pure nothrow @nogc
private size_t _hashDouble(double a) @trusted pure nothrow @nogc
private uint _floatBits(float a) @trusted pure nothrow @nogc
private ulong _doubleBits(double a) @trusted pure nothrow @nogc
private bool _getBool() @trusted const pure nothrow @nogc
private byte _getByte() @trusted const pure nothrow @nogc
private ubyte _getUbyte() @trusted const pure nothrow @nogc
private short _getShort() @trusted const pure nothrow @nogc
private ushort _getUshort() @trusted const pure nothrow @nogc
private int _getInt() @trusted const pure nothrow @nogc
private uint _getUint() @trusted const pure nothrow @nogc
private long _getLong() @trusted const pure nothrow @nogc
private ulong _getUlong() @trusted const pure nothrow @nogc
private float _getFloat() @trusted const pure nothrow @nogc
private double _getDouble() @trusted const pure nothrow @nogc
private double _getReal() @trusted const pure nothrow @nogc
private char _getChar() @trusted const pure nothrow @nogc
private wchar _getWchar() @trusted const pure nothrow @nogc
private dchar _getDchar() @trusted const pure nothrow @nogc
private void _setBool(bool v) @trusted
private void _setByte(byte v) @trusted
private void _setUbyte(ubyte v) @trusted
private void _setShort(short v) @trusted
private void _setUshort(ushort v) @trusted
private void _setInt(int v) @trusted
private void _setUint(uint v) @trusted
private void _setLong(long v) @trusted
private void _setUlong(ulong v) @trusted
private void _setFloat(float v) @trusted
private void _setDouble(double v) @trusted
private void _setReal(double v) @trusted
private void _setChar(char v) @trusted
private void _setWchar(wchar v) @trusted
private void _setDchar(dchar v) @trusted
private string _toJSONString(size_t depth) const @safeRender arrays and maps in a compact, deterministic JSON-like form.
Type type() @property const nothrow @nogc pure @safeGet the current type tag of this value.
bool isNull() @property const nothrow @nogc pure @safeCheck if this value is null (Type.NULL).
bool isArray() @property const nothrow @nogc pure @safeCheck if this value is an array (Type.ARRAY).
bool isObject() @property const nothrow @nogc pure @safeCheck if this value is an object/map (Type.OBJECT).
bool isNumeric() @property const nothrow @nogc pure @safeCheck if this value is a numeric type.
bool isInteger() @property const nothrow @nogc pure @safeReturns true if this is any integer type (BYTE, UBYTE, SHORT, USHORT, INT, UINT, LONG, ULONG).
bool isFloat() @property const nothrow @nogc pure @safeReturns true if this is any floating-point type (FLOAT, DOUBLE, REAL).
bool isString() @property const nothrow @nogc pure @safeCheck if this value is a string (Type.STRING).
bool empty() @property const @safeCheck if this value is empty.
bool isBool() @property const nothrow @nogc pure @safeCheck if this value is a boolean (Type.BOOL).
bool isDate() @property const nothrow @nogc pure @safeCheck if this `var` holds a `Date` value.
bool isTime() @property const nothrow @nogc pure @safeCheck if this `var` holds a `TimeOfDay` value.
bool isDateTime() @property const nothrow @nogc pure @safeCheck if this `var` holds a `DateTime` value.
bool isSysTime() @property const nothrow @nogc pure @safeCheck if this `var` holds a `SysTime` value.
bool isDuration() @property const nothrow @nogc pure @safeCheck if this `var` holds a `Duration` value.
bool isTemporal() @property const nothrow @nogc pure @safeCheck if this `var` holds any temporal (datetime) type.
auto visit(handlers...)() const @safeApply a visitor pattern to this value, dispatching to the appropriate handler based on type.
auto visitNogc(handlers...)() const @safe @nogc`visitNogc` is a no-GC variant of `visit`.
private R _unreachable(R)(string msg) @trusted
private static auto _visitDispatch(R, T, handlers...)(T value) @safeHelper to find and call the appropriate handler
var makeArray() @safeCreate an empty array value (`Type.ARRAY`).
var makeObject() @safeCreate an empty map value (`Type.OBJECT`).
var emptyArray() @property @safeReturns an empty array value (`Type.ARRAY`).
var emptyObject() @property @safeReturns an empty object/map value (`Type.OBJECT`).
var array_() @property @safeAlias for `emptyArray`. Returns an empty array value (`Type.ARRAY`).
var object_() @property @safeAlias for `emptyObject`. Returns an empty object/map value (`Type.OBJECT`).
var fromArray(T)(T[] arr) @safeConstruct a `var` from an array `arr`, converting elements to `var`.
var fromMap(const var[string] m) @safeConstruct a `var` from a map `m` (string -> var).
Constructors
this(T arg)Construct a `var` from another value `arg`.
Nested Templates
TypeThe concrete type of a `var` value.
ElementRangeA forward range over the elements of a `var` array.
ConstElementRangeA forward range over the elements of a `const var` array.
KeyRangeA forward range over the keys of a `var` object.
ValueRangeA forward range over the values of a `var` object.
KeyValuePairA key-value pair returned by `PairRange`.
PairRangeA forward range over the key-value pairs of a `var` object.