Display the source code in std/exception.d from which this page was generated on github.

If you spot a problem with this page, click here to create a Bugzilla issue.

Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone.

Module `std.exception`

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


Category	Functions
Assumptions	`assertNotThrown` `assertThrown` `assumeUnique` `assumeWontThrow` `mayPointTo`
Enforce	`doesPointTo` `enforce` `errnoEnforce`
Handlers	`collectException` `collectExceptionMsg` `ifThrown` `handle`
Other	`basicExceptionCtors` `emptyExceptionMsg` `ErrnoException` `RangePrimitive`

Example

Synopis

import core.stdc.stdlib : malloc, free;
import std.algorithm.comparison : equal;
import std.algorithm.iteration : map, splitter;
import std.algorithm.searching : endsWith;
import std.conv : ConvException, to;
import std.range : front, retro;

// use enforce like assert
int a = 3;
enforce(a > 2, "a needs to be higher than 2.");

// enforce can throw a custom exception
enforce!ConvException(a > 2, "a needs to be higher than 2.");

// enforce will return it's input
enum size = 42;
auto memory = enforce(malloc(size), "malloc failed")[0 .. size];
scope(exit) free(memory.ptr);

// collectException can be used to test for exceptions
Exception e = collectException("abc".to!int);
assert(e.file.endsWith("conv.d"));

// and just for the exception message
string msg = collectExceptionMsg("abc".to!int);
writeln(msg); // "Unexpected 'a' when converting from type string to type int"

// assertThrown can be used to assert that an exception is thrown
assertThrown!ConvException("abc".to!int);

// ifThrown can be used to provide a default value if an exception is thrown
writeln("x".to!int().ifThrown(0)); // 0

// handle is a more advanced version of ifThrown for ranges
auto r = "12,1337z32,54".splitter(',').map!(a => to!int(a));
auto h = r.handle!(ConvException, RangePrimitive.front, (e, r) => 0);
assert(h.equal([12, 0, 54]));
assertThrown!ConvException(h.retro.equal([54, 0, 12]));

// basicExceptionCtors avoids the boilerplate when creating custom exceptions
static class MeaCulpa : Exception
{
    mixin basicExceptionCtors;
}
e = collectException((){throw new MeaCulpa("diagnostic message");}());
writeln(e.msg); // "diagnostic message"
writeln(e.file); // __FILE__
writeln(e.line); // __LINE__ - 3

// assumeWontThrow can be used to cast throwing code into `nothrow`
void exceptionFreeCode() nothrow
{
    // auto-decoding only throws if an invalid UTF char is given
    assumeWontThrow("abc".front);
}

// assumeUnique can be used to cast mutable instance to an `immutable` one
// use with care
char[] str = "  mutable".dup;
str[0 .. 2] = "im";
immutable res = assumeUnique(str);
writeln(res); // "immutable"

Functions

Name	Description
`assertNotThrown(expression, msg, file, 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 `AssertError` is thrown. However, any other `Throwable`s will escape.
`assertThrown(expression, msg, file, 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` of the given type is thrown, then an `AssertError` is thrown.
`assumeUnique(array)`	Casts 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)` should only be called when there are no more active mutable aliases to elements of `arr`. To strengthen this assumption, `assumeUnique(arr)` also clears `arr` before returning. Essentially `assumeUnique(arr)` indicates commitment from the caller that there is no more mutable access to any of `arr`'s elements (transitively), and that all future accesses will be done through the immutable array returned by `assumeUnique`.
`assumeWontThrow(expr, msg, file, line)`	Wraps a possibly-throwing expression in a `nothrow` wrapper so that it can be called by a `nothrow` function.
`collectException(expression, 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.
`collectException(expression)`	Catches and returns the exception thrown from the given expression. If no exception is thrown, then null is returned. `E` can be `void`.
`collectExceptionMsg(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`.
`doesPointTo(source, target)`	Checks whether a given source object contains pointers or references to a given target object.
`enforce(value, dg)`	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
`handle(input)`	Handle exceptions thrown from range primitives.
`ifThrown(expression, 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. The error handler's type must be the same as the expression's type.
`mayPointTo(source, target)`	Checks whether a given source object contains pointers or references to a given target object.

Classes

Name	Description
`ErrnoException`	Thrown if errors that set `errno` occur.

Enums

Name	Description
`RangePrimitive`	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.

Templates

Name	Description
`basicExceptionCtors`	Convenience mixin for trivially sub-classing exceptions
`enforce`	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

Manifest constants

Name	Type	Description
`emptyExceptionMsg`		Value that collectExceptionMsg returns when it catches an exception with an empty exception message.

Aliases

Name	Type	Description
`errnoEnforce`	`enforce!ErrnoException`	Enforces that the given value is true, throwing an `ErrnoException` if it is not.

Authors

Andrei Alexandrescu and Jonathan M Davis

License

Boost License 1.0