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_exceptionthat takes aboost::source_locationobject.
| Note | Projects using BOOST_THROW_EXCEPTIONwith 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:
- 
Emust havestd::exceptionas 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_DISABLEis defined, the function throwse.
- 
Otherwise, the function throws an object of a type derived from E, derived fromboost::exception, ifEdoesn’t already derive from it, and containing the necessary support forboost::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:
- 
Emust havestd::exceptionas 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_DISABLEis defined, the function throwse.
- 
Otherwise, the function throws an object of a type derived from E, derived fromboost::exception, ifEdoesn’t already derive from it, and containing the necessary support forboost::exception_ptr. Theboost::exceptionbase class is initialized to contain the source locationloc.
 
- 
Appendix A: Copyright and License
This documentation is
- 
Copyright 2019 Peter Dimov 
- 
Distributed under the Boost Software License, Version 1.0.