std.exception

This module defines functions related to exceptions and general error handling. It also defines functions intended to aid in unit testing.

Copyright

License

Boost License 1.0

Authors

Andrei Alexandrescu and Jonathan M Davis

Source: std/exception.d

var emptyExceptionMsg

tmpl enforce

alias errnoEnforce

enum RangePrimitive

class ErrnoException

fn assertNotThrown assertThrown assumeUnique assumeWontThrow bailOut collectException collectExceptionMsg doesPointTo enforce errnoString handle ifThrown isUnionAliasedImpl mayPointTo

Types 3

aliaserrnoEnforce = enforce!ErrnoException

Enforces that the given value is true, throwing an ErrnoException if it is not.

Parameters

`value`	The value to test.
`msg`	The message to include in the `ErrnoException` if it is thrown.

Returns

value, if cast(bool) value is true. Otherwise, new ErrnoException(msg) is thrown. It is assumed that the last

operation set errno to an error code corresponding with the failed condition.

classErrnoException : Exception

Thrown if errors that set errno occur.

Fields

private uint _errno

private string _errnoMsg

Methods

uint errno() @property nothrow pure scope @nogc @safeOperating system error code.

string errnoMsg() @property nothrow pure scope @nogc @safeLocalized error message generated through strerror_r or strerror.

Constructors

this(string msg, string file = null, size_t line = 0)Constructor which takes an error message. The current global errno value is used as error code.

this(string msg, int errno, string file = null, size_t line = 0)Constructor which takes an error message and error code.

enumRangePrimitive

This enum is used to select the primitives of the range to handle by the

handle range wrapper. The values of the enum can be OR'd to

select multiple primitives to be handled.

RangePrimitive.access is a shortcut for the access primitives; front, back and opIndex.

RangePrimitive.pop is a shortcut for the mutating primitives; popFront and popBack.

front = 0b00_0000_0001

back = 0b00_0000_0010Ditto

popFront = 0b00_0000_0100Ditto

popBack = 0b00_0000_1000Ditto

empty = 0b00_0001_0000Ditto

save = 0b00_0010_0000Ditto

length = 0b00_0100_0000Ditto

opDollar = 0b00_1000_0000Ditto

opIndex = 0b01_0000_0000Ditto

opSlice = 0b10_0000_0000Ditto

access = front | back | opIndexDitto

pop = popFront | popBackDitto

Functions 22

auto assertNotThrown(T :  Throwable =  Exception,  E)(lazy  E expression,
                      string msg =  null,
                      string file =  __FILE__,
                      size_t line =  __LINE__)

Asserts that the given expression does not throw the given type of `Throwable`. If a `Throwable` of the given type is thrown, it is caught and does not escape assertNotThrown. Rather, an `AssertErr...

void assertThrown(T :  Throwable =  Exception,  E)(lazy  E expression,
                   string msg =  null,
                   string file =  __FILE__,
                   size_t line =  __LINE__)

Asserts that the given expression throws the given type of `Throwable`. The `Throwable` is caught and does not escape assertThrown. However, any other `Throwable`s will escape, and if no `Throwable...

T enforce(T,  Dg,  string file =  __FILE__,  size_t line =  __LINE__)(T value,  scope  Dg dg) if (isSomeFunction!Dg &&  is(typeof(  dg() ))  &&
     is(typeof({  if (!value)  { }  })))

ditto

fnT enforce(T)(T value, lazy Throwable ex)ditto

private fnnoreturn bailOut(E : Throwable = Exception)(string file, size_t line, scope const(char)[] msg)

fnT collectException(T = Exception, E)(lazy E expression, ref E result)Catches and returns the exception thrown from the given expression. If no exception is thrown, then null is returned and `result` is set to the result of the expression.

fnT collectException(T : Throwable = Exception, E)(lazy E expression)Catches and returns the exception thrown from the given expression. If no exception is thrown, then null is returned. `E` can be `void`.

fnstring collectExceptionMsg(T = Exception, E)(lazy E expression)Catches the exception thrown from the given expression and returns the msg property of that exception. If no exception is thrown, then null is returned. `E` can be `void`.

fnimmutable(T)[] assumeUnique(T)(T[] array) pure nothrowCasts a mutable array to an immutable array in an idiomatic manner. Technically, `assumeUnique` just inserts a cast, but its name documents assumptions on the part of the caller. `assumeUnique(arr)...

fnimmutable(T)[] assumeUnique(T)(ref T[] array) pure nothrowditto

fnimmutable(T[U]) assumeUnique(T, U)(ref T[U] array) pure nothrowditto

T assumeWontThrow(T)(lazy  T expr,
                      string msg =  null,
                      string file =  __FILE__,
                      size_t line =  __LINE__)

nothrowWraps a possibly-throwing expression in a `nothrow` wrapper so that it can be called by a `nothrow` function.

bool doesPointTo(S,  T,  Tdummy = void)(auto  ref  const  S source,  ref  const  T target) if (__traits(isRef,  source)  ||  isDynamicArray!S ||
     is(S ==  U *,  U)  ||  is(S ==  class))

@nogc @trusted pure nothrowChecks whether a given source object contains pointers or references to a given target object.

fnbool doesPointTo(S, T)(auto ref const shared S source, ref const shared T target) @trusted pure nothrowditto

bool mayPointTo(S,  T,  Tdummy = void)(auto  ref  const  S source,  ref  const  T target) if (__traits(isRef,  source)  ||  isDynamicArray!S ||
     is(S ==  U *,  U)  ||  is(S ==  class))

@trusted pure nothrowditto

fnbool mayPointTo(S, T)(auto ref const shared S source, ref const shared T target) @trusted pure nothrowditto

private fnbool isUnionAliasedImpl(T)(size_t offset)

fnstring errnoString(int errno) nothrow @trusted

CommonType!(T1,  T2) ifThrown(E :  Throwable =  Exception,  T1,  T2)(lazy  scope  T1 expression,  lazy  scope  T2 errorHandler)

ML-style functional exception handling. Runs the supplied expression and returns its result. If the expression throws a `Throwable`, runs the supplied error handler instead and return its result. T...

CommonType!(T1,  T2) ifThrown(E :  Throwable,  T1,  T2)(lazy  scope  T1 expression,  scope  T2 delegate(E)  errorHandler)

ditto

fnCommonType!(T1, T2) ifThrown(T1, T2)(lazy scope T1 expression, scope T2 delegate(Exception) errorHandler)ditto

auto handle(E :  Throwable,  RangePrimitive primitivesToHandle,  alias  handler,  Range)(Range input) if (isInputRange!Range)

Handle exceptions thrown from range primitives.

Variables 1

enumvaremptyExceptionMsg = "<Empty Exception Message>"

Value that collectExceptionMsg returns when it catches an exception with an empty exception message.

Templates 1

tmplenforce(E : Throwable = Exception)

if (is(typeof(new  E("",  string.init,  size_t.init)) :  Throwable)  ||
     is(typeof(new  E(string.init,  size_t.init)) :  Throwable))

Enforces that the given value is true. If the given value is false, an exception is thrown. The

msg - error message as a string
dg - custom delegate that return a string and is only called if an exception occurred
ex - custom exception to be thrown. It is lazy and is only created if an exception occurred

Parameters

`value`	The value to test.
`E`	Exception type to throw if the value evaluates to false.
`msg`	The error message to put in the exception if it is thrown.
`dg`	The delegate to be called if the value evaluates to false.
`ex`	The exception to throw if the value evaluates to false.
`file`	The source file of the caller.
`line`	The line number of the caller.

Returns

value, if cast(bool) value is true. Otherwise,

depending on the chosen overload, new Exception(msg), dg() or ex is thrown.

Note

enforce is used to throw exceptions and is therefore intended to

aid in error handling. It is not intended for verifying the logic of your program - that is what assert is for.

Do not use enforce inside of contracts (i.e. inside of in and out blocks and invariants), because contracts are compiled out when compiling with -release.

If a delegate is passed, the safety and purity of this function are inferred from Dg's safety and purity.

Functions

T enforce(T)(T value, lazy const(char)[] msg = null, string file = __FILE__, size_t line = __LINE__) if (is(typeof({ if (!value) { } })))