Boost Exception

exception

namespace
boost
    {
    class
    exception
        {
        public:
    
        virtual char const * diagnostic_information() const throw();    
    
        protected:
    
        exception();
        exception( exception const & x );    
        ~exception();    
        };
    }

Class boost::exception is designed to be used as a universal base for user-defined exception types.

An object of any type deriving from boost::exception can store data of arbitrary types, using the error_info wrapper and operator<<.

To retrieve data from a boost::exception object, use the get_error_info function template.

exception();
exception( exception const & x );

~exception();

virtual char const * diagnostic_information() const throw();

error_info

namespace
boost
    {
    template <class Tag,class T>
    class
    error_info
        {
        public:
    
        typedef T value_type;
    
        error_info( value_type const & );
        };
    }

Requirements:

T must have accessible copy constructor and must not be a reference.

Description:

This class template is used to associate a Tag type with a value type T. Objects of type error_info<Tag,T> can be passed to operator<< to be stored in objects of type boost::exception.

Note:

The header <boost/exception/error_info.hpp> provides a declaration of the error_info template, which is sufficient for the purpose of typedefing an instance for specific Tag and T, like this:

#include <boost/exception/error_info.hpp>

typedef boost::error_info<struct tag_errno,int> errno_info;

Of course, to actually add an errno_info object to exceptions using operator<<, or to retrieve it using get_error_info, you must first #include <boost/exception/info.hpp>.

operator<<, error_info overload

namespace
boost
    {
    template <class E, class Tag, class T>
    E const & operator<<( E const & x, error_info<Tag,T> const & v );
    }

Requirements:

E must be boost::exception, or a type that derives (indirectly) from boost::exception.

Effects:

Stores a copy of v into x. If x already contains data of type error_info<Tag1,T1>, that data is overwritten.

Returns:

x.

get_error_info

namespace
boost
    {
    template <class ErrorInfo,class E>
    shared_ptr<typename ErrorInfo::value_type const> get_error_info( E const & x );
    }

Requirements:

The type of the x object must derive from boost::exception; ErrorInfo must be an instance of the error_info template.

Returns:

If x does not store an object of type ErrorInfo, returns an empty shared_ptr; otherwise returns pointer to the stored value. Use operator<< to store values in exception objects.

Throws:

Nothing.

enable_error_info

namespace
boost
    {
    template <class T>
    ---unspecified--- enable_error_info( T const & x );
    }

Requirements:

T must be a user-defined type with accessible no-throw copy constructor.

Returns:

An object of unspecified type with no-throw copy semantics, which derives publicly from both T, and class boost::exception. The T sub-object is initialized from x by the T copy constructor. If T already derives from boost::exception, then the type of the returned object does not derive boost::exception.

Throws:

Nothing.

BOOST_ERROR_INFO

namespace
boost
    {
    typedef error_info<struct tag_throw_function,char const *> throw_function;
    typedef error_info<struct tag_throw_file,char const *> throw_file;
    typedef error_info<struct tag_throw_line,int> throw_line;
    
    #define BOOST_ERROR_INFO\
        ::boost::throw_function(BOOST_CURRENT_FUNCTION) <<\
        ::boost::throw_file(__FILE__) <<\
        ::boost::throw_line((int)__LINE__)
    }

This macro is designed to be used with operator<< when throwing a boost::exception, to store information about the location of the throw statement. It can be chained with other error_infos in a single throw expression.

exception_ptr

namespace
boost
    {
    typedef ---unspecified--- exception_ptr;
    }

The exception_ptr type can be used to refer to a copy of an exception object. It is Default Constructible, Copy Constructible, Assignable and Equality Comparable; exception_ptr's operations do not throw.

Two instances of exception_ptr are equivalent and compare equal if and only if they refer to the same exception.

The default constructor of exception_ptr produces the null value of the type. The null value is equivalent only to itself.

Note:

exception_ptr objects are returned by current_exception and copy_exception.

enable_current_exception

namespace
boost
    {
    template <class T>
    ---unspecified--- enable_current_exception( T const & e );
    }

Requirements:

T must have an accessible no-throw copy constructor

Returns:

An object of unspecified type which derives publicly from T. That is, the returned object can be intercepted by a catch(T &).

Description:

This function is designed to be used directly in a throw-expression to enable the exception_ptr support in Boost Exception. For example:

class
my_exception:
    public std::exception
    {
    };

....
throw boost::enable_current_exception(my_exception());

Unless enable_current_exception is called at the time an exception object is used in a throw-expression, an attempt to copy it using current_exception may return an exception_ptr which refers to an instance of unknown_exception. See current_exception for details.

Note:

Instead of using the throw keyword directly, it is preferable to call boost::throw_exception. This is guaranteed to throw an exception that derives from boost::exception and supports exception_ptr functionality.

current_exception

namespace
boost
    {
    exception_ptr current_exception();
    }

Requirements:

The current_exception function must not be called outside of a catch block.

Returns:

Throws:

Nothing.

Notes:

copy_exception

namespace
boost
    {
    template <class T>
    exception_ptr copy_exception( T const & e );
    }

Effects:

As if try { throw e; } catch( ... ) { return current_exception(); }

rethrow_exception

namespace
boost
    {
    void rethrow_exception( exception_ptr const & ep );
    }

Precondition:

ep shall not be null.

Throws:

The exception to which ep refers.

unknown_exception

namespace
boost
    {
    class
    unknown_exception:
        public std::exception
        public boost::exception
        {
        ---unspecified---
        };
    }

This type is used by the exception_ptr support in Boost Exception. Please see current_exception.

diagnostic_information

namespace
boost
    {
    std::string diagnostic_information( std::exception const & x );
    }

Returns:

If dynamic_cast<boost::exception *>(&x) is not null, the returned string is initialized by a call to exception::diagnostic_information; otherwise, the returned string combines the output of x.what() and typeid(x).name().

throw_exception

namespace
boost
    {
    #ifdef BOOST_NO_EXCEPTIONS
    
    void throw_exception( std::exception const & e ); // user defined
    
    #else
    
    template <class E>
    void throw_exception( E const & e );
    
    #endif
    }

Requirements:

E must derive publicly from std::exception.

Effects: