View source code
Display the source code in std/exception.d from which this page was generated on github.
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
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.

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

NameDescription
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 Throwables 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 Throwables 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

NameDescription
ErrnoException Thrown if errors that set errno occur.

Enums

NameDescription
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

NameDescription
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

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

Aliases

NameTypeDescription
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