std.exception

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

Members

Aliases

errnoEnforce
alias errnoEnforce = enforce!ErrnoException

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

Classes

ErrnoException
class ErrnoException

Thrown if errors that set errno occur.

Enums

RangePrimitive
enum 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.

Functions

assertNotThrown
auto assertNotThrown(E expression, string msg, string file, size_t 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
void assertThrown(E expression, string msg, string file, size_t 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
immutable(T)[] assumeUnique(T[] array)
immutable(T[U]) assumeUnique(T[U] 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
T assumeWontThrow(T expr, string msg, string file, size_t line)

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

collectException
T collectException(E expression, 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.

collectException
T collectException(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.

collectExceptionMsg
string collectExceptionMsg(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.

doesPointTo
bool doesPointTo(S source, T target)

Checks whether a given source object contains pointers or references to a given target object.

enforce
T enforce(T value, Dg dg)
T enforce(T value, Throwable ex)

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
auto handle(Range input)

Handle exceptions thrown from range primitives.

ifThrown
CommonType!(T1, T2) ifThrown(T1 expression, T2 errorHandler)
CommonType!(T1, T2) ifThrown(T1 expression, T2 delegate(E) errorHandler)
CommonType!(T1, T2) ifThrown(T1 expression, T2 delegate(Exception) 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
bool mayPointTo(S source, T target)

Checks whether a given source object contains pointers or references to a given target object.

Manifest constants

emptyExceptionMsg
enum emptyExceptionMsg;

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

Mixin templates

basicExceptionCtors
mixintemplate basicExceptionCtors()

Convenience mixin for trivially sub-classing exceptions

Templates

enforce
template enforce(E : Throwable = Exception)

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

Examples

Synopis

1 import core.stdc.stdlib : malloc, free;
2 import std.algorithm.comparison : equal;
3 import std.algorithm.iteration : map, splitter;
4 import std.algorithm.searching : endsWith;
5 import std.conv : ConvException, to;
6 import std.range : front, retro;
7 
8 // use enforce like assert
9 int a = 3;
10 enforce(a > 2, "a needs to be higher than 2.");
11 
12 // enforce can throw a custom exception
13 enforce!ConvException(a > 2, "a needs to be higher than 2.");
14 
15 // enforce will return it's input
16 enum size = 42;
17 auto memory = enforce(malloc(size), "malloc failed")[0 .. size];
18 scope(exit) free(memory.ptr);
19 
20 // collectException can be used to test for exceptions
21 Exception e = collectException("abc".to!int);
22 assert(e.file.endsWith("conv.d"));
23 
24 // and just for the exception message
25 string msg = collectExceptionMsg("abc".to!int);
26 assert(msg == "Unexpected 'a' when converting from type string to type int");
27 
28 // assertThrown can be used to assert that an exception is thrown
29 assertThrown!ConvException("abc".to!int);
30 
31 // ifThrown can be used to provide a default value if an exception is thrown
32 assert("x".to!int().ifThrown(0) == 0);
33 
34 // handle is a more advanced version of ifThrown for ranges
35 auto r = "12,1337z32,54".splitter(',').map!(a => to!int(a));
36 auto h = r.handle!(ConvException, RangePrimitive.front, (e, r) => 0);
37 assert(h.equal([12, 0, 54]));
38 assertThrown!ConvException(h.retro.equal([54, 0, 12]));
39 
40 // basicExceptionCtors avoids the boilerplate when creating custom exceptions
41 static class MeaCulpa : Exception
42 {
43     mixin basicExceptionCtors;
44 }
45 e = collectException((){throw new MeaCulpa("diagnostic message");}());
46 assert(e.msg == "diagnostic message");
47 assert(e.file == __FILE__);
48 assert(e.line == __LINE__ - 3);
49 
50 // assumeWontThrow can be used to cast throwing code into `nothrow`
51 void exceptionFreeCode() nothrow
52 {
53     // auto-decoding only throws if an invalid UTF char is given
54     assumeWontThrow("abc".front);
55 }
56 
57 // assumeUnique can be used to cast mutable instance to an `immutable` one
58 // use with care
59 char[] str = "  mutable".dup;
60 str[0 .. 2] = "im";
61 immutable res = assumeUnique(str);
62 assert(res == "immutable");

Meta