Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit d3ab4fa067.
Library Documentation Index

Safe Numerics

PrevUpHomeNext

ExceptionPolicy<EP>

Description
Notation
Valid Expressions
dispatch<EP>(const safe_numerics_error & e, const char * msg)
Models
Header

Description

The exception policy specifies what is to occur when a safe operation cannot return a valid result. A type is an ExceptionPolicy if it has functions for handling exceptional events that occur in the course of safe numeric operations.

Notation

EP A type that fulfills the requirements of an ExceptionPolicy
e A code from safe_numerics_error
message A const char * which refers to a text message about the cause of an exception

Valid Expressions

Whenever an operation yield an invalid result, one of the following functions will be invoked.

Expression Return Value Invoked when:
EP::on_arithmetic_error(e, message) void The operation cannot produce valid arithmetic result such as overflows, divide by zero, etc.
EP::on_undefined_behavior(e, message) void The result is undefined by the C++ standard
EP::on_implementation_defined_behavior(e, message) void The result depends upon implementation defined behavior according to the C++ standard
EP::on_uninitialized_value(e, message) void A variable is not initialized

dispatch<EP>(const safe_numerics_error & e, const char * msg)

This function is used to invoke the exception handling policy for a particular exception code.

Synopsis
template<class EP>
constexpr void
dispatch<EP>(const boost::numeric::safe_numerics_error & e, char const * const & msg);
Example of use
#include <boost/safe_numerics/exception_policies.hpp"

dispatch<boost::numeric::loose_exception_policy>(
    boost::numeric::safe_numerics_error::positive_overflow_error, 
    "operation resulted in overflow"
);

Models

The library header <boost/safe_numerics/exception_policies.hpp> contains a number of pre-made exception policies:

  • boost::numeric::loose_exception_policy

    Throw on arithmetic errors, ignore other errors. Some applications ignore these issues and still work and we don't want to update them.

  • boost::numeric::loose_trap_policy

    Same as above in that it doesn't check for various undefined behaviors but traps at compile time for hard arithmetic errors. This policy would be suitable for older embedded systems which depend on bit manipulation operations to work.

  • boost::numeric::strict_exception_policy

    Permit just about anything, throw at runtime on any kind of error. Recommended for new code. Check everything at compile time if possible and runtime if necessary. Trap or Throw as appropriate. Should guarantee code to be portable across architectures.

  • boost::numeric::strict_trap_policy

    Same as above but requires code to be written in such a way as to make it impossible for errors to occur. This naturally will require extra coding effort but might be justified for embedded and/or safety critical systems.

  • boost::numeric::default_exception_policy

    Alias for strict_exception_policy, One would use this first. After experimentation, one might switch to one of the above policies or perhaps use a custom policy.

Header

#include <boost/safe_numerics/concepts/exception_policy.hpp>


PrevUpHomeNext