std.typecons

Encapsulates unique ownership of a resource.

When a Unique!T goes out of scope it will call destroy on the resource T that it manages, unless it is transferred. One important consequence of destroy is that it will call the destructor of the resource T. GC-managed references are not guaranteed to be valid during a destructor call, but other members of T, such as file handles or pointers to malloc memory, will still be valid during the destructor call. This allows the resource T to deallocate or clean up any non-GC resources.

If it is desirable to persist a Unique!T outside of its original scope, then it can be transferred. The transfer can be explicit, by calling release, or implicit, when returning Unique from a function. The resource T can be a polymorphic class object or instance of an interface, in which case Unique behaves polymorphically too.

If T is a value type, then Unique!T will be implemented as a reference to a T.

ditto

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.

See also:

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.

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

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

Perl module by Sean M. Burke.

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.

The name came from

Perl module by Michael G Schwern.

ditto

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

The second version of AutoImplement automatically implements Interface, while deriving from BaseClass.

ditto

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

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

An instance of SafeRefCounted is a reference to a structure, which is referred to as the store, or storage implementation struct in this documentation. The store contains a reference count and the T payload. SafeRefCounted uses malloc to allocate the store. As instances of SafeRefCounted are copied or go out of scope, they will automatically increment or decrement the reference count. When the reference count goes down to zero, SafeRefCounted will call destroy against the payload and call free to deallocate the store. If the T payload contains any references to GC-allocated memory, then SafeRefCounted will add it to the GC memory that is scanned for pointers, and remove it from GC scanning before free is called on the store.

One important consequence of destroy is that it will call the destructor of the T payload. GC-managed references are not guaranteed to be valid during a destructor call, but other members of T, such as file handles or pointers to malloc memory, will still be valid during the destructor call. This allows the T to deallocate or clean up any non-GC resources immediately after the reference count has reached zero.

Without -preview=dip1000, SafeRefCounted is unsafe and should be used with care. No references to the payload should be escaped outside the SafeRefCounted object.

With -preview=dip1000, SafeRefCounted is safe if it's payload is accessed only with the borrow function. Scope semantics can also prevent accidental escaping of refCountedPayload, but it's still up to the user to not destroy the last counted reference while the payload is in use. Due to that, refCountedPayload remains accessible only in @system code.

The autoInit option makes the object ensure the store is automatically initialized. Leaving autoInit == RefCountedAutoInitialize.yes (the default option) is convenient but has the cost of a test whenever the payload is accessed. If autoInit == RefCountedAutoInitialize.no, user code must call either refCountedStore.isInitialized or refCountedStore.ensureInitialized before attempting to access the payload. Not doing so results in null pointer dereference.

If T.this() is annotated with @disable then autoInit must be RefCountedAutoInitialize.no in order to compile.

based on an existing type. Unlike the alias feature,

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

Ditto

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; } ----

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

Ternary type with three truth values:

• Ternary.yes for true
• Ternary.no for false
• Ternary.unknown as an unknown state

Also known as trinary, trivalent, or trilean.

The old version of SafeRefCounted, before borrow existed. Old code may be relying on @safety of some of the member functions which cannot be safe in the new scheme, and can avoid breakage by continuing to use this. SafeRefCounted should be preferred, as this type is outdated and unrecommended for new code.

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

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

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.

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)

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

When called on a Nullable, apply will unpack the value contained in the Nullable, pass it to the function you provide and wrap the result in another Nullable (if necessary). If the Nullable is null, apply will return null itself.

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

ditto

Supports structural based typesafe conversion.

If Source has structural conformance with the interface Targets, wrap creates an internal wrapper class which inherits Targets and wraps the src object, then returns it.

unwrap can be used to extract objects which have been wrapped by wrap.

ditto

ditto

ditto

Borrows the payload of SafeRefCounted for use in fun. Inferred as @safe if fun is @safe and does not escape a reference to the payload. The reference count will be incremented for the duration of the operation, so destroying the last reference will not leave dangling references in fun.

Get the underlying type which a Typedef wraps. If T is not a Typedef it will alias itself to 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.

The class destructor will be called when the result of scoped() is itself destroyed.

Scoped class instances can be embedded in a parent class or struct, just like a child struct instance. Scoped member variables must have type typeof(scoped!Class(args)), and be initialized with a call to scoped. See below for an example.

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.

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.

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