• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1////
2Copyright 2019 Peter Dimov
3Distributed under the Boost Software License, Version 1.0.
4http://www.boost.org/LICENSE_1_0.txt
5////
6
7[#description]
8# Description
9:toc:
10:toc-title:
11:idprefix:
12
13The header `<boost/throw_exception.hpp>` provides a common Boost infrastructure
14for throwing exceptions, in the form of a function `boost::throw_exception`
15and a macro `BOOST_THROW_EXCEPTION`.
16
17`boost::throw_exception(x);` is a replacement for `throw x;` that both
18degrades gracefully when exception handling support is not available, and
19integrates the thrown exception into facilities provided by
20link:../../../exception/index.html[Boost.Exception], such as automatically
21providing a base class of type `boost::exception` and support for
22`boost::exception_ptr`.
23
24When exception handling is not available, the function is only declared, but
25not defined. This allows users to provide their own definition.
26
27An overload for `boost::throw_exception` that takes a
28link:../../../assert/doc/html/assert.html#source_location_support[`boost::source_location`]
29is provided. It records the supplied source location into the `boost::exception`
30base class, from where it can later be retrieved when the exception is caught.
31link:../../../exception/doc/diagnostic_information.html[`boost::diagnostic_information`]
32automatically displays the stored source location.
33
34The macro `BOOST_THROW_EXCEPTION(x)` expands to
35`::boost::throw_exception(x, BOOST_CURRENT_LOCATION)`, passing the current source
36location.
37
38[#examples]
39# Examples
40:toc:
41:toc-title:
42:idprefix:
43
44## Using BOOST_THROW_EXCEPTION
45
46```
47#include <boost/throw_exception.hpp>
48#include <boost/exception/diagnostic_information.hpp>
49#include <stdexcept>
50#include <iostream>
51
52void f()
53{
54    BOOST_THROW_EXCEPTION( std::runtime_error( "Unspecified runtime error" ) );
55}
56
57int main()
58{
59    try
60    {
61        f();
62    }
63    catch( std::exception const & x )
64    {
65        std::cerr << boost::diagnostic_information( x ) << std::endl;
66    }
67}
68```
69
70## Using boost::throw_exception with a source location
71
72```
73#include <boost/throw_exception.hpp>
74#include <boost/lexical_cast.hpp>
75#include <boost/exception/diagnostic_information.hpp>
76#include <stdexcept>
77#include <cstddef>
78#include <iostream>
79
80void throw_index_error( std::size_t i, std::size_t n,
81  boost::source_location const & loc )
82{
83    std::string msg = "Index out of range: "
84      + boost::lexical_cast<std::string>( i ) + " >= "
85      + boost::lexical_cast<std::string>( n );
86
87    boost::throw_exception( std::out_of_range( msg ), loc );
88}
89
90void f1( std::size_t i, std::size_t n )
91{
92    if( i >= n )
93    {
94        throw_index_error( i, n, BOOST_CURRENT_LOCATION );
95    }
96}
97
98void f2( std::size_t i, std::size_t n )
99{
100    if( i >= n )
101    {
102        throw_index_error( i, n, BOOST_CURRENT_LOCATION );
103    }
104}
105
106int main()
107{
108    try
109    {
110        f1( 4, 3 );
111    }
112    catch( std::exception const & x )
113    {
114        std::cerr << boost::diagnostic_information( x ) << std::endl;
115    }
116}
117```
118