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:

  • This library does not throw exceptions for runtime misuse. Instead, programmer errors (e.g., indexing a non-map or using array APIs on non-arrays) are guarded with assert in debug builds.
  • Recoverable situations return a status value and do not throw.
  • 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

var.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.

Parameters:

Name Type Description
arg T The value to store

Example:

var a = 42;           // INT
var b = "hello";      // STRING
var c = 3.14;         // DOUBLE
var d = true;         // BOOL
var e = [1, 2, 3];    // ARRAY

Properties

type

@property Type type() const nothrow @nogc pure @safe

Returns the current type tag of the stored value.

Returns: The Type enum value indicating the stored type.

isNull

@property bool isNull() const nothrow @nogc pure @safe

Returns true if the value is NULL.

isArray

@property bool isArray() const nothrow @nogc pure @safe

Returns true if the value is an ARRAY.

isObject

@property bool isObject() const nothrow @nogc pure @safe

Returns true if the value is an OBJECT.

isNumeric

@property bool isNumeric() const nothrow @nogc pure @safe

Returns true if the value is a numeric type (integer or floating point).

isString

@property bool isString() const nothrow @nogc pure @safe

Returns true if the value is a STRING.

isBool

@property bool isBool() const nothrow @nogc pure @safe

Returns true if the value is a BOOL.

length

@property size_t length() const @safe

Returns the length of the stored value.

  • For STRING: returns the string length.
  • For ARRAY: returns the number of elements.
  • For OBJECT: returns the number of key-value pairs.
  • For other types: returns 0.

keys

@property string[] keys() const @safe

Returns an array of all keys in an OBJECT. Returns an empty array for non-object types.

values

@property var[] values() const @safe

Returns an array of all values in an OBJECT. Returns an empty array for non-object types.

count

@property size_t count() const @safe

Returns the number of elements in an ARRAY or key-value pairs in an OBJECT. Returns 0 for other types.

opDollar

@property size_t opDollar() const @safe

Returns the length for use with the $ operator in slice expressions.

Methods

opAssign(T)

public var opAssign(T)(T rhs) @safe

Assigns a value of type T to this var.

Parameters:

Name Type Description
rhs T The value to assign

Returns: Reference to this.

Note: Assignment from another var is shallow for arrays and objects. Use dup() for deep copies.

as(T)

public T as(T)() const @safe

Converts the stored value to type T.

Returns: The value converted to type T, or T.init if conversion is not possible.

Example:

var v = 42;
int i = v.as!int;        // 42
string s = v.as!string;  // "42"

var arr = [1, 2, 3];
var[] elements = arr.as!(var[]);

dup

var dup() const @safe

Creates a deep copy of the var value. For arrays and objects, recursively duplicates all nested elements.

Returns: A new var that is an independent deep copy.

Example:

var original;
original["nested"] = [1, 2, 3];

var copy = original.dup;
copy["nested"][0] = 99;
assert(original["nested"][0].as!int == 1);  // Original unchanged

idup

var idup() const @safe

Creates an immutable deep copy of the var value.

Returns: A new var with immutable string data.

get(key, defaultValue)

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

Retrieves a value from an OBJECT by key, returning a default if the key is not found.

Parameters:

Name Type Description
key string The key to look up
defaultValue TDefault Value to return if key is not found

Returns: The value associated with key, or defaultValue if not found.

contains

bool contains(const string key) const @safe

Checks if an OBJECT contains the specified key.

Parameters:

Name Type Description
key string The key to check

Returns: true if the key exists, false otherwise.

remove

bool remove(string key) @safe

Removes a key-value pair from an OBJECT.

Parameters:

Name Type Description
key string The key to remove

Returns: true if the key was found and removed, false otherwise.

insert

bool insert(T)(size_t index, T rhs) @safe

Inserts a value into an ARRAY at the specified index.

Parameters:

Name Type Description
index size_t Position to insert at
rhs T Value to insert

Returns: true if insertion succeeded, false otherwise.

removeAt

bool removeAt(size_t index) @safe

Removes an element from an ARRAY at the specified index.

Parameters:

Name Type Description
index size_t Position to remove

Returns: true if removal succeeded, false otherwise.

clear

void clear() @safe

Resets the var to NULL, releasing any stored value.

toString

string toString() const @safe

Converts the var to a human-readable string representation.

Returns: A string representation of the value.

toJSON

string toJSON() const @safe

Serializes the var to a JSON string.

Returns: A JSON-formatted string.

Example:

var data;
data["name"] = "example";
data["values"] = [1, 2, 3];

string json = data.toJSON();
// Output: {"name":"example","values":[1,2,3]}

Operators

opIndex (string key)

ref var opIndex(string key) @safe

Accesses or creates a value in an OBJECT by key. If the var is NULL, it is promoted to an OBJECT.

Example:

var obj;
obj["name"] = "Alice";
string name = obj["name"].as!string;

opIndex (size_t index)

ref var opIndex(size_t index) @safe

Accesses an element in an ARRAY by index.

opIndexAssign

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

Assigns a value to an OBJECT key.

opDispatch

auto opDispatch(string key)() @safe

Provides field-like access to OBJECT keys.

Example:

var obj;
obj.name = "Alice";      // Same as obj["name"] = "Alice"
obj.age = 30;
string name = obj.name.as!string;

opBinary

var opBinary(string op)(const var rhs) const @safe

Performs arithmetic operations (+, -, *, /, %) between var values.

Note: Division or modulo by zero returns var.init (NULL).

Example:

var a = 10;
var b = 3;
var sum = a + b;   // 13
var quot = a / b;  // 3

opUnary

var opUnary(string op)() const @safe

Performs unary operations (-, +, ~, !) on a var value.

opEquals

bool opEquals(const scope var rhs) const @safe

Compares two var values for equality.

opCmp

int opCmp(const var rhs) const @safe

Compares two var values for ordering.

Returns: Negative if this < rhs, zero if equal, positive if this > rhs.

See Also