std.typecons

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

Members

Aliases

BlackHole
alias BlackHole(Base) = AutoImplement!(Base, generateEmptyFunction, isAbstractFunction)

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.

ReplaceType
alias ReplaceType(From, To, T...) = ReplaceTypeUnless!(false_, 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.

WhiteHole
alias WhiteHole(Base) = AutoImplement!(Base, generateAssertTrap, isAbstractFunction)

WhiteHole!Base is a subclass of Base which automatically implements all abstract member functions as functions that always fail. These functions simply throw an Error and never return. Whitehole is useful for trapping the use of class member functions that haven't been implemented.

Classes

AutoImplement
class AutoImplement(Base, alias how, alias what = isAbstractFunction)
class AutoImplement(Interface, BaseClass, alias how, alias what = isAbstractFunction)

AutoImplement automatically implements (by default) all abstract member functions in the class or interface Base in specified way.

Enums

RefCountedAutoInitialize
enum RefCountedAutoInitialize

Options regarding auto-initialization of a RefCounted object (see the definition of RefCounted below).

isTuple
eponymoustemplate isTuple(T)

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

Functions

alignForSize
string alignForSize(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).

nullable
auto nullable(T 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.

nullable
auto nullable(T t)

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.

nullableRef
auto nullableRef(T* 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).

rebindable
Rebindable!T rebindable(T obj)

Convenience function for creating a Rebindable using automatic type inference.

rebindable
Rebindable!T rebindable(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.

refCounted
RefCounted!(T, RefCountedAutoInitialize.no) refCounted(T val)

Initializes a RefCounted with val. The template parameter T of RefCounted is inferred from val. This function can be used to move non-copyable values to the heap. It also disables the autoInit option of RefCounted.

reverse
auto reverse(T t)

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

Mixin templates

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

Structs

BitFlags
struct BitFlags(E, Flag!"unsafe" unsafe = No.unsafe)

A typesafe structure for storing combinations of enum values.

No
struct No

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

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

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

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

RefCounted
struct RefCounted(T, RefCountedAutoInitialize autoInit = RefCountedAutoInitialize.yes)

Defines a reference-counted object containing a T value as payload.

Ternary
struct Ternary

Ternary type with three truth values:

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

Unique
struct Unique(T)

Encapsulates unique ownership of a resource.

Yes
struct Yes

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

Templates

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

Rebindable
template Rebindable(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.

ReplaceTypeUnless
template ReplaceTypeUnless(alias pred, From, To, T...)

Like ReplaceType, but does not perform replacement in types for which pred evaluates to true.

Tuple
template 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.

TypedefType
template TypedefType(T)

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

UnqualRef
template UnqualRef(T)

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)

apply
template apply(alias fun)

Unpacks the content of a Nullable, performs an operation and packs it again. Does nothing if isNull.

generateAssertTrap
template generateAssertTrap(C, func...)

Predefined how-policies for AutoImplement. These templates are also used by BlackHole and WhiteHole, respectively.

generateEmptyFunction
template generateEmptyFunction(C, func...)

Predefined how-policies for AutoImplement. These templates are also used by BlackHole and WhiteHole, respectively.

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

scoped
template scoped(T)

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.

tuple
template tuple(Names...)

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

unwrap
template unwrap(Target)

Supports structural based typesafe conversion.

wrap
template wrap(Targets...)

Supports structural based typesafe conversion.

Meta

Authors

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

Suggestion Box / Bug Report