diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..0972e2d --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,2 @@ +/html/ +/pdf/ diff --git a/doc/BOOST_THROW_EXCEPTION.html b/doc/BOOST_THROW_EXCEPTION.html deleted file mode 100644 index 7d8806f..0000000 --- a/doc/BOOST_THROW_EXCEPTION.html +++ /dev/null @@ -1,55 +0,0 @@ - - - - - BOOST_THROW_EXCEPTION - - - -
-
-
-
- -

Boost Exception

-
- - - -

BOOST_THROW_EXCEPTION

-
-

#include <boost/throw_exception.hpp>

-
#if !defined( BOOST_EXCEPTION_DISABLE )
-    #include <boost/exception/exception.hpp>
-    #include <boost/current_function.hpp>
-    #define BOOST_THROW_EXCEPTION(x)\
-        ::boost::throw_exception( ::boost::enable_error_info(x) <<\
-        ::boost::throw_function(BOOST_THROW_EXCEPTION_CURRENT_FUNCTION) <<\
-        ::boost::throw_file(__FILE__) <<\
-        ::boost::throw_line((int)__LINE__) )
-#else
-    #define BOOST_THROW_EXCEPTION(x) ::boost::throw_exception(x)
-#endif
-

This macro takes an exception object, records the current function name, __FILE__ and __LINE__ in it, and forwards it to throw_exception. To recover this information at the catch site, use get_error_info; the information is also included in the message returned by diagnostic_information.

-
-See also: Boost Exception | boost/throw_exception.hpp | Configuration Macros | Frequently Asked Questions -
- - - - -
-
-
- - diff --git a/doc/Jamfile b/doc/Jamfile new file mode 100644 index 0000000..93ecbc9 --- /dev/null +++ b/doc/Jamfile @@ -0,0 +1,23 @@ +# Copyright 2017 Peter Dimov +# +# Distributed under the Boost Software License, Version 1.0. +# (See accompanying file LICENSE_1_0.txt or copy at +# http://www.boost.org/LICENSE_1_0.txt) + +import asciidoctor ; + +html throw_exception.html : index.adoc ; + +install html_ : throw_exception.html : html ; + +pdf throw_exception.pdf : index.adoc ; +explicit throw_exception.pdf ; + +install pdf_ : throw_exception.pdf : pdf ; +explicit pdf_ ; + +############################################################################### +alias boostdoc ; +explicit boostdoc ; +alias boostrelease : html_ ; +explicit boostrelease ; diff --git a/doc/boost_throw_exception_hpp.html b/doc/boost_throw_exception_hpp.html deleted file mode 100644 index a99cd9b..0000000 --- a/doc/boost_throw_exception_hpp.html +++ /dev/null @@ -1,65 +0,0 @@ - - - - - boost/throw_exception.hpp - - - -
-
-
-
- -

Boost Exception

-
- - - -

boost/throw_exception.hpp

-
-

Synopsis

-
#if !defined( BOOST_EXCEPTION_DISABLE )
-    #include <boost/exception/exception.hpp>
-    #include <boost/current_function.hpp>
-    #define BOOST_THROW_EXCEPTION(x)\
-        ::boost::throw_exception( ::boost::enable_error_info(x) <<\
-        ::boost::throw_function(BOOST_THROW_EXCEPTION_CURRENT_FUNCTION) <<\
-        ::boost::throw_file(__FILE__) <<\
-        ::boost::throw_line((int)__LINE__) )
-#else
-    #define BOOST_THROW_EXCEPTION(x) ::boost::throw_exception(x)
-#endif
-
-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
-    }
-
-See also: BOOST_THROW_EXCEPTION | Configuration Macros | Synopsis | throw_exception -
- - - - -
-
-
- - diff --git a/doc/changes.adoc b/doc/changes.adoc new file mode 100644 index 0000000..6802450 --- /dev/null +++ b/doc/changes.adoc @@ -0,0 +1,19 @@ +//// +Copyright 2019 Peter Dimov +Distributed under the Boost Software License, Version 1.0. +http://www.boost.org/LICENSE_1_0.txt +//// + +[#changes] +# Release History +:toc: +:toc-title: +:idprefix: + +## Changes in Boost 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. diff --git a/doc/description.adoc b/doc/description.adoc new file mode 100644 index 0000000..262e369 --- /dev/null +++ b/doc/description.adoc @@ -0,0 +1,117 @@ +//// +Copyright 2019 Peter Dimov +Distributed under the Boost Software License, Version 1.0. +http://www.boost.org/LICENSE_1_0.txt +//// + +[#description] +# Description +:toc: +:toc-title: +:idprefix: + +The header `` 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 +link:../../../exception/index.html[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 +link:../../../assert/doc/html/assert.html#source_location_support[`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. +link:../../../exception/doc/diagnostic_information.html[`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] +# Examples +:toc: +:toc-title: +:idprefix: + +## Using BOOST_THROW_EXCEPTION + +``` +#include +#include +#include +#include + +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 +#include +#include +#include +#include +#include + +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( i ) + " >= " + + boost::lexical_cast( 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; + } +} +``` diff --git a/doc/index-docinfo-footer.html b/doc/index-docinfo-footer.html new file mode 100644 index 0000000..51969f4 --- /dev/null +++ b/doc/index-docinfo-footer.html @@ -0,0 +1,6 @@ + diff --git a/doc/index.adoc b/doc/index.adoc new file mode 100644 index 0000000..a27f28a --- /dev/null +++ b/doc/index.adoc @@ -0,0 +1,27 @@ +//// +Copyright 2017, 2019 Peter Dimov +Distributed under the Boost Software License, Version 1.0. +http://www.boost.org/LICENSE_1_0.txt +//// + +# Boost.ThrowException +Peter Dimov, Emil Dotchevski +:toc: left +:idprefix: +:docinfo: private-footer + +:leveloffset: +1 + +include::description.adoc[] +include::changes.adoc[] +include::reference.adoc[] + +:leveloffset: -1 + +[appendix] +## Copyright and License + +This documentation is + +* Copyright 2019 Peter Dimov +* Distributed under the http://www.boost.org/LICENSE_1_0.txt[Boost Software License, Version 1.0]. diff --git a/doc/reference.adoc b/doc/reference.adoc new file mode 100644 index 0000000..413d60c --- /dev/null +++ b/doc/reference.adoc @@ -0,0 +1,98 @@ +//// +Copyright 2019 Peter Dimov +Distributed under the Boost Software License, Version 1.0. +http://www.boost.org/LICENSE_1_0.txt +//// + +[#reference] +# Reference +:toc: +:toc-title: +:idprefix: + +[#synopsis] +## Synopsis + +``` +#include +#include +#include + +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 BOOST_NORETURN inline void throw_exception( E const & e ); + +template 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 BOOST_NORETURN inline 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 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`. diff --git a/doc/reno.css b/doc/reno.css deleted file mode 100644 index a079b50..0000000 --- a/doc/reno.css +++ /dev/null @@ -1,226 +0,0 @@ -/* - * Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. - * - * Distributed under the Boost Software License, Version 1.0. (See accompanying - * file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - */ - -body -{ - font-family: Trebuchet, Verdana, Arial, Helvetica, Sans; - font-size: 10pt; - margin: 0; - padding: 0; - background-color: #E5E5E5; -} - -.RenoPageList, -ol, -ul -{ - clear: both; -} - -.RenoPageList -{ - margin:0; -} - -h1 -{ - font-size: 24pt; - clear: left; - padding-top: 5pt; - padding-bottom: 5pt; - margin-top: 0; - margin-bottom: 0; -} - -h2 -{ - font-size: 18pt; - clear: left; - padding-top: 20pt; - padding-bottom: 5pt; - margin-top: 0; - margin-bottom: 0; -} - -h3 -{ - font-size: 14pt; - clear: left; - padding-top: 15pt; - padding-bottom: 5pt; - margin-top: 0; - margin-bottom: 0; -} - -h4 -{ - font-size: 10pt; - float: left; - clear: left; - padding-top: 5pt; - padding-bottom: 0; - margin-top: 0; - margin-bottom: 0; - margin-right: 4pt; -} - -p -{ - font-size: 10pt; - padding-top: 5pt; - padding-bottom: 5pt; - margin-top: 0; - margin-bottom: 0; - clear:right; -} - -pre -{ - border-top: 1px solid #C5C5C5; - border-bottom: 1px solid #C5C5C5; - border-left: 1px solid #C5C5C5; - border-right: 1px solid #C5C5C5; - font-size: 10pt; - padding-top: 5pt; - padding-bottom: 5pt; - padding-left: 5pt; - padding-right: 5pt; - margin-left: 18pt; - margin-right: 18pt; - margin-top: 10pt; - margin-bottom: 10pt; - clear: both; -} - -ol,ul -{ - padding-top: 0; - padding-bottom: 0; - margin-top: 0; - margin-bottom: 0; -} - -ul li -{ - padding-top: 5pt; - padding-bottom: 5pt; - margin-top: 0; - margin-bottom: 0; -} - -.RenoIndex h3 -{ - margin: 20pt 0 5pt 0; - padding: 2pt; - display: inline; - border: 1.5pt solid #A0A0A0; - float: left; - clear: both; - width: 15pt; - text-align: center; - background-color: #EAEAEA; -} - -.RenoIndex p -{ - clear: both; - margin: 0; - padding: 0; -} - -.RenoHookUnbound, -.RenoHookBound -{ - background-position: left center; - background-image: url('link.gif'); - background-repeat: no-repeat; - padding-left: 10pt; -} - -.RenoIncludeDIV -{ - padding: 0; - margin: 0; -} - -.RenoError -{ - background-color: red; - color: white; - display: inline; -} - -a -{ - text-decoration: underline; - color: #0000AA; -} - -tt -{ - font-size: 10pt; -} - -hr -{ - border: 0; - color: black; - background-color: black; - height: 1px; - margin-top: 20pt; -} - -blockquote -{ - padding-top: 0; - padding-bottom: 0; - padding-right: 0; - padding-left: 20pt; - margin: 0; -} - -#boost_logo -{ - float:right; -} - -#footer -{ - margin-top:20pt; -} - -.logo_pic -{ - border:0; -} - -.logo -{ - float:right; - margin-left: 6pt; - margin-right: -4pt; -} - -.body-0 -{ - min-width: 40em; - padding-left: 30px; - background: url(shade-l.png) repeat-y left; -} -.body-1 -{ - padding-right: 30px; - background: url(shade-r.png) repeat-y right; -} -.body-2 -{ - background-color: white; - padding: 0 8pt 0 8pt; - margin-left: 0; - border-top: solid 2.5pt #717171; - border-bottom: solid 3pt #717171; -} diff --git a/doc/throw_exception.html b/doc/throw_exception.html deleted file mode 100644 index eb03fdb..0000000 --- a/doc/throw_exception.html +++ /dev/null @@ -1,64 +0,0 @@ - - - - - throw_exception - - - -
-
-
-
- -

Boost Exception

-
- - - -

throw_exception

-
-

#include <boost/throw_exception.hpp>

-
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:

-
  • If BOOST_NO_EXCEPTIONS is not defined, boost::throw_exception(e) throws an exception of unspecified type that derives publicly from E and from boost::exception.
    • -
  • If BOOST_NO_EXCEPTIONS is defined, the function is left undefined, and the user is expected to supply an appropriate definition. Callers of throw_exception are allowed to assume that the function never returns; therefore, if the user-defined throw_exception returns, the behavior is undefined.
    • -
-

Requirements:

-

E must derive publicly from std::exception. E may or may not derive from boost::exception.

-

Notes:

-
  • The emitted exception can be intercepted as E &, std::exception &, or boost::exception &.
    • -
  • The emitted exception supports boost::exception_ptr.
    • -
  • If BOOST_EXCEPTION_DISABLE is defined and BOOST_NO_EXCEPTIONS is not defined, boost::throw_exception(e) equivalent to throw e.
    • -
-
-See also: BOOST_THROW_EXCEPTION | Boost Exception | boost/throw_exception.hpp | Configuration Macros | enable_current_exception | Frequently Asked Questions | Transporting of Exceptions Between Threads -
- - - - -
-
-
- - diff --git a/doc/valid-css.png b/doc/valid-css.png deleted file mode 100644 index 931bacf..0000000 Binary files a/doc/valid-css.png and /dev/null differ diff --git a/doc/valid-xhtml.png b/doc/valid-xhtml.png deleted file mode 100644 index 7b12715..0000000 Binary files a/doc/valid-xhtml.png and /dev/null differ diff --git a/index.html b/index.html index 100b9a0..8387dfb 100644 --- a/index.html +++ b/index.html @@ -1,13 +1,13 @@ - + Automatic redirection Automatic redirection failed, please go to -boost_throw_exception_hpp.html. 
-

© Copyright Beman Dawes, 2001

+throw_exception.html. 
+

Copyright Beman Dawes, 2001

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)