<p>The purpose of Boost Exception is to ease the design of exception class hierarchies and to help write exception handling and error reporting code.</p>
<p>It supports transporting of arbitrary data to the catch site, which is otherwise tricky due to the no-throw requirements (15.5.1) for exception classes. Data can be added to any exception object, either directly in the throw-expression (15.1), or at a later time as the exception object propagates up the call stack.</p>
<p>The ability to add data to exception objects after they have been passed to <tt>throw</tt> is important, because often some of the information needed to handle an exception is unavailable in the context where the failure is detected. </p>
<p>Boost Exception also supports <spanclass="RenoLink"><ahref="cloning.html">cloning</a></span> of exception objects, implemented non-intrusively and automatically by the <tt>boost::<spanclass="RenoLink"><ahref="throw_exception.html">throw_exception</a></span>()</tt> function.</p>
<p>Boost Exception was accepted as a Boost library on November 7 2007, however it has not yet been part of an official Boost release. Current version can be downloaded from <spanclass="RenoLink"><ahref="http://svn.boost.org/svn/boost/trunk"> Boost SVN</a></span>.</p>
<div><ol><li>Tutorial<div><ol><li><spanclass="RenoLink"><ahref="transporting_data.html">Tutorial: Transporting of Arbitrary Data to the Catch Site</a></span></li>
<li><spanclass="RenoLink"><ahref="using_enable_error_info.html">Tutorial: Integrating Boost Exception in Existing Exception Class Hierarchies</a></span></li>
<li><spanclass="RenoLink"><ahref="cloning.html">Tutorial: Transporting of Exceptions between Threads</a></span></li>
<li><spanclass="RenoLink"><ahref="logging.html">Tutorial: Logging of boost::exception Objects</a></span></li>
<spanclass="RenoLink"><ahref="exception_constructors.html">exception</a></span>( <spanclass="RenoLink"><ahref="exception.html">exception</a></span> const & x );</span>
<spanclass="RenoLink"><ahref="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">shared_ptr</a></span><typename ErrorInfo::value_type const><spanclass="RenoLink"><ahref="get_error_info.html">get_error_info</a></span>( E const & x );</span>
<spanclass="RenoLink"><ahref="exception_ptr.html">exception_ptr</a></span><spanclass="RenoLink"><ahref="copy_exception.html">copy_exception</a></span>( T const & e );</span>
<spanclass="RenoIncludeSPAN"> void <spanclass="RenoLink"><ahref="rethrow_exception.html">rethrow_exception</a></span>( <spanclass="RenoLink"><ahref="exception_ptr.html">exception_ptr</a></span> const & ep );</span>
<spanclass="RenoLink"><ahref="exception_constructors.html">exception</a></span>( <spanclass="RenoLink"><ahref="exception.html">exception</a></span> const & x );</span>
</div><p>Class <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt> is designed to be used as a universal base for user-defined exception types.</p>
<p>An object of any type deriving from <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt> can store data of arbitrary types, using the <tt><spanclass="RenoLink"><ahref="error_info.html">error_info</a></span></tt> wrapper and <tt><spanclass="RenoLink"><ahref="operator_shl_exception.html">operator<<</a></span>()</tt>.</p>
<p>To retrieve data from a <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt> object, use the <tt><spanclass="RenoLink"><ahref="get_error_info.html">get_error_info</a></span>()</tt> function template.</p>
<spanclass="RenoLink"><ahref="exception_constructors.html">exception</a></span>( <spanclass="RenoLink"><ahref="exception.html">exception</a></span> const & x );</pre>
</div><h4>Effects:</h4>
<div><ul><li> Default constructor: initializes an empty <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt> object.</li>
<li> Copy constructor: initializes a <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt> object which shares with <tt>x</tt> all data added through <tt><spanclass="RenoLink"><ahref="operator_shl_exception.html">operator<<</a></span>()</tt>, including data that is added at a future time.</li>
<p>An string representation of all data stored in the <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt> object by the <tt><spanclass="RenoLink"><ahref="operator_shl_exception.html">operator<<</a></span>()</tt> function. See "<spanclass="RenoLink"><ahref="logging.html">Tutorial: Logging of boost::exception Objects</a></span>" for details.</p>
<h4>Throws:</h4>
<p>Nothing.</p>
<h4>Note:</h4>
<p>The return value remains valid until the exception object from which it is obtained is destroyed or modified.</p>
</div></div></div><h2>Transporting of Arbitrary Data to the Catch Site</h2>
<p><tt>T</tt> must have accessible copy constructor and must not be a reference.</p>
<h4>Description:</h4>
<p>This class template is used to associate a <tt>Tag</tt> type with a value type <tt>T</tt>. Objects of type <tt><spanclass="RenoLink"><ahref="error_info.html">error_info</a></span><Tag,T></tt> can be passed to <tt><spanclass="RenoLink"><ahref="operator_shl_exception.html">operator<<</a></span>()</tt> to be stored in objects of type <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt>.</p>
<h4>Note:</h4>
<p>The header <tt><<spanclass="RenoLink"><ahref="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></span>></tt> provides a declaration of the <tt><spanclass="RenoLink"><ahref="error_info.html">error_info</a></span></tt> template, which is sufficient for the purpose of <tt>typedef</tt>ing an instance for specific <tt>Tag</tt> and <tt>T</tt>, like this:</p>
<p>Of course, to actually add an <tt>errno_info</tt> object to exceptions using <tt><spanclass="RenoLink"><ahref="operator_shl_exception.html">operator<<</a></span>()</tt>, or to retrieve it using <tt><spanclass="RenoLink"><ahref="get_error_info.html">get_error_info</a></span>()</tt>, you must first <tt>#include <<spanclass="RenoLink"><ahref="exception_error_info_hpp.html">boost/exception/info.hpp</a></span>></tt>.</p>
<spanclass="RenoLink"><ahref="error_info.html">error_info</a></span><TagN,TN>> const & v );</span>
}</pre>
</div><h4>Requirements:</h4>
<p><tt>E</tt> must be <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt>, or a type that derives (indirectly) from <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt>.</p>
<h4>Effects:</h4>
<div><ul><li> The first overload stores a copy of <tt>v</tt> into <tt>x</tt>. If <tt>x</tt> already contains data of type <tt><spanclass="RenoLink"><ahref="error_info.html">error_info</a></span><Tag1,T1></tt>, that data is overwritten.</li>
<li> The <tt>boost::<spanclass="RenoLink"><ahref="http://www.boost.org/libs/tuple/doc/tuple_users_guide.html">tuple</a></span></tt> overload is equivalent to <tt>x << v.<spanclass="RenoLink"><ahref="http://www.boost.org/libs/tuple/doc/tuple_users_guide.html#accessing_elements">get</a></span><0>() << ... << v.<spanclass="RenoLink"><ahref="http://www.boost.org/libs/tuple/doc/tuple_users_guide.html#accessing_elements">get</a></span><N>()</tt>.</li>
</ul></div>
<h4>Returns:</h4>
<p><tt>x</tt>.</p>
<divclass="RenoIncludeDIV"><h4>Throws:</h4>
<p><tt>std::bad_alloc</tt>, or any exception emitted by <tt>T1..TN</tt> copy constructor.</p>
<spanclass="RenoLink"><ahref="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">shared_ptr</a></span><typename ErrorInfo::value_type const><spanclass="RenoLink"><ahref="get_error_info.html">get_error_info</a></span>( E const & x );</span>
}</pre>
</div><h4>Requirements:</h4>
<p>The type of the <tt>x</tt> object must derive from <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt>; <tt>ErrorInfo</tt> must be an instance of the <tt><spanclass="RenoLink"><ahref="error_info.html">error_info</a></span></tt> template.</p>
<h4>Returns:</h4>
<p>If <tt>x</tt> does not store an object of type <tt>ErrorInfo</tt>, returns an empty <tt><spanclass="RenoLink"><ahref="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">shared_ptr</a></span></tt>; otherwise returns pointer to the stored value. Use <tt><spanclass="RenoLink"><ahref="operator_shl_exception.html">operator<<</a></span>()</tt> to store values in exception objects.</p>
---unspecified--- <spanclass="RenoLink"><ahref="enable_error_info.html">enable_error_info</a></span>( T const & x );</span>
}</pre>
</div><h4>Requirements:</h4>
<p><tt>T</tt> must be a user-defined type with accessible no-throw copy constructor.</p>
<h4>Returns:</h4>
<p>An object of unspecified type with no-throw copy semantics, which derives publicly from both <tt>T</tt>, and class <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt>. The <tt>T</tt> sub-object is initialized from <tt>x</tt> by the <tt>T</tt> copy constructor. If <tt>T</tt> already derives from <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt>, then the type of the returned object does not derive <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt>.</p>
</div><p>This macro is designed to be used with <tt><spanclass="RenoLink"><ahref="operator_shl_exception.html">operator<<</a></span>()</tt> when throwing a <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt>, to store information about the location of the throw statement. It can be chained with other <tt><spanclass="RenoLink"><ahref="error_info.html">error_info</a></span></tt>s in a single throw expression.</p>
</div><h2>Transporting of Exceptions between Threads</h2>
</div><p>The <tt><spanclass="RenoLink"><ahref="exception_ptr.html">exception_ptr</a></span></tt> type can be used to refer to a copy of an exception object. It is Default Constructible, Copy Constructible, Assignable and Equality Comparable; <tt><spanclass="RenoLink"><ahref="exception_ptr.html">exception_ptr</a></span></tt>'s operations do not throw.</p>
<p>Two instances of <tt><spanclass="RenoLink"><ahref="exception_ptr.html">exception_ptr</a></span></tt> are equivalent and compare equal if and only if they refer to the same exception.</p>
<p>The default constructor of <tt><spanclass="RenoLink"><ahref="exception_ptr.html">exception_ptr</a></span></tt> produces the null value of the type. The null value is equivalent only to itself.</p>
<p><tt><spanclass="RenoLink"><ahref="exception_ptr.html">exception_ptr</a></span></tt> objects are returned by <tt><spanclass="RenoLink"><ahref="current_exception.html">current_exception</a></span>()</tt> and <tt><spanclass="RenoLink"><ahref="copy_exception.html">copy_exception</a></span>()</tt>.</p>
<p><tt>T</tt> must have an accessible no-throw copy constructor</p>
<h4>Returns:</h4>
<p>An object of <i>unspecified</i> type which derives publicly from <tt>T</tt>. That is, the returned object can be intercepted by a <tt>catch(T &)</tt>.</p>
<h4>Description:</h4>
<p>This function is designed to be used directly in a throw-expression to enable the cloning support in Boost Exception. For example:</p>
<p>Unless <tt><spanclass="RenoLink"><ahref="enable_current_exception.html">enable_current_exception</a></span>()</tt> is called at the time an exception object is used in a throw-expression, any attempt to copy it using <tt><spanclass="RenoLink"><ahref="current_exception.html">current_exception</a></span>()</tt> returns an <tt><spanclass="RenoLink"><ahref="exception_ptr.html">exception_ptr</a></span></tt> which refers to an instance of <tt><spanclass="RenoLink"><ahref="unknown_exception.html">unknown_exception</a></span></tt>.</p>
<p>Instead of using the <tt>throw</tt> keyword directly, it is preferable to call <tt>boost::<spanclass="RenoLink"><ahref="throw_exception.html">throw_exception</a></span>()</tt>. This is guaranteed to throw an exception that derives from <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt> and supports cloning.</p>
<p>The <tt><spanclass="RenoLink"><ahref="current_exception.html">current_exception</a></span>()</tt> function must not be called outside of a <tt>catch</tt> block.</p>
<div><ul><li> An <tt><spanclass="RenoLink"><ahref="exception_ptr.html">exception_ptr</a></span></tt> that refers to the currently handled exception or a copy of the currently handled exception.</li>
<li> If the function needs to allocate memory and the attempt fails, it returns an <tt><spanclass="RenoLink"><ahref="exception_ptr.html">exception_ptr</a></span></tt> that refers to an instance of <tt>std::bad_alloc</tt>.</li>
<div><ul><li> It is unspecified whether the return values of two successive calls to <tt><spanclass="RenoLink"><ahref="current_exception.html">current_exception</a></span>()</tt> refer to the same exception object.</li>
<li> Correct implementation of <tt><spanclass="RenoLink"><ahref="current_exception.html">current_exception</a></span>()</tt> may require compiler support, unless <tt><spanclass="RenoLink"><ahref="enable_current_exception.html">enable_current_exception</a></span>()</tt> is used at the time the currently handled exception object was passed to <tt>throw</tt>. If <tt><spanclass="RenoLink"><ahref="enable_current_exception.html">enable_current_exception</a></span>()</tt> is not used, and if the compiler does not provide the necessary support, then <tt><spanclass="RenoLink"><ahref="current_exception.html">current_exception</a></span>()</tt> may return an <tt><spanclass="RenoLink"><ahref="exception_ptr.html">exception_ptr</a></span></tt> that refers to an instance of <tt><spanclass="RenoLink"><ahref="unknown_exception.html">unknown_exception</a></span></tt>. In this case, if the original exception object derives from <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt>, then the <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt> sub-object of the <tt><spanclass="RenoLink"><ahref="unknown_exception.html">unknown_exception</a></span></tt> object is initialized by the <tt>boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span></tt> copy constructor.</li>
<spanclass="RenoLink"><ahref="exception_ptr.html">exception_ptr</a></span><spanclass="RenoLink"><ahref="copy_exception.html">copy_exception</a></span>( T const & e );</span>
<spanclass="RenoIncludeSPAN"> void <spanclass="RenoLink"><ahref="rethrow_exception.html">rethrow_exception</a></span>( <spanclass="RenoLink"><ahref="exception_ptr.html">exception_ptr</a></span> const & ep );</span>
</div><p>This type is used by the <spanclass="RenoLink"><ahref="cloning.html">cloning</a></span> support in Boost Exception. Please see <tt><spanclass="RenoLink"><ahref="current_exception.html">current_exception</a></span>()</tt>.</p>
<div><ul><li> If <tt>BOOST_NO_EXCEPTIONS</tt> is not defined, <tt>boost::<spanclass="RenoLink"><ahref="throw_exception.html">throw_exception</a></span>(e)</tt> is equivalent to <tt>throw boost::<spanclass="RenoLink"><ahref="enable_current_exception.html">enable_current_exception</a></span>(boost::<spanclass="RenoLink"><ahref="enable_error_info.html">enable_error_info</a></span>(e))</tt>, unless <tt>BOOST_EXCEPTION_DISABLE</tt> is defined, in which case <tt>boost::<spanclass="RenoLink"><ahref="throw_exception.html">throw_exception</a></span>(e)</tt> is equivalent to <tt>throw e;</tt></li>
<li> If <tt>BOOST_NO_EXCEPTIONS</tt> is defined, the function is left undefined, and the user is expected to supply an appropriate definition. Callers of <tt>throw_exception</tt> are allowed to assume that the function never returns; therefore, if the user-defined <tt>throw_exception</tt> returns, the behavior is undefined.</li>
