ddn.adam¶

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

Overview¶

The ddn.adam 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 ideal for applications where large numbers of dynamic values must be stored or transmitted with minimal overhead.

Key Differences from `ddn.var`¶

Aspect	`ddn.var`	`ddn.adam`
Size (64-bit)	24+ bytes	16 bytes
Size (32-bit)	Variable	8 bytes
Max array/string length (32-bit)	Unlimited	2²⁸ - 1
Type storage	Separate tag	Tagged-length encoding

Features¶

Compact Representation¶

On 64-bit platforms, adam uses only 16 bytes per value:

8 bytes for the scalar-or-pointer payload (_data)
8 bytes for the tagged-length word (_lenTag)

The type tag and collection length share a single size_t word using bit packing.

Full Numeric Tower¶

adam supports the complete set of D numeric types:

Category	Types
Boolean	`bool`
Signed Integers	`byte`, `short`, `int`, `long`
Unsigned Integers	`ubyte`, `ushort`, `uint`, `ulong`
Floating Point	`float`, `double`
Characters	`dchar` (normalized from `char`/`wchar`)

Type Normalization¶

To keep the tag space small, adam normalizes certain types:

real values are stored as double
char and wchar values are stored as dchar

Composite Types¶

adam supports JSON-like composite structures:

Arrays: adam[] — ordered sequences of values
Objects: adam[string] — key-value maps with string keys

GC Safety¶

Pointer payloads are never tagged, ensuring the garbage collector can properly track and manage referenced memory.

Usage Examples¶

Scalar Values¶

import ddn.adam;

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

Arrays¶

adam arr = [adam(1), adam(2), adam(3)];
assert(arr.length == 3);

// Access elements
adam first = arr[0];

Objects¶

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

assert(obj["name"].get!string == "alice");
assert(obj["age"].get!int == 30);

JSON Serialization¶

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

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

Platform Notes¶

64-bit Systems¶

adam.sizeof == 16
Full range for array/string lengths

32-bit Systems¶

adam.sizeof == 8
Array/string lengths limited to 28 bits (max 268,435,455 elements)

This limitation arises from the tagged-length encoding scheme where 4 bits are reserved for the type tag.

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`