Skip to content

ddn.var

A compact, dynamic value type for the D programming language.

Overview

This module provides var, a versatile dynamic value type that can hold values of many different types at runtime. It is designed to be compact, efficient, and easy to use for scenarios where static typing is impractical—such as configuration handling, JSON-like data structures, or scripting interfaces.

Structs

var

struct var

A compact, dynamic value type capable of holding scalar values, strings, arrays, and associative arrays.

Error Handling Strategy:

  • By default, ddn.var follows a fail-fast strategy: wrong-type container use (e.g., indexing a non-object) throws a VarException (specifically VarTypeException or VarKeyException).
  • When compiled with version(DDN_VAR_TYPE_COERCE), var becomes permissive, automatically coercing scalar types to collections upon mutation and returning neutral NULL values for read-only mismatches.
  • Division/modulo by zero returns var.init (NULL) instead of throwing.

Thread Safety:

  • var does not perform internal synchronization. Concurrent mutation of the same instance from multiple threads is a data race.
  • Independent copies may be used in different threads.
  • Use dup() for deep copies when sharing data between threads.

Enums

Type
enum Type : byte

The concrete type tag for a var value.

Member Description
NULL The absence of a value
BOOL Boolean value (true or false)
BYTE Signed 8-bit integer
UBYTE Unsigned 8-bit integer
SHORT Signed 16-bit integer
USHORT Unsigned 16-bit integer
INT Signed 32-bit integer
UINT Unsigned 32-bit integer
LONG Signed 64-bit integer
ULONG Unsigned 64-bit integer
FLOAT 32-bit IEEE-754 floating point
DOUBLE 64-bit IEEE-754 floating point
REAL Platform real (stored internally as double)
CHAR Narrow character (char)
WCHAR Wide character (wchar)
DCHAR Unicode scalar character (dchar)
ARRAY Dynamic array of var
STRING UTF-8 string
OBJECT Associative array (string → var)
VAR Backward-compatibility alias for OBJECT

Constructors

this(T)
public this(T)(T arg) @safe

Constructs a var from a value of type T.

Properties

type
@property Type type() const

Returns the current type tag of the stored value.

length
@property size_t length() const

Get the number of elements when the value holds an array. Returns 0 for Type.NULL. Asserts for other non-array types.

keys
@property string[] keys() const

Return an array of keys (if map). For Type.NULL, returns an empty array.

values
@property var[] values() const

Return an array of values (if map). For Type.NULL, returns an empty array.

count
@property size_t count() const

Return the number of elements in the map. Returns 0 for Type.NULL.

opDollar
@property size_t opDollar() const

Support $ in slice expressions for arrays. Returns the length of the array.

Methods

opAssign
var opAssign(T)(T rhs)

Assign from an arbitrary value rhs, setting the internal type and payload accordingly.

opIndex
ref var opIndex(string key)
ref const(var) opIndex(string key) const

Access a child value by key. Mutable version turns this instance into a map on first use (auto-vivification). Const version asserts if key is missing.

ref var opIndex(size_t index)
ref const(var) opIndex(size_t index) const

Index into the array payload and return a reference to the element.

opIndexAssign
void opIndexAssign(T)(T rhs, string key)

Assign a value to a child by key (map-style assignment).

opSlice
var opSlice(size_t start, size_t end) const

Slice an array to create a new var containing a subrange of elements.

remove
bool remove(string key)

Remove a child by key from the map. Returns true if removed.

append
void append(T)(T rhs)

Append a value to the array. Converts Type.NULL to an empty array on first use.

contains
bool contains(const string key) const

Check whether the map contains key.

get
var get(TDefault)(const string key, TDefault defaultValue) const

Get the value for key or return defaultValue if missing. Does not modify the map.

getField
var getField(T)(const string key, T defaultValue) const

Safely get a field value with a default fallback. Similar to get.

opDispatch
ref var opDispatch(string name)()
ref const(var) opDispatch(string name)() const

Dynamic field access (v.field). Promotes Type.NULL to Type.OBJECT.

as
T as(T)() const

Convert the stored value to type T (or T.init on failure).

tryAs
Nullable!T tryAs(T)() const

Attempt to convert the stored value to type T, returning a Nullable!T.

toString
string toString() const

Convert the stored value to a human-readable string (JSON-like for objects/arrays).

toStringTo
void toStringTo(Sink)(ref Sink sink) const

Write the string representation of this value to an output range.

byElement
ElementRange byElement()
ConstElementRange byElement() const

Get a forward range over the elements of this array.

Ranges

ElementRange
struct ElementRange

A forward range for iterating over var array elements.