std.traits

Templates with which to extract information about types and symbols at compile time.

License:
Boost License 1.0.

Authors:
Walter Bright, Tomasz Stachowiak (isExpressionTuple), Andrei Alexandrescu, Shin Fujishiro, Robert Clipsham

Source:
std/traits.d

struct Demangle(T);

template defaultInit(T)

template packageName(alias T)

Get the full package name for the given symbol.

Example:

 import std.traits;
 static assert(packageName!(packageName) == "std");

template moduleName(alias T)

Get the module name (including package) for the given symbol.

Example:

 import std.traits;
 static assert(moduleName!(moduleName) == "std.traits");

template fullyQualifiedName(alias T)

Get the fully qualified name of a symbol.

Example:

 import std.traits;
 static assert(fullyQualifiedName!(fullyQualifiedName) == "std.traits.fullyQualifiedName");

template ReturnType(func...) if (func.length == 1 && isCallable!(func))

Get the type of the return value from a function, a pointer to function, a delegate, a struct with an opCall, a pointer to a struct with an opCall, or a class with an opCall.

Example:

 import std.traits;
 int foo();
 ReturnType!(foo) x;   // x is declared as int

template ParameterTypeTuple(func...) if (func.length == 1 && isCallable!(func))

Get, as a tuple, the types of the parameters to a function, a pointer to function, a delegate, a struct with an opCall, a pointer to a struct with an opCall, or a class with an opCall.

Example:

import std.traits;
int foo(int, long);
void bar(ParameterTypeTuple!(foo));      // declares void bar(int, long);
void abc(ParameterTypeTuple!(foo)[1]);   // declares void abc(long);

enum ParameterStorageClass; template ParameterStorageClassTuple(func...) if (func.length == 1 && isCallable!(func))

Returns a tuple consisting of the storage classes of the parameters of a function func.

Example:

alias ParameterStorageClass STC; // shorten the enum name

void func(ref int ctx, out real result, real param)
{
}
alias ParameterStorageClassTuple!(func) pstc;
static assert(pstc.length == 3); // three parameters
static assert(pstc[0] == STC.ref_);
static assert(pstc[1] == STC.out_);
static assert(pstc[2] == STC.none);

none scope_ out_ ref_ lazy_: These flags can be bitwise OR-ed together to represent complex storage class. ditto

enum FunctionAttribute; template functionAttributes(func...) if (func.length == 1 && isCallable!(func))

Returns the attributes attached to a function func.

Example:

alias FunctionAttribute FA; // shorten the enum name

real func(real x) pure nothrow @safe
{
    return x;
}
static assert(functionAttributes!(func) & FA.pure_);
static assert(functionAttributes!(func) & FA.safe);
static assert(!(functionAttributes!(func) & FA.trusted)); // not @trusted

none pure_ nothrow_ ref_ property trusted safe: These flags can be bitwise OR-ed together to represent complex attribute. ditto

template isSafe(alias func)

Checks the func that is @safe or @trusted

Example:

@system int add(int a, int b) {return a+b;}
@safe int sub(int a, int b) {return a-b;}
@trusted int mul(int a, int b) {return a*b;}

static assert(!isSafe!(add));
static assert( isSafe!(sub));
static assert( isSafe!(mul));

template areAllSafe(funcs...) if (funcs.length > 0)

Checks the all functions are @safe or @trusted

Example:

@system int add(int a, int b) {return a+b;}
@safe int sub(int a, int b) {return a-b;}
@trusted int mul(int a, int b) {return a*b;}

static assert(!areAllSafe!(add, sub));
static assert( areAllSafe!(sub, mul));

template isUnsafe(alias func)

Checks the func that is @system

Example:

@system int add(int a, int b) {return a+b;}
@safe int sub(int a, int b) {return a-b;}
@trusted int mul(int a, int b) {return a*b;}

static assert( isUnsafe!(add));
static assert(!isUnsafe!(sub));
static assert(!isUnsafe!(mul));

template functionLinkage(func...) if (func.length == 1 && isCallable!(func))

Returns the calling convention of function as a string.

Example:

string a = functionLinkage!(writeln!(string, int));
assert(a == "D"); // extern(D)

auto fp = &printf;
string b = functionLinkage!(fp);
assert(b == "C"); // extern(C)

enum Variadic; template variadicFunctionStyle(func...) if (func.length == 1 && isCallable!(func))

Determines what kind of variadic parameters function has.

Example:

void func() {}
static assert(variadicFunctionStyle!(func) == Variadic.no);

extern(C) int printf(in char*, ...);
static assert(variadicFunctionStyle!(printf) == Variadic.c);

no: Function is not variadic.
c: Function is a C-style variadic function.
d: Function is a D-style variadic function, which uses _argptr and _arguments.
typesafe: Function is a typesafe variadic function.

template FunctionTypeOf(func...) if (func.length == 1 && isCallable!(func))

Get the function type from a callable object func.

Using builtin typeof on a property function yields the types of the property value, not of the property function itself. Still, FunctionTypeOf is able to obtain function types of properties.

class C
{
    int value() @property;
}
static assert(is( typeof(C.value) == int ));
static assert(is( FunctionTypeOf!(C.value) == function ));

Note:
Do not confuse function types with function pointer types; function types are usually used for compile-time reflection purposes.

template FieldTypeTuple(S)

Get the types of the fields of a struct or class. This consists of the fields that take up memory space, excluding the hidden fields like the virtual function table pointer.

template RepresentationTypeTuple(T)

Get the primitive types of the fields of a struct or class, in topological order.

Example:

struct S1 { int a; float b; }
struct S2 { char[] a; union { S1 b; S1 * c; } }
alias RepresentationTypeTuple!(S2) R;
assert(R.length == 4
    && is(R[0] == char[]) && is(R[1] == int)
    && is(R[2] == float) && is(R[3] == S1*));

template hasAliasing(T...)

Returns true if and only if T's representation includes at least one of the following:

a raw pointer U* and U is not immutable;
an array U[] and U is not immutable;
a reference to a class or interface type C and C is not immutable.
an associative array that is not immutable.
a delegate.

template hasIndirections(T)

Returns true if and only if T's representation includes at least one of the following:

a raw pointer U*;
an array U[];
a reference to a class type C.
an associative array.
a delegate.

template hasUnsharedAliasing(T...)

Returns true if and only if T's representation includes at least one of the following:

a raw pointer U* and U is not immutable or shared;
an array U[] and U is not immutable or shared;
a reference to a class type C and C is not immutable or shared.
an associative array that is not immutable or shared.
a delegate that is not shared.

template hasElaborateCopyConstructor(S)

True if S or any type embedded directly in the representation of S defines an elaborate copy constructor. Elaborate copy constructors are introduced by defining this(this) for a struct. (Non-struct types never have elaborate copy constructors.)

template hasElaborateAssign(S)

True if S or any type directly embedded in the representation of S defines an elaborate assignmentq. Elaborate assignments are introduced by defining opAssign(typeof(this)) or opAssign(ref typeof(this)) for a struct. (Non-struct types never have elaborate assignments.)

template hasElaborateDestructor(S)

True if S or any type directly embedded in the representation of S defines an elaborate destructor. Elaborate destructors are introduced by defining ~this() for a struct. (Non-struct types never have elaborate destructors, even though classes may define ~this().)

template hasMember(T,string name)

Yields true if and only if T is an aggregate that defines a symbol called name.

template EnumMembers(E) if (is(E == enum))

Retrieves the members of an enumerated type enum E.

Parameters:

E	An enumerated type. E may have duplicated values.

Returns:
Static tuple composed of the members of the enumerated type E. The members are arranged in the same order as declared in E.

Note:
Returned values are strictly typed with E. Thus, the following code does not work without the explicit cast:

enum E : int { a, b, c }
int[] abc = cast(int[]) [ EnumMembers!E ];

Cast is not necessary if the type of the variable is inferred. See the example below.

Examples:
Creating an array of enumerated values:

enum Sqrts : real
{
    one   = 1,
    two   = 1.41421,
    three = 1.73205,
}
auto sqrts = [ EnumMembers!Sqrts ];
assert(sqrts == [ Sqrts.one, Sqrts.two, Sqrts.three ]);

A generic function rank(v) in the following example uses this template for finding a member e in an enumerated type E.

// Returns i if e is the i-th enumerator of E.
size_t rank(E)(E e)
    if (is(E == enum))
{
    foreach (i, member; EnumMembers!E)
    {
        if (e == member)
            return i;
    }
    assert(0, "Not an enum member");
}

enum Mode
{
    read  = 1,
    write = 2,
    map   = 4,
}
assert(rank(Mode.read ) == 0);
assert(rank(Mode.write) == 1);
assert(rank(Mode.map  ) == 2);

template BaseTypeTuple(A)

Get a TypeTuple of the base class and base interfaces of this class or interface. BaseTypeTuple!(Object) returns the empty type tuple.

Example:

 import std.traits, std.typetuple, std.stdio;
 interface I { }
 class A { }
 class B : A, I { }

 void main()
 {
     alias BaseTypeTuple!(B) TL;
     writeln(typeid(TL));        // prints: (A,I)
 }

template BaseClassesTuple(T)

Get a TypeTuple of all base classes of this class, in decreasing order. Interfaces are not included. BaseClassesTuple!(Object) yields the empty type tuple.

Example:

 import std.traits, std.typetuple, std.stdio;
 interface I { }
 class A { }
 class B : A, I { }
 class C : B { }

 void main()
 {
     alias BaseClassesTuple!(C) TL;
     writeln(typeid(TL));        // prints: (B,A,Object)
 }

template InterfacesTuple(T)

Get a TypeTuple of all interfaces directly or indirectly inherited by this class or interface. Interfaces do not repeat if multiply implemented. InterfacesTuple!(Object) yields the empty type tuple.

Example:

 import std.traits, std.typetuple, std.stdio;
 interface I1 { }
 interface I2 { }
 class A : I1, I2 { }
 class B : A, I1 { }
 class C : B { }

 void main()
 {
     alias InterfacesTuple!(C) TL;
     writeln(typeid(TL));        // prints: (I1, I2)
 }

template TransitiveBaseTypeTuple(T)

Get a TypeTuple of all base classes of T, in decreasing order, followed by T's interfaces. TransitiveBaseTypeTuple!(Object) yields the empty type tuple.

Example:

 import std.traits, std.typetuple, std.stdio;
 interface I { }
 class A { }
 class B : A, I { }
 class C : B { }

 void main()
 {
     alias TransitiveBaseTypeTuple!(C) TL;
     writeln(typeid(TL));        // prints: (B,A,Object,I)
 }

template MemberFunctionsTuple(C,string name) if (is(C == class) || is(C == interface))

Returns a tuple of non-static functions with the name name declared in the class or interface C. Covariant duplicates are shrunk into the most derived one.

Example:

interface I { I foo(); }
class B
{
    real foo(real v) { return v; }
}
class C : B, I
{
    override C foo() { return this; } // covariant overriding of I.foo()
}
alias MemberFunctionsTuple!(C, "foo") foos;
static assert(foos.length == 2);
static assert(__traits(isSame, foos[0], C.foo));
static assert(__traits(isSame, foos[1], B.foo));

template CommonType(T...)

Get the type that all types can be implicitly converted to. Useful e.g. in figuring out an array type from a bunch of initializing values. Returns void if passed an empty list, or if the types have no common type.

Example:

alias CommonType!(int, long, short) X;
assert(is(X == long));
alias CommonType!(int, char[], short) Y;
assert(is(Y == void));

template ImplicitConversionTargets(T)

Returns a tuple with all possible target types of an implicit conversion of a value of type T.

Important note:

The possible targets are computed more conservatively than the D 2.005 compiler does, eliminating all dangerous conversions. For example, ImplicitConversionTargets!(double) does not include float.

template isImplicitlyConvertible(From,To)

Is From implicitly convertible to To?

template isAssignable(Lhs,Rhs)

Returns true iff a value of type Rhs can be assigned to a variable of type Lhs.

Examples:

static assert(isAssignable!(long, int));
static assert(!isAssignable!(int, long));
static assert( isAssignable!(const(char)[], string));
static assert(!isAssignable!(string, char[]));

template isCovariantWith(F,G) if (is(F == function) && is(G == function))

Determines whether the function type F is covariant with G, i.e., functions of the type F can override ones of the type G.

Example:

interface I { I clone(); }
interface J { J clone(); }
class C : I
{
    override C clone()   // covariant overriding of I.clone()
    {
        return new C;
    }
}

// C.clone() can override I.clone(), indeed.
static assert(isCovariantWith!(typeof(C.clone), typeof(I.clone)));

// C.clone() can't override J.clone(); the return type C is not implicitly
// convertible to J.
static assert(isCovariantWith!(typeof(C.clone), typeof(J.clone)));

template isBoolean(T)

Detect whether we can treat T as a built-in boolean type.

template isIntegral(T)

Detect whether we can treat T as a built-in integral type. Types bool, char, wchar, and dchar are not considered integral.

template isFloatingPoint(T)

Detect whether we can treat T as a built-in floating point type.

template isNumeric(T)

Detect whether we can treat T as a built-in numeric type (integral or floating point).

template isUnsigned(T)

Detect whether T is a built-in unsigned numeric type.

template isSigned(T)

Detect whether T is a built-in signed numeric type.

template isSomeChar(T)

Detect whether we can treat T as one of the built-in character types.

template isSomeString(T)

Detect whether we can treat T as one of the built-in string types.

template isStaticArray(T : U[N],U,size_t N)

Detect whether type T is a static array.

template isDynamicArray(T,U = void)

Detect whether type T is a dynamic array.

template isArray(T)

Detect whether type T is an array.

template isAssociativeArray(T)

Detect whether T is an associative array type

template isPointer(T)

Detect whether type T is a pointer.

template pointerTarget(T : T*)

Returns the target type of a pointer.

template isIterable(T)

Returns true if T can be iterated over using a foreach loop with a single loop variable of automatically inferred type, regardless of how the foreach loop is implemented. This includes ranges, structs/classes that define opApply with a single loop variable, and builtin dynamic, static and associative arrays.

template isExpressionTuple(T...)

Tells whether the tuple T is an expression tuple.

template isTypeTuple(T...)

Detect whether tuple T is a type tuple.

template isFunctionPointer(T...) if (T.length == 1)

Detect whether symbol or type T is a function pointer.

template isDelegate(T...) if (T.length == 1)

Detect whether T is a delegate.

template isSomeFunction(T...) if (T.length == 1)

Detect whether symbol or type T is a function, a function pointer or a delegate.

template isCallable(T...) if (T.length == 1)

Detect whether T is a callable object, which can be called with the function call operator (...).

template isAbstractFunction(method...) if (method.length == 1)

Exactly the same as the builtin traits: __traits(isAbstractFunction, method).

template Unqual(T)

Removes all qualifiers, if any, from type T.

Example:

static assert(is(Unqual!(int) == int));
static assert(is(Unqual!(const int) == int));
static assert(is(Unqual!(immutable int) == int));
static assert(is(Unqual!(shared int) == int));
static assert(is(Unqual!(shared(const int)) == int));

template ForeachType(T)

Returns the inferred type of the loop variable when a variable of type T is iterated over using a foreach loop with a single loop variable and automatically inferred return type. Note that this may not be the same as std.range.ElementType!(Range) in the case of narrow strings, or if T has both opApply and a range interface.

template OriginalType(T)

Strips off all typedefs (including enum ones) from type T.

Example:

enum E : int { a }
typedef E F;
typedef const F G;
static assert(is(OriginalType!G == const int));

template Unsigned(T)

Returns the corresponding unsigned type for T. T must be a numeric integral type, otherwise a compile-time error occurs.

template Largest(T...) if (T.length >= 1)

Returns the largest type, i.e. T such that T.sizeof is the largest. If more than one type is of the same size, the leftmost argument of these in will be returned.

template Signed(T)

Returns the corresponding signed type for T. T must be a numeric integral type, otherwise a compile-time error occurs.

auto unsigned(T)(T x);

Returns the corresponding unsigned value for x, e.g. if x has type int, returns cast(uint) x. The advantage compared to the cast is that you do not need to rewrite the cast if x later changes type to e.g. long.

template mostNegative(T)

Returns the most negative value of the numeric type T.

template mangledName(sth...) if (sth.length == 1)

Returns the mangled name of symbol or type sth.

mangledName is the same as builtin .mangleof property, except that the correct names of property functions are obtained.

module test;
import std.traits : mangledName;

class C
{
    int value() @property;
}
pragma(msg, C.value.mangleof);      // prints "i"
pragma(msg, mangledName!(C.value)); // prints "_D4test1C5valueMFNdZi"

template Select(bool condition,T,F)

Aliases itself to T if the boolean condition is true and to F otherwise.

Example:

alias Select!(size_t.sizeof == 4, int, long) Int;

A select(bool cond : true, A, B)(A a, lazy B b); B select(bool cond : false, A, B)(lazy A a, B b);

If cond is true, returns a without evaluating b. Otherwise, returns b without evaluating a.

std

etc

core

std.traits