std.sumtype

SumType is a generic discriminated union implementation that uses design-by-introspection to generate safe and efficient code. Its features include:

  • Pattern matching.
  • Support for self-referential types.
  • Full attribute correctness (pure, @safe, @nogc, and nothrow are inferred whenever possible).
  • A type-safe and memory-safe API compatible with DIP 1000 (scope).
  • No dependency on runtime type information (TypeInfo).
  • Compatibility with BetterC.

List of examples

var isSumType isSumTypeInstance
tmpl canMatch failedGetMessage get getLvalue getRvalue handlerArgs has Iota match matchImpl
struct SumType TagTuple This
fn destroyIfOwner stride

Types 3

structThis

Placeholder used to refer to the enclosing SumType.

structSumType(Types...) if (is(NoDuplicates!Types == Types) && Types.length > 0)

A tagged union that can hold a single value from any of a specified set of types.

The value in a SumType can be operated on using pattern matching.

To avoid ambiguity, duplicate types are not allowed (but see the "basic usage" example for a workaround).

The special type This can be used as a placeholder to create self-referential types, just like with Algebraic. See the "Recursive SumTypes" example for usage.

A SumType is initialized by default to hold the .init value of its first member type, just like a regular union. The version identifier SumTypeNoDefaultCtor can be used to disable this behavior.

See Also

Algebraic
Fields
bool canHoldTag
Storage storage
Methods
@trusted ref getByIndex(size_t tid)() if (tid < Types.length) inout
bool opEquals(this This, Rhs)(auto ref Rhs rhs) if (!is(CommonType!(This, Rhs) == void))Compares two `SumType`s for equality.
private structTagTuple(typeCounts...)
Fields
size_t[typeCounts.length] tags
Methods
TagTuple fromCaseId(size_t caseId)
size_t toCaseId()
Constructors
this(ref const SumTypes args)

Functions 2

private fnsize_t stride(size_t dim, lengths...)()
private fnvoid destroyIfOwner(T)(ref T value)

Variables 2

private enumvarisSumTypeInstance = is(T == SumType!Args, Args...)

True if T is an instance of the SumType template, otherwise false.

enumvarisSumType = is(T : SumType!Args, Args...)

True if T is a SumType or implicitly converts to one, otherwise false.

Templates 10

tmplmatch(handlers...)

Calls a type-appropriate function with the value held in a SumType.

For each possible type the SumType can hold, the given handlers are checked, in order, to see whether they accept a single argument of that type. The first one that does is chosen as the match for that type. (Note that the first match may not always be the most exact match. See "Avoiding unintentional matches" for one common pitfall.)

Every type must have a matching handler, and every handler must match at least one type. This is enforced at compile time.

Handlers may be functions, delegates, or objects with opCall overloads. If a function with more than one overload is given as a handler, all of the overloads are considered as potential matches.

Templated handlers are also accepted, and will match any type for which they can be implicitly instantiated. (Remember that a spec/expression without an explicit argument type is considered a template.)

If multiple SumTypes are passed to match, their values are passed to the handlers as separate arguments, and matching is done for each possible combination of value types. See "Multiple dispatch" for an example.

Returns

The value returned from the handler that matches the currently-held type.

See Also

visit
Functions
auto ref match(SumTypes...)(auto ref SumTypes args) if (allSatisfy!(isSumType, SumTypes) && args.length > 0)

The actual match function.

Parameters

argsOne or more SumType objects.
tmplcanMatch(alias handler, Ts...) if (Ts.length > 0)

True if handler is a potential match for Ts, otherwise false.

See the documentation for match for a full explanation of how matches are chosen.

tmplIota(size_t n)
tmplmatchImpl(Flag!"exhaustive" exhaustive, handlers...)
Functions
auto ref matchImpl(SumTypes...)(auto ref SumTypes args) if (allSatisfy!(isSumType, SumTypes) && args.length > 0)
tmplhandlerArgs(size_t caseId, typeCounts...)
tmplhas(T)

Checks whether a SumType contains a value of a given type.

The types must match exactly, without implicit conversions.

Parameters

Tthe type to check for.
Functions
bool has(Self)(auto ref Self self) if (isSumType!Self)

The actual has function.

Parameters

selfthe SumType to check.

Returns

true if self contains a T, otherwise false.
bool checkType(Value)(ref Value value)
tmplget(T)

Accesses a SumType's value.

The value must be of the specified type. Use has to check.

Parameters

Tthe type of the value being accessed.
Functions
T get(Self)(auto ref Self self) if (isSumType!Self)

The actual get function.

Parameters

selfthe SumType whose value is being accessed.

Returns

the SumType's value.
tmplfailedGetMessage(Expected, Actual)
tmplgetLvalue(Flag!"try_" try_, T)
Functions
T getLvalue(Value)(ref Value value)
tmplgetRvalue(Flag!"try_" try_, T)
Functions
T getRvalue(Value)(ref Value value)