If you spot a problem with this page, click here to create a Bugzilla issue.

Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

std.typecons

This module implements a variety of type constructors, i.e., templates that allow construction of new, useful general-purpose types.

Source: std/typecons.d

Synopsis:

// value tuples
alias Coord = Tuple!(float, "x", float, "y", float, "z");
Coord c;
c[1] = 1;       // access by index
c.z = 1;        // access by given name
alias DicEntry = Tuple!(string, string); // names can be omitted

// Rebindable references to const and immutable objects
void bar()
{
    const w1 = new Widget, w2 = new Widget;
    w1.foo();
    // w1 = w2 would not work; can't rebind const object
    auto r = Rebindable!(const Widget)(w1);
    // invoke method as if r were a Widget object
    r.foo();
    // rebind r to refer to another object
    r = w2;
}

License:

Boost License 1.0.

Authors:

Andrei Alexandrescu, Bartosz Milewski, Don Clugston, Shin Fujishiro, Kenji Hara

struct Unique(T);

Encapsulates unique ownership of a resource. Resource of type T is deleted at the end of the scope, unless it is transferred. The transfer can be explicit, by calling release, or implicit, when returning Unique from a function. The resource can be a polymorphic class object, in which case Unique behaves polymorphically too.

Examples:

static struct S
{
    int i;
    this(int i){this.i = i;}
}
Unique!S produce()
{
    // Construct a unique instance of S on the heap
    Unique!S ut = new S(5);
    // Implicit transfer of ownership
    return ut;
}
// Borrow a unique resource by ref
void increment(ref Unique!S ur)
{
    ur.i++;
}
void consume(Unique!S u2)
{
    assert(u2.i == 6);
    // Resource automatically deleted here
}
Unique!S u1;
assert(u1.isEmpty);
u1 = produce();
increment(u1);
assert(u1.i == 6);
//consume(u1); // Error: u1 is not copyable
// Transfer ownership of the resource
consume(u1.release);
assert(u1.isEmpty);

alias RefT = T;

Represents a reference to T. Resolves to T* if T is a value type.

Unique!T create(A...)(auto ref A args) if (__traits(compiles, new T(args)));

Allows safe construction of Unique. It creates the resource and guarantees unique ownership of it (unless T publishes aliases of this).

Note: Nested structs/classes cannot be created.

Parameters:

A args

Arguments to pass to T's constructor.

static class C {}
auto u = Unique!(C).create();

this(RefT p);

Constructor that takes an rvalue. It will ensure uniqueness, as long as the rvalue isn't just a view on an lvalue (e.g., a cast). Typical usage:

Unique!Foo f = new Foo;

this(ref RefT p);

Constructor that takes an lvalue. It nulls its source. The nulling will ensure uniqueness as long as there are no previous aliases to the source.

this(U)(Unique!U u) if (is(u.RefT : RefT));

Constructor that takes a Unique of a type that is convertible to our type.

Typically used to transfer a Unique rvalue of derived type to a Unique of base type.

Example:

class C : Object {}

Unique!C uc = new C;
Unique!Object uo = uc.release;

void opAssign(U)(Unique!U u) if (is(u.RefT : RefT));

Transfer ownership from a Unique of a type that is convertible to our type.

const @property bool isEmpty();

Returns whether the resource exists.

Unique release();

Transfer ownership to a Unique rvalue. Nullifies the current contents.

RefT opDot();

Forwards member access to contents.

struct Tuple(Specs...);

Tuple of values, for example Tuple!(int, string) is a record that stores an int and a string. Tuple can be used to bundle values together, notably when returning multiple values from a function. If obj is a Tuple, the individual members are accessible with the syntax obj[0] for the first field, obj[1] for the second, and so on.

The choice of zero-based indexing instead of one-base indexing was motivated by the ability to use value Tuples with various compile-time loop constructs (e.g. std.meta.AliasSeq iteration), all of which use zero-based indexing.

Parameters:

Specs

A list of types (and optionally, member names) that the Tuple contains.

Examples:

Tuple!(int, int) point;
// assign coordinates
point[0] = 5;
point[1] = 6;
// read coordinates
auto x = point[0];
auto y = point[1];

Examples:

Tuple members can be named. It is legal to mix named and unnamed members. The method above is still applicable to all fields.

alias Entry = Tuple!(int, "index", string, "value");
Entry e;
e.index = 4;
e.value = "Hello";
assert(e[1] == "Hello");
assert(e[0] == 4);

Examples:

A Tuple with named fields is a distinct type from a Tuple with unnamed fields, i.e. each naming imparts a separate type for the Tuple. Two Tuples differing in naming only are still distinct, even though they might have the same structure.

Tuple!(int, "x", int, "y") point1;
Tuple!(int, int) point2;
assert(!is(typeof(point1) == typeof(point2)));

alias Types = staticMap!(extractType, fieldSpecs);

The types of the Tuple's components.

Examples:

alias Fields = Tuple!(int, "id", string, float);
static assert(is(Fields.Types == AliasSeq!(int, string, float)));

alias fieldNames = staticMap!(extractName, fieldSpecs);

The names of the Tuple's components. Unnamed fields have empty names.

Examples:

alias Fields = Tuple!(int, "id", string, float);
static assert(Fields.fieldNames == AliasSeq!("id", "", ""));

Types expand;

Use t.expand for a Tuple t to expand it into its components. The result of expand acts as if the Tuple's components were listed as a list of values. (Ordinarily, a Tuple acts as a single value.)

Examples:

auto t1 = tuple(1, " hello ", 2.3);
assert(t1.toString() == `Tuple!(int, string, double)(1, " hello ", 2.3)`);

void takeSeveralTypes(int n, string s, bool b)
{
    assert(n == 4 && s == "test" && b == false);
}

auto t2 = tuple(4, "test", false);
//t.expand acting as a list of values
takeSeveralTypes(t2.expand);

this(Types values);

Constructor taking one value for each field.

Parameters:

Types values

A list of values that are either the same types as those given by the Types field of this Tuple, or can implicitly convert to those types. They must be in the same order as they appear in Types.

Examples:

alias ISD = Tuple!(int, string, double);
auto tup = ISD(1, "test", 3.2);
assert(tup.toString() == `Tuple!(int, string, double)(1, "test", 3.2)`);

this(U, size_t n)(U[n] values) if (n == Types.length && allSatisfy!(isBuildableFrom!U, Types));

Constructor taking a compatible array.

Parameters:

U[n] values

A compatible static array to build the Tuple from. Array slices are not supported.

Examples:

int[2] ints;
Tuple!(int, int) t = ints;

this(U)(U another) if (areBuildCompatibleTuples!(typeof(this), U));

Constructor taking a compatible Tuple. Two Tuples are compatible iff they are both of the same length, and, for each type T on the left-hand side, the corresponding type U on the right-hand side can implicitly convert to T.

Parameters:

U another

A compatible Tuple to build from. Its type must be compatible with the target Tuple's type.

Examples:

alias IntVec = Tuple!(int, int, int);
alias DubVec = Tuple!(double, double, double);

IntVec iv = tuple(1, 1, 1);

//Ok, int can implicitly convert to double
DubVec dv = iv;
//Error: double cannot implicitly convert to int
//IntVec iv2 = dv;

bool opEquals(R)(R rhs) if (areCompatibleTuples!(typeof(this), R, "==")); const bool opEquals(R)(R rhs) if (areCompatibleTuples!(typeof(this), R, "=="));

Comparison for equality. Two Tuples are considered equal iff they fulfill the following criteria:

Each Tuple is the same length.
For each type T on the left-hand side and each type U on the right-hand side, values of type T can be compared with values of type U.
For each value v1 on the left-hand side and each value v2 on the right-hand side, the expression v1 == v2 is true.

Parameters:

R rhs

The Tuple to compare against. It must meeting the criteria for comparison between Tuples.

Returns:

true if both Tuples are equal, otherwise false.

Examples:

Tuple!(int, string) t1 = tuple(1, "test");
Tuple!(double, string) t2 =  tuple(1.0, "test");
//Ok, int can be compared with double and
//both have a value of 1
assert(t1 == t2);

int opCmp(R)(R rhs) if (areCompatibleTuples!(typeof(this), R, "<")); const int opCmp(R)(R rhs) if (areCompatibleTuples!(typeof(this), R, "<"));

Comparison for ordering.

Parameters:

R rhs

The Tuple to compare against. It must meet the criteria for comparison between Tuples.

Returns:

For any values v1 on the right-hand side and v2 on the left-hand side:

A negative integer if the expression v1 < v2 is true.
A positive integer if the expression v1 > v2 is true.
0 if the expression v1 == v2 is true.

Examples:

The first v1 for which v1 > v2 is true determines the result. This could lead to unexpected behaviour.

auto tup1 = tuple(1, 1, 1);
auto tup2 = tuple(1, 100, 100);
assert(tup1 < tup2);

//Only the first result matters for comparison
tup1[0] = 2;
assert(tup1 > tup2);

void opAssign(R)(auto ref R rhs) if (areCompatibleTuples!(typeof(this), R, "="));

Assignment from another Tuple.

Parameters:

R rhs

The source Tuple to assign from. Each element of the source Tuple must be implicitly assignable to each respective element of the target Tuple.

@property ref @trusted Tuple!(sliceSpecs!(from, to)) slice(size_t from, size_t to)() if (from <= to && to <= Types.length);

Takes a slice of this Tuple.

Parameters:

from	A size_t designating the starting position of the slice.
to	A size_t designating the ending position (exclusive) of the slice.

Returns:

A new Tuple that is a slice from [from, to) of the original. It has the same types and values as the range [from, to) in the original.

Examples:

Tuple!(int, string, float, double) a;
a[1] = "abc";
a[2] = 4.5;
auto s = a.slice!(1, 3);
static assert(is(typeof(s) == Tuple!(string, float)));
assert(s[0] == "abc" && s[1] == 4.5);

const nothrow @trusted size_t toHash();

Creates a hash of this Tuple.

Returns:

A size_t representing the hash of this Tuple.

template toString()

const string toString()();

Converts to string.

Returns:

The string representation of this Tuple.

const void toString(DG)(scope DG sink); const void toString(DG, Char)(scope DG sink, FormatSpec!Char fmt);

Formats Tuple with either %s, %(inner%) or %(inner%|sep%).

Formats supported by Tuple
Format	Description
%s	Format like Tuple!(types)(elements formatted with %s each).
%(inner%)	The format inner is applied the expanded Tuple, so it may contain as many formats as the Tuple has fields.
%(inner%\|sep%)	The format inner is one format, that is applied on all fields of the Tuple. The inner format must be compatible to all of them.

 Tuple!(int, double)[3] tupList = [ tuple(1, 1.0), tuple(2, 4.0), tuple(3, 9.0) ];

 // Default format
 assert(format("%s", tuple("a", 1)) == `Tuple!(string, int)("a", 1)`);

 // One Format for each individual component
 assert(format("%(%#x v %.4f w %#x%)", tuple(1, 1.0, 10))         == `0x1 v 1.0000 w 0xa`);
 assert(format(  "%#x v %.4f w %#x"  , tuple(1, 1.0, 10).expand)  == `0x1 v 1.0000 w 0xa`);

 // One Format for all components
 assert(format("%(>%s<%| & %)", tuple("abc", 1, 2.3, [4, 5])) == `>abc< & >1< & >2.3< & >[4, 5]<`);

 // Array of Tuples
 assert(format("%(%(f(%d) = %.1f%);  %)", tupList) == `f(1) = 1.0;  f(2) = 4.0;  f(3) = 9.0`);


 // Error: %( %) missing.
 assertThrown!FormatException(
     format("%d, %f", tuple(1, 2.0)) == `1, 2.0`
 );

 // Error: %( %| %) missing.
 assertThrown!FormatException(
     format("%d", tuple(1, 2)) == `1, 2`
 );

 // Error: %d inadequate for double.
 assertThrown!FormatException(
     format("%(%d%|, %)", tuple(1, 2.0)) == `1, 2.0`
 );

ReverseTupleType!T reverse(T)(T t) if (isTuple!T);

Create a copy of a Tuple with its fields in reverse order.

Parameters:

T t	The Tuple to copy.

Returns:

A copy of t with its fields in reverse order.

Examples:

auto tup = tuple(1, "2");
assert(tup.reverse == tuple("2", 1));

template tuple(Names...)

Constructs a Tuple object instantiated and initialized according to the given arguments.

Parameters:

Names	A list of strings naming each successive field of the Tuple. Each name matches up with the corresponding field given by Args. A name does not have to be provided for every field, but as the names must proceed in order, it is not possible to skip one field and name the next after it.
args	Values to initialize the Tuple with. The Tuple's type will be inferred from the types of the values given.

Returns:

A new Tuple with its type inferred from the arguments given.

Examples:

auto value = tuple(5, 6.7, "hello");
assert(value[0] == 5);
assert(value[1] == 6.7);
assert(value[2] == "hello");

// Field names can be provided.
auto entry = tuple!("index", "value")(4, "Hello");
assert(entry.index == 4);
assert(entry.value == "Hello");

enum auto isTuple(T);

Returns true if and only if T is an instance of std.typecons.Tuple.

Parameters:

T	The type to check.

Returns:

true if T is a Tuple type, false otherwise.

Examples:

static assert(isTuple!(Tuple!()));
static assert(isTuple!(Tuple!(int)));
static assert(isTuple!(Tuple!(int, real, string)));
static assert(isTuple!(Tuple!(int, "x", real, "y")));
static assert(isTuple!(Tuple!(int, Tuple!(real), string)));

template Rebindable(T) if (is(T == class) || is(T == interface) || isDynamicArray!T || isAssociativeArray!T)

Rebindable!(T) is a simple, efficient wrapper that behaves just like an object of type T, except that you can reassign it to refer to another object. For completeness, Rebindable!(T) aliases itself away to T if T is a non-const object type.

You may want to use Rebindable when you want to have mutable storage referring to const objects, for example an array of references that must be sorted in place. Rebindable does not break the soundness of D's type system and does not incur any of the risks usually associated with cast.

Parameters:

T	An object, interface, array slice type, or associative array type.

Examples:

Regular const object references cannot be reassigned.

class Widget { int x; int y() const { return x; } }
const a = new Widget;
// Fine
a.y();
// error! can't modify const a
// a.x = 5;
// error! can't modify const a
// a = new Widget;

Examples:

However, Rebindable!(Widget) does allow reassignment, while otherwise behaving exactly like a const Widget.

class Widget { int x; int y() const { return x; } }
auto a = Rebindable!(const Widget)(new Widget);
// Fine
a.y();
// error! can't modify const a
// a.x = 5;
// Fine
a = new Widget;

Rebindable!T rebindable(T)(T obj) if (is(T == class) || is(T == interface) || isDynamicArray!T || isAssociativeArray!T);

Convenience function for creating a Rebindable using automatic type inference.

Parameters:

T obj

A reference to an object, interface, associative array, or an array slice to initialize the Rebindable with.

Returns:

A newly constructed Rebindable initialized with the given reference.

Rebindable!T rebindable(T)(Rebindable!T obj);

This function simply returns the Rebindable object passed in. It's useful in generic programming cases when a given object may be either a regular class or a Rebindable.

Parameters:

Rebindable!T obj

An instance of Rebindable!T.

Returns:

obj without any modification.

template UnqualRef(T) if (is(T == class) || is(T == interface))

Similar to Rebindable!(T) but strips all qualifiers from the reference as opposed to just constness / immutability. Primary intended use case is with shared (having thread-local reference to shared class data)

Parameters:

T	A class or interface type.

Examples:

class Data {}

static shared(Data) a;
static UnqualRef!(shared Data) b;

import core.thread;

auto thread = new core.thread.Thread({
    a = new shared Data();
    b = new shared Data();
});

thread.start();
thread.join();

assert(a !is null);
assert(b is null);

string alignForSize(E...)(const char[][] names...);

Order the provided members to minimize size while preserving alignment. Alignment is not always optimal for 80-bit reals, nor for structs declared as align(1).

Parameters:

E	A list of the types to be aligned, representing fields of an aggregate such as a struct or class.
char[][] names	The names of the fields that are to be aligned.

Returns:

A string to be mixed in to an aggregate, such as a struct or class.

Examples:

struct Banner {
    mixin(alignForSize!(byte[6], double)(["name", "height"]));
}

struct Nullable(T);

Defines a value paired with a distinctive "null" state that denotes the absence of a value. If default constructed, a Nullable!T object starts in the null state. Assigning it renders it non-null. Calling nullify can nullify it again.

Practically Nullable!T stores a T and a bool.

Examples:

struct CustomerRecord
{
    string name;
    string address;
    int customerNum;
}

Nullable!CustomerRecord getByName(string name)
{
    //A bunch of hairy stuff

    return Nullable!CustomerRecord.init;
}

auto queryResult = getByName("Doe, John");
if (!queryResult.isNull)
{
    //Process Mr. Doe's customer record
    auto address = queryResult.address;
    auto customerNum = queryResult.customerNum;

    //Do some things with this customer's info
}
else
{
    //Add the customer to the database
}

inout this(inout T value);

Constructor initializing this with value.

Parameters:

T value

The value to initialize this Nullable with.

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

Check if this is in the null state.

Returns:

true iff this is in the null state, otherwise false.

Examples:

Nullable!int ni;
assert(ni.isNull);

ni = 0;
assert(!ni.isNull);

void nullify()();

Forces this to the null state.

Examples:

Nullable!int ni = 0;
assert(!ni.isNull);

ni.nullify();
assert(ni.isNull);

void opAssign()(T value);

Assigns value to the internally-held state. If the assignment succeeds, this becomes non-null.

Parameters:

T value

A value of type T to assign to this Nullable.

Examples:

If this Nullable wraps a type that already has a null value (such as a pointer), then assigning the null value to this Nullable is no different than assigning any other value of type T, and the resulting code will look very strange. It is strongly recommended that this be avoided by instead using the version of Nullable that takes an additional nullValue template argument.

//Passes
Nullable!(int*) npi;
assert(npi.isNull);

//Passes?!
npi = null;
assert(!npi.isNull);

inout pure nothrow @property ref @safe inout(T) get();

Gets the value. this must not be in the null state. This function is also called for the implicit conversion to T.

Returns:

The value held internally by this Nullable.

Examples:

import std.exception: assertThrown, assertNotThrown;

Nullable!int ni;
//`get` is implicitly called. Will throw
//an AssertError in non-release mode
assertThrown!Throwable(ni == 0);

ni = 0;
assertNotThrown!Throwable(ni == 0);

struct Nullable(T, T nullValue);

Just like Nullable!T, except that the null state is defined as a particular value. For example, Nullable!(uint, uint.max) is an uint that sets aside the value uint.max to denote a null state. Nullable!(T, nullValue) is more storage-efficient than Nullable!T because it does not need to store an extra bool.

Parameters:

T	The wrapped type for which Nullable provides a null value.
nullValue	The null value which denotes the null state of this Nullable. Must be of type T.

Examples:

Nullable!(size_t, size_t.max) indexOf(string[] haystack, string needle)
{
    //Find the needle, returning -1 if not found

    return Nullable!(size_t, size_t.max).init;
}

void sendLunchInvite(string name)
{
}

//It's safer than C...
auto coworkers = ["Jane", "Jim", "Marry", "Fred"];
auto pos = indexOf(coworkers, "Bob");
if (!pos.isNull)
{
    //Send Bob an invitation to lunch
    sendLunchInvite(coworkers[pos]);
}
else
{
    //Bob not found; report the error
}

//And there's no overhead
static assert(Nullable!(size_t, size_t.max).sizeof == size_t.sizeof);

this(T value);

Constructor initializing this with value.

Parameters:

T value

The value to initialize this Nullable with.

const @property bool isNull();

Check if this is in the null state.

Returns:

true iff this is in the null state, otherwise false.

Examples:

Nullable!(int, -1) ni;
//Initialized to "null" state
assert(ni.isNull);

ni = 0;
assert(!ni.isNull);

void nullify()();

Forces this to the null state.

Examples:

Nullable!(int, -1) ni = 0;
assert(!ni.isNull);

ni = -1;
assert(ni.isNull);

void opAssign()(T value);

Assigns value to the internally-held state. If the assignment succeeds, this becomes non-null. No null checks are made. Note that the assignment may leave this in the null state.

Parameters:

T value

A value of type T to assign to this Nullable. If it is nullvalue, then the internal state of this Nullable will be set to null.

Examples:

If this Nullable wraps a type that already has a null value (such as a pointer), and that null value is not given for nullValue, then assigning the null value to this Nullable is no different than assigning any other value of type T, and the resulting code will look very strange. It is strongly recommended that this be avoided by using T's "built in" null value for nullValue.

//Passes
enum nullVal = cast(int*)0xCAFEBABE;
Nullable!(int*, nullVal) npi;
assert(npi.isNull);

//Passes?!
npi = null;
assert(!npi.isNull);

inout @property ref inout(T) get();

Gets the value. this must not be in the null state. This function is also called for the implicit conversion to T.

Returns:

The value held internally by this Nullable.

Examples:

import std.exception: assertThrown, assertNotThrown;

Nullable!(int, -1) ni;
//`get` is implicitly called. Will throw
//an error in non-release mode
assertThrown!Throwable(ni == 0);

ni = 0;
assertNotThrown!Throwable(ni == 0);

struct NullableRef(T);

Just like Nullable!T, except that the object refers to a value sitting elsewhere in memory. This makes assignments overwrite the initially assigned value. Internally NullableRef!T only stores a pointer to T (i.e., Nullable!T.sizeof == (T*).sizeof).

pure nothrow @safe this(T* value);

Constructor binding this to value.

Parameters:

T* value

The value to bind to.

pure nothrow @safe void bind(T* value);

Binds the internal state to value.

Parameters:

T* value

A pointer to a value of type T to bind this NullableRef to.

Examples:

NullableRef!int nr = new int(42);
assert(nr == 42);

int* n = new int(1);
nr.bind(n);
assert(nr == 1);

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

Returns true if and only if this is in the null state.

Returns:

true if this is in the null state, otherwise false.

Examples:

NullableRef!int nr;
assert(nr.isNull);

int* n = new int(42);
nr.bind(n);
assert(!nr.isNull && nr == 42);

pure nothrow @safe void nullify();

Forces this to the null state.

Examples:

NullableRef!int nr = new int(42);
assert(!nr.isNull);

nr.nullify();
assert(nr.isNull);

void opAssign()(T value) if (isAssignable!T);

Assigns value to the internally-held state.

Parameters:

T value

A value of type T to assign to this NullableRef. If the internal state of this NullableRef has not been initialized, an error will be thrown in non-release mode.

Examples:

import std.exception: assertThrown, assertNotThrown;

NullableRef!int nr;
assert(nr.isNull);
assertThrown!Throwable(nr = 42);

nr.bind(new int(0));
assert(!nr.isNull);
assertNotThrown!Throwable(nr = 42);
assert(nr == 42);

inout pure nothrow @property ref @safe inout(T) get();

Gets the value. this must not be in the null state. This function is also called for the implicit conversion to T.

Examples:

import std.exception: assertThrown, assertNotThrown;

NullableRef!int nr;
//`get` is implicitly called. Will throw
//an error in non-release mode
assertThrown!Throwable(nr == 0);

nr.bind(new int(0));
assertNotThrown!Throwable(nr == 0);

template BlackHole(Base)

BlackHole!Base is a subclass of Base which automatically implements all abstract member functions in Base as do-nothing functions. Each auto-implemented function just returns the default value of the return type without doing anything.

The name came from Class::BlackHole Perl module by Sean M. Burke.

Parameters:

Base	A non-final class for BlackHole to inherit from.

See Also:

C++'s make_shared

Examples:

static struct File
{
    string name;
    @disable this(this); // not copyable
    ~this() { name = null; }
}

auto file = File("name");
assert(file.name == "name");
// file cannot be copied and has unique ownership
static assert(!__traits(compiles, {auto file2 = file;}));

// make the file refcounted to share ownership
import std.algorithm.mutation : move;
auto rcFile = refCounted(move(file));
assert(rcFile.name == "name");
assert(file.name == null);
auto rcFile2 = rcFile;
assert(rcFile.refCountedStore.refCount == 2);
// file gets properly closed when last reference is dropped

template Proxy(alias a)

Creates a proxy for the value a that will forward all operations while disabling implicit conversions. The aliased item a must be an lvalue. This is useful for creating a new type from the "base" type (though this is not a subtype-supertype relationship; the new type is not related to the old type in any way, by design).

The new type supports all operations that the underlying type does, including all operators such as +, --, <, [], etc.

Parameters:

a	The value to act as a proxy for all operations. It must be an lvalue.

Examples:

struct MyInt
{
    private int value;
    mixin Proxy!value;

    this(int n){ value = n; }
}

MyInt n = 10;

// Enable operations that original type has.
++n;
assert(n == 11);
assert(n * 2 == 22);

void func(int n) { }

// Disable implicit conversions to original type.
//int x = n;
//func(n);

Examples:

The proxied value must be an lvalue.

struct NewIntType
{
    //Won't work; the literal '1' is
    //is an rvalue, not an lvalue
    //mixin Proxy!1;

    //Okay, n is an lvalue
    int n;
    mixin Proxy!n;

    this(int n) { this.n = n; }
}

NewIntType nit = 0;
nit++;
assert(nit == 1);


struct NewObjectType
{
    Object obj;
    //Ok, obj is an lvalue
    mixin Proxy!obj;

    this (Object o) { obj = o; }
}

NewObjectType not = new Object();
assert(__traits(compiles, not.toHash()));

Examples:

There is one exception to the fact that the new type is not related to the old type. Pseudo-member functions are usable with the new type; they will be forwarded on to the proxied value.

import std.math;

float f = 1.0;
assert(!f.isInfinity);

struct NewFloat
{
    float _;
    mixin Proxy!_;

    this(float f) { _ = f; }
}

NewFloat nf = 1.0f;
assert(!nf.isInfinity);

struct Typedef(T, T init = T.init, string cookie = null);

Typedef allows the creation of a unique type which is based on an existing type. Unlike the alias feature, Typedef ensures the two types are not considered as equals.

Example:

alias MyInt = Typedef!int;
static void takeInt(int) { }
static void takeMyInt(MyInt) { }

int i;
takeInt(i);    // ok
takeMyInt(i);  // fails

MyInt myInt;
takeInt(myInt);    // fails
takeMyInt(myInt);  // ok

Parameters:

init

Optional initial value for the new type. For example:

alias MyInt = Typedef!(int, 10);
MyInt myInt;
assert(myInt == 10);  // default-initialized to 10

Optional, used to create multiple unique types which are based on the same origin type T. For example:

alias TypeInt1 = Typedef!int;
alias TypeInt2 = Typedef!int;

// The two Typedefs are the same type.
static assert(is(TypeInt1 == TypeInt2));

alias MoneyEuros = Typedef!(float, float.init, "euros");
alias MoneyDollars = Typedef!(float, float.init, "dollars");

// The two Typedefs are _not_ the same type.
static assert(!is(MoneyEuros == MoneyDollars));

Note: If a library routine cannot handle the Typedef type, you can use the TypedefType template to extract the type which the Typedef wraps.

template TypedefType(T)

Get the underlying type which a Typedef wraps. If T is not a Typedef it will alias itself to T.

Examples:

import std.typecons: Typedef, TypedefType;
import std.conv: to;

alias MyInt = Typedef!int;
static assert(is(TypedefType!MyInt == int));

/// Instantiating with a non-Typedef will return that type
static assert(is(TypedefType!int == int));

string num = "5";

// extract the needed type
MyInt myInt = MyInt( num.to!(TypedefType!MyInt) );
assert(myInt == 5);

// cast to the underlying type to get the value that's being wrapped
int x = cast(TypedefType!MyInt)myInt;

alias MyIntInit = Typedef!(int, 42);
static assert(is(TypedefType!MyIntInit == int));
static assert(MyIntInit() == 42);

template scoped(T) if (is(T == class))

Allocates a class object right inside the current scope, therefore avoiding the overhead of new. This facility is unsafe; it is the responsibility of the user to not escape a reference to the object outside the scope.

Note: it's illegal to move a class reference even if you are sure there are no pointers to it. As such, it is illegal to move a scoped object.

Examples:

class A
{
    int x;
    this()     {x = 0;}
    this(int i){x = i;}
}

// Standard usage
auto a1 = scoped!A();
auto a2 = scoped!A(1);
a1.x = 42;
assert(a1.x == 42);
assert(a2.x ==  1);

// Restrictions
static assert(!is(typeof({
    auto e1 = a1; // illegal, scoped objects can't be copied
    assert([a2][0].x == 42); // ditto
    alias ScopedObject = typeof(a1);
    auto e2 = ScopedObject();  //Illegal, must be built via scoped!A
    auto e3 = ScopedObject(1); //Illegal, must be built via scoped!A
})));

// Use as member variable
struct B
{
    typeof(scoped!A()) a; // note the trailing parentheses
}

// Use with alias
alias makeScopedA = scoped!A;
auto a6 = makeScopedA();
auto a7 = makeScopedA();

@system auto scoped(Args...)(auto ref Args args);: Returns the scoped object

template Flag(string name)

Defines a simple, self-documenting yes/no flag. This makes it easy for APIs to define functions accepting flags without resorting to bool, which is opaque in calls, and without needing to define an enumerated type separately. Using Flag!"Name" instead of bool makes the flag's meaning visible in calls. Each yes/no flag has its own type, which makes confusions and mix-ups impossible.

Example: Code calling getLine (usually far away from its definition) can't be understood without looking at the documentation, even by users familiar with the API:

string getLine(bool keepTerminator)
{
    ...
    if (keepTerminator) ...
    ...
}
...
auto line = getLine(false);

Assuming the reverse meaning (i.e. "ignoreTerminator") and inserting the wrong code compiles and runs with erroneous results.

After replacing the boolean parameter with an instantiation of Flag, code calling getLine can be easily read and understood even by people not fluent with the API:

string getLine(Flag!"keepTerminator" keepTerminator)
{
    ...
    if (keepTerminator) ...
    ...
}
...
auto line = getLine(Yes.keepTerminator);

The structs Yes and No are provided as shorthand for Flag!"Name".yes and Flag!"Name".no and are preferred for brevity and readability. These convenience structs mean it is usually unnecessary and counterproductive to create an alias of a Flag as a way of avoiding typing out the full type while specifying the affirmative or negative options.

Passing categorical data by means of unstructured bool parameters is classified under "simple-data coupling" by Steve McConnell in the Code Complete book, along with three other kinds of coupling. The author argues citing several studies that coupling has a negative effect on code quality. Flag offers a simple structuring method for passing yes/no flags to APIs.

enum Flag: bool;

no: When creating a value of type Flag!"Name", use Flag!"Name".no for the negative option. When using a value of type Flag!"Name", compare it against Flag!"Name".no or just false or 0.
yes: When creating a value of type Flag!"Name", use Flag!"Name".yes for the affirmative option. When using a value of type Flag!"Name", compare it against Flag!"Name".yes.

struct Yes; struct No;

Convenience names that allow using e.g. Yes.encryption instead of Flag!"encryption".yes and No.encryption instead of Flag!"encryption".no.

Examples:

Flag!"abc" flag1;
assert(flag1 == Flag!"abc".no);
assert(flag1 == No.abc);
assert(!flag1);
if (flag1) assert(false);
flag1 = Yes.abc;
assert(flag1);
if (!flag1) assert(false);
if (flag1) {} else assert(false);
assert(flag1 == Yes.abc);

template isBitFlagEnum(E)

Detect whether an enum is of integral type and has only "flag" values (i.e. values with a bit count of exactly 1). Additionally, a zero value is allowed for compatibility with enums including a "None" value.

Examples:

enum A
{
    None,
    A = 1<<0,
    B = 1<<1,
    C = 1<<2,
    D = 1<<3,
}

static assert(isBitFlagEnum!A);

enum B
{
    A,
    B,
    C,
    D // D == 3
}

static assert(!isBitFlagEnum!B);

enum C: double
{
    A = 1<<0,
    B = 1<<1
}

static assert(!isBitFlagEnum!C);

struct BitFlags(E, Flag!"unsafe" unsafe = No.unsafe) if (unsafe || isBitFlagEnum!E);

A typesafe structure for storing combinations of enum values.

This template defines a simple struct to represent bitwise OR combinations of enum values. It can be used if all the enum values are integral constants with a bit count of at most 1, or if the unsafe parameter is explicitly set to Yes. This is much safer than using the enum itself to store the OR combination, which can produce surprising effects like this:

enum E
{
    A = 1<<0,
    B = 1<<1
}
E e = E.A | E.B;
// will throw SwitchError
final switch(e)
{
    case E.A:
        return;
    case E.B:
        return;
}

Examples:

BitFlags can be manipulated with the usual operators

// You can use such an enum with BitFlags straight away
enum Enum
{
    None,
    A = 1<<0,
    B = 1<<1,
    C = 1<<2
}
BitFlags!Enum flags1;
assert(!(flags1 & (Enum.A | Enum.B | Enum.C)));

// You need to specify the $(D unsafe) parameter for enum with custom values
enum UnsafeEnum
{
    A,
    B,
    C,
    D = B|C
}
static assert(!__traits(compiles, { BitFlags!UnsafeEnum flags2; }));
BitFlags!(UnsafeEnum, Yes.unsafe) flags3;

immutable BitFlags!Enum flags_empty;
// A default constructed BitFlags has no value set
assert(!(flags_empty & Enum.A) && !(flags_empty & Enum.B) && !(flags_empty & Enum.C));

// Value can be set with the | operator
immutable BitFlags!Enum flags_A = flags_empty | Enum.A;

// And tested with the & operator
assert(flags_A & Enum.A);

// Which commutes
assert(Enum.A & flags_A);

// BitFlags can be variadically initialized
immutable BitFlags!Enum flags_AB = BitFlags!Enum(Enum.A, Enum.B);
assert((flags_AB & Enum.A) && (flags_AB & Enum.B) && !(flags_AB & Enum.C));

// Use the ~ operator for subtracting flags
immutable BitFlags!Enum flags_B = flags_AB & ~BitFlags!Enum(Enum.A);
assert(!(flags_B & Enum.A) && (flags_B & Enum.B) && !(flags_B & Enum.C));

// You can use the EnumMembers template to set all flags
immutable BitFlags!Enum flags_all = EnumMembers!Enum;

// use & between BitFlags for intersection
immutable BitFlags!Enum flags_BC = BitFlags!Enum(Enum.B, Enum.C);
assert (flags_B == (flags_BC & flags_AB));

// All the binary operators work in their assignment version
BitFlags!Enum temp = flags_empty;
temp |= flags_AB;
assert(temp == (flags_empty | flags_AB));
temp = flags_empty;
temp |= Enum.B;
assert(temp == (flags_empty | Enum.B));
temp = flags_empty;
temp &= flags_AB;
assert(temp == (flags_empty & flags_AB));
temp = flags_empty;
temp &= Enum.A;
assert(temp == (flags_empty & Enum.A));

// BitFlags with no value set evaluate to false
assert(!flags_empty);

// BitFlags with at least one value set evaluate to true
assert(flags_A);

// This can be useful to check intersection between BitFlags
assert(flags_A & flags_AB);
assert(flags_AB & Enum.A);

// Finally, you can of course get you raw value out of flags
auto value = cast(int)flags_A;
assert(value == Enum.A);

template ReplaceType(From, To, T...)

Replaces all occurrences of From into To, in one or more types T. For example, ReplaceType!(int, uint, Tuple!(int, float)[string]) yields Tuple!(uint, float)[string]. The types in which replacement is performed may be arbitrarily complex, including qualifiers, built-in type constructors (pointers, arrays, associative arrays, functions, and delegates), and template instantiations; replacement proceeds transitively through the type definition. However, member types in structs or classes are not replaced because there are no ways to express the types resulting after replacement.

This is an advanced type manipulation necessary e.g. for replacing the placeholder type This in std.variant.Algebraic.

Returns:

ReplaceType aliases itself to the type(s) that result after replacement.

Examples:

static assert(
    is(ReplaceType!(int, string, int[]) == string[]) &&
    is(ReplaceType!(int, string, int[int]) == string[string]) &&
    is(ReplaceType!(int, string, const(int)[]) == const(string)[]) &&
    is(ReplaceType!(int, string, Tuple!(int[], float))
        == Tuple!(string[], float))
);

Library Reference

std.typecons