Boost Exception

exception

namespace
boost
    {
    class
    exception
        {
        public:

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

        protected:

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

        private:

        ---unspecified---
        };
    }

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 * what() const throw();

error_info

namespace
boost
    {
    template <class Tag,class T>
    class
    error_info
        {
        public:

        typedef T value_type;

        error_info( value_type const & );

        private:

        ---unspecified---
        };
    }

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<<()

namespace
boost
    {
    template <class E, class Tag1, class T1>
    E const & operator<<( E const & x, error_info<Tag1,T1> const & v );

    template <class E, class Tag1, class T1, ..., class TagN, class TN>
    E const & operator<<( E const & x,
        tuple<
            error_info<Tag1,T1>,
            ...,
            error_info<TagN,TN> > const & v );
    }

Requirements:

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

Effects:

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 cloning 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, any attempt to copy it using current_exception() returns an exception_ptr which refers to an instance of unknown_exception.

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 cloning.

current_exception()

namespace
boost
    {
    exception_ptr current_exception();
    }

Requirements:

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

Returns:

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 cloning support in Boost Exception. Please see current_exception().

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
    }

Effects: