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.

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

Synopsis of some of std.exception's functions:

string synopsis()
{
    FILE* f = enforce(fopen("some/file"));
    // f is not null from here on
    FILE* g = enforce!WriteException(fopen("some/other/file", "w"));
    // g is not null from here on

    Exception e = collectException(write(g, readln(f)));
    if (e)
    {
        ... an exception occurred...
        ... We have the exception to play around with...
    }

    string msg = collectExceptionMsg(write(g, readln(f)));
    if (msg)
    {
        ... an exception occurred...
        ... We have the message from the exception but not the exception...
    }

    char[] line;
    enforce(readln(f, line));
    return assumeUnique(line);
}

Functions

Name Description
assertNotThrown 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 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 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 Wraps a possibly-throwing expression in a nothrow wrapper so that it can be called by a nothrow function.
collectException 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 Catches and returns the exception thrown from the given expression. If no exception is thrown, then null is returned. E can be void.
collectExceptionMsg 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 Checks whether a given source object contains pointers or references to a given target object.
enforce Enforces that the given value is true.
enforce Enforces that the given value is true.
enforce Enforces that the given value is true.
errnoEnforce Enforces that the given value is true, throwing an ErrnoException if it is not.
handle Handle exceptions thrown from range primitives.
ifThrown 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 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
enforceEx If !value is false, value is returned. Otherwise, new E(msg, file, line) is thrown. Or if E doesn't take a message and can be constructed with new E(file, line), then new E(file, line) will be thrown.

Enum values

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

Authors

Andrei Alexandrescu and Jonathan M Davis

License

Boost License 1.0

Comments