Skip to content

ddn.adam

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

Overview

This module provides adam, a memory-optimized dynamic value type designed to match the semantics and API of ddn.var while minimizing memory footprint. It is suitable for applications where large numbers of dynamic values must be stored or transmitted with minimal overhead.

Key Features:

  • Compact representation: Only 16 bytes on 64-bit platforms (vs. typical 24+ bytes for variant types).
  • Tagged-length encoding: Type tag and collection length share a single size_t word.
  • Full numeric tower: Supports bool, all D integer types, float, double, and dchar.
  • Composite types: Arrays (adam[]) and objects (adam[string]) with JSON-like semantics.
  • GC-safe: Pointer payloads are never tagged, preserving garbage collector reachability.
  • API compatibility: Mirrors ddn.var operators, conversions, and serialization methods.

Structs

adam

struct adam

A compact, memory-efficient dynamic value type.

Representation:

  • A scalar-or-pointer payload word (_data).
  • A tagged length word (_lenTag) that packs the Type tag into the high bits and (for STRING and ARRAY) the length into the low bits.

Type Normalization:

  • real values are stored as Type.DOUBLE (converted to double).
  • char and wchar values are stored as Type.DCHAR (converted to dchar).

Platform Notes:

Platform adam.sizeof Max Array/String Length
64-bit 16 bytes Full size_t range
32-bit 8 bytes 2²⁸ - 1 (28 bits)

Enums

adam.Type

enum Type : ubyte

The concrete type tag for an adam 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
DCHAR Unicode scalar character (normalized from char/wchar)
ARRAY Dynamic array of adam
STRING UTF-8 string
OBJECT Associative array (string → adam)

Constructors

this(T)

this(T)(T value) @safe

Constructs an adam from a value of type T.

Parameters:

Name Type Description
value T The value to store

Example:

adam i = 42;
adam d = 3.14;
adam s = "hello";
adam b = true;

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.

isBool

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

Returns true if the value is a BOOL.

isArray

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

Returns true if the value is an ARRAY.

isString

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

Returns true if the value is a STRING.

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

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.

opDollar

@property size_t opDollar() const @safe

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

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.

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 adam[] values() const @safe

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

Methods

opAssign(T)

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

Assigns a value of type T to this adam.

Parameters:

Name Type Description
rhs T The value to assign

Returns: Reference to this.

get(T)

T get(T)() const @safe

Extracts the stored value as type T.

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

Example:

adam v = 42;
int i = v.get!int;
string s = v.get!string;

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.

toString

string toString() const @trusted

Converts the adam to a human-readable string representation.

Returns: A string representation of the value.

toJSON

string toJSON() const @safe

Serializes the adam to a JSON string.

Returns: A JSON-formatted string.

Example:

adam data;
data["id"] = 123;
data["active"] = true;

string json = data.toJSON();
// Output: {"active":true,"id":123}

Operators

opIndex (string key)

ref adam opIndex(string key) @safe

Accesses or creates a value in an OBJECT by key.

Example:

adam obj;
obj["name"] = "alice";
obj["age"] = 30;

opIndex (size_t index)

ref adam 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.

opEquals

bool opEquals(const adam other) const @safe

Compares two adam values for equality.

opCmp

int opCmp(const adam rhs) const @safe

Compares two adam values for ordering.

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

Usage Comparison

When to Use adam vs var

Use Case Recommended Type
Memory-constrained environments adam
Large collections of dynamic values adam
Network serialization with size limits adam
General-purpose dynamic typing var
Maximum compatibility and features var

See Also