Description

The header <boost/throw_exception.hpp> provides a common Boost infrastructure for throwing exceptions, in the form of a function boost::throw_exception and a macro BOOST_THROW_EXCEPTION.

boost::throw_exception(x); is a replacement for throw x; that both degrades gracefully when exception handling support is not available, and integrates the thrown exception into facilities provided by Boost.Exception, such as automatically providing a base class of type boost::exception and support for boost::exception_ptr.

When exception handling is not available, the function is only declared, but not defined. This allows users to provide their own definition.

An overload for boost::throw_exception that takes a boost::source_location is provided. It records the supplied source location into the boost::exception base class, from where it can later be retrieved when the exception is caught. boost::diagnostic_information automatically displays the stored source location.

The macro BOOST_THROW_EXCEPTION(x) expands to ::boost::throw_exception(x, BOOST_CURRENT_LOCATION), passing the current source location.

Examples

Using BOOST_THROW_EXCEPTION

#include <boost/throw_exception.hpp>
#include <boost/exception/diagnostic_information.hpp>
#include <stdexcept>
#include <iostream>

void f()
{
    BOOST_THROW_EXCEPTION( std::runtime_error( "Unspecified runtime error" ) );
}

int main()
{
    try
    {
        f();
    }
    catch( std::exception const & x )
    {
        std::cerr << boost::diagnostic_information( x ) << std::endl;
    }
}

Using boost::throw_exception with a source location

#include <boost/throw_exception.hpp>
#include <boost/lexical_cast.hpp>
#include <boost/exception/diagnostic_information.hpp>
#include <stdexcept>
#include <cstddef>
#include <iostream>

void throw_index_error( std::size_t i, std::size_t n,
  boost::source_location const & loc )
{
    std::string msg = "Index out of range: "
      + boost::lexical_cast<std::string>( i ) + " >= "
      + boost::lexical_cast<std::string>( n );

    boost::throw_exception( std::out_of_range( msg ), loc );
}

void f1( std::size_t i, std::size_t n )
{
    if( i >= n )
    {
        throw_index_error( i, n, BOOST_CURRENT_LOCATION );
    }
}

void f2( std::size_t i, std::size_t n )
{
    if( i >= n )
    {
        throw_index_error( i, n, BOOST_CURRENT_LOCATION );
    }
}

int main()
{
    try
    {
        f1( 4, 3 );
    }
    catch( std::exception const & x )
    {
        std::cerr << boost::diagnostic_information( x ) << std::endl;
    }
}

Revision History

Changes in 1.73.0

  • Added an overload of throw_exception that takes a boost::source_location object.

Note
 Projects using BOOST_THROW_EXCEPTION with exceptions disabled will need to add a definition of this new overload.

Reference

<boost/throw_exception.hpp> Synopsis

#include <boost/assert/source_location.hpp>
#include <boost/config.hpp>
#include <exception>

namespace boost
{

#if defined( BOOST_NO_EXCEPTIONS )

BOOST_NORETURN void throw_exception( std::exception const & e ); // user defined

BOOST_NORETURN void throw_exception( std::exception const & e,
  boost::source_location const & loc ); // user defined

#else

template<class E> BOOST_NORETURN void throw_exception( E const & e );

template<class E> BOOST_NORETURN void throw_exception( E const & e,
  boost::source_location const & loc );

#endif

} // namespace boost

#define BOOST_THROW_EXCEPTION(x) \
  ::boost::throw_exception(x, BOOST_CURRENT_LOCATION)

throw_exception

#if defined( BOOST_NO_EXCEPTIONS )

BOOST_NORETURN void throw_exception( std::exception const & e ); // user defined

#else

template<class E> BOOST_NORETURN void throw_exception( E const & e );

#endif
Requires:

E must have std::exception as a public and unambiguous base class.

Effects:

  • When exceptions aren’t available, the function is declared, but not defined. The user is expected to supply an appropriate definition.

  • Otherwise, if BOOST_EXCEPTION_DISABLE is defined, the function throws e.

  • Otherwise, the function throws an object of a type derived from E, derived from boost::exception, if E doesn’t already derive from it, and containing the necessary support for boost::exception_ptr.

#if defined( BOOST_NO_EXCEPTIONS )

BOOST_NORETURN void throw_exception( std::exception const & e,
  boost::source_location const & loc ); // user defined

#else

template<class E> BOOST_NORETURN void throw_exception( E const & e,
  boost::source_location const & loc );

#endif
Requires:

E must have std::exception as a public and unambiguous base class.

Effects:

  • When exceptions aren’t available, the function is declared, but not defined. The user is expected to supply an appropriate definition.

  • Otherwise, if BOOST_EXCEPTION_DISABLE is defined, the function throws e.

  • Otherwise, the function throws an object of a type derived from E, derived from boost::exception, if E doesn’t already derive from it, and containing the necessary support for boost::exception_ptr. The boost::exception base class is initialized to contain the source location loc.

This documentation is