VariantN

Back-end type seldom used directly by user code. Two commonly-used types using VariantN are:

  1. Algebraic: A closed discriminated union with a limited type universe (e.g., Algebraic!(int, double, string) only accepts these three types and rejects anything else).
  2. Variant: An open discriminated union allowing an unbounded set of types. If any of the types in the Variant are larger than the largest built-in type, they will automatically be boxed. This means that even large types will only be the size of a pointer within the Variant, but this also implies some overhead. Variant can accommodate all primitive types and all user-defined types.

Both Algebraic and Variant share VariantN's interface. (See their respective documentations below.)

VariantN is a discriminated union type parameterized with the largest size of the types stored (maxDataSize) and with the list of allowed types (AllowedTypes). If the list is empty, then any type up of size up to maxDataSize (rounded up for alignment) can be stored in a VariantN object without being boxed (types larger than this will be boxed).

Constructors

this
this(T value)

Constructs a VariantN value given an argument of a generic type. Statically rejects disallowed types.

this
this(T value)

Allows assignment from a subset algebraic type

Destructor

A destructor is present on this object, but not explicitly documented in the source.

Postblit

A postblit is present on this object, but not explicitly documented in the source.

Members

Aliases

AllowedTypes
alias AllowedTypes = This2Variant!(VariantN, AllowedTypesParam)

The list of allowed types. If empty, any type is allowed.

Functions

opApply
int opApply(Delegate dg)

If the VariantN contains an array, applies dg to each element of the array in turn. Otherwise, throws an exception.

opAssign
VariantN opAssign(T rhs)

Assigns a VariantN from a generic * argument. Statically rejects disallowed types.

opBinary
VariantN opBinary(T rhs)
opBinaryRight
VariantN opBinaryRight(T lhs)

Arithmetic between VariantN objects and numeric values. All arithmetic operations return a VariantN object typed depending on the types of both values involved. The conversion rules mimic D's built-in rules for arithmetic conversions.

opCmp
int opCmp(T rhs)

Ordering comparison used by the "<", "<=", ">", and ">=" operators. In case comparison is not sensible between the held value and rhs, an exception is thrown.

opEquals
bool opEquals(T rhs)

Comparison for equality used by the "==" and "!=" operators.

opIndex
inout(Variant) opIndex(K i)
opIndexAssign
Variant opIndexAssign(T value, N i)
opIndexOpAssign
Variant opIndexOpAssign(T value, N i)

Array and associative array operations. If a VariantN contains an (associative) array, it can be indexed into. Otherwise, an exception is thrown.

opOpAssign
VariantN opOpAssign(T rhs)

Arithmetic between VariantN objects and numeric values. All arithmetic operations return a VariantN object typed depending on the types of both values involved. The conversion rules mimic D's built-in rules for arithmetic conversions.

toHash
size_t toHash()

Computes the hash of the held value.

toString
string toString()

Formats the stored value as a string.

Properties

coerce
T coerce [@property getter]

Returns the value stored in the VariantN object, explicitly converted (coerced) to the requested type T. If T is a string type, the value is formatted as a string. If the VariantN object is a string, a parse of the string to type T is attempted. If a conversion is not possible, throws a VariantException.

convertsTo
bool convertsTo [@property getter]

Returns true if and only if the VariantN object holds an object implicitly convertible to type T. Implicit convertibility is defined as per AllImplicitConversionTargets.

get
inout(T) get [@property getter]
auto get [@property getter]

Returns the value stored in the VariantN object, either by specifying the needed type or the index in the list of allowed types. The latter overload only applies to bounded variants (e.g. Algebraic).

hasValue
bool hasValue [@property getter]

Returns true if and only if the VariantN object holds a valid value (has been initialized with, or assigned from, a valid value).

length
size_t length [@property getter]

If the VariantN contains an (associative) array, returns the length of that array. Otherwise, throws an exception.

peek
inout(T)* peek [@property getter]

If the VariantN object holds a value of the exact type T, returns a pointer to that value. Otherwise, returns null. In cases where T is statically disallowed, peek will not compile.

type
TypeInfo type [@property getter]

Returns the typeid of the currently held value.

Templates

allowed
template allowed(T)

Tells whether a type T is statically allowed for storage inside a VariantN object by looking T up in AllowedTypes.

Examples

alias Var = VariantN!(maxSize!(int, double, string));

Var a; // Must assign before use, otherwise exception ensues
// Initialize with an integer; make the type int
Var b = 42;
assert(b.type == typeid(int));
// Peek at the value
assert(b.peek!(int) !is null && *b.peek!(int) == 42);
// Automatically convert per language rules
auto x = b.get!(real);

// Assign any other type, including other variants
a = b;
a = 3.14;
assert(a.type == typeid(double));
// Implicit conversions work just as with built-in types
assert(a < b);
// Check for convertibility
assert(!a.convertsTo!(int)); // double not convertible to int
// Strings and all other arrays are supported
a = "now I'm a string";
assert(a == "now I'm a string");

can also assign arrays

alias Var = VariantN!(maxSize!(int[]));

Var a = new int[42];
assert(a.length == 42);
a[5] = 7;
assert(a[5] == 7);

Can also assign class values

alias Var = VariantN!(maxSize!(int*)); // classes are pointers
Var a;

class Foo {}
auto foo = new Foo;
a = foo;
assert(*a.peek!(Foo) == foo); // and full type information is preserved

Meta