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 0f79ae966a.
Library Documentation Index

Safe Numerics

PrevUpHomeNext

exception

Description
enum class safe_numerics_error
enum class safe_numerics_actions
See Also
Header

Description

Here we describe the data types used to refer to exceptional conditions which might occur. Note that when we use the word "exception", we don't mean the C++ term which refers to a data type, but rather the colloquial sense of a anomaly, irregularity, deviation, special case, isolated example, peculiarity, abnormality, oddity; misfit, aberration or out of the ordinary occurrence. This concept of "exception" is more complex that one would think and hence is not manifested by a single simple type. A small number of types work together to implement this concept within the library.

We've leveraged on the std::error_code which is part of the standard library. We don't use all the facilities that it offers so it's not an exact match, but it's useful and works for our purposes.

enum class safe_numerics_error

The following values are those which a numeric result might return. They resemble the standard error codes used by C++ standard exceptions. This resemblance is coincidental and they are wholly unrelated to any codes of similar names. The reason for the resemblance is that the library started it's development using the standard library codes. But as development progressed it became clear that the original codes weren't sufficient so now they stand on their own. Here are a list of error codes. The description of what they mean is

Symbol Description
success successful operation - no error returned
positive_overflow_error A positive number is too large to be represented by the data type
negative_overflow_error The absolute value of a negative number is too large to be represented by the data type.
domain_error the result of an operation is outside the legal range of the result.
range_error an argument to a function or operator is outside the legal range - e.g. sqrt(-1).
precision_overflow_error precision was lost in the course of executing the operation.
underflow_error A number is too close to zero to be represented by the data type.
uninitialized_value According to the C++ standard, the result may be defined by the application. e.g. 16 >> 10 will result the expected result of 0 on most machines.

The above listed codes can be transformed to a instance of type std::error_code with the function:

std::error_code make_error_code(safe_numerics_error e)

This object can be

enum class safe_numerics_actions

The above error codes are classified into groups according to how such exceptions should be handled. The following table shows the possible actions that an error could be mapped to.

Symbol Description
no_action successful operation - no action action required
uninitialized_value report attempt to use an uninitialized value - not currently used
arithmetic_error report an arithmetic error
implementation_defined_behavior report an operation which the C++ standard permits but fails to specify
undefined_behavior report an operation whose result is undefined by the C++ standard.

Translation of a safe_numerics_error into the corresponding safe_numerics_action can be accomplished with the following function:

constexpr enum  safe_numerics_actions
make_safe_numerics_action(const safe_numerics_error & e);

See Also

Header

#include <boost/numeric/safe_numerics/exception.hpp>


PrevUpHomeNext