12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970 |
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
- <html><meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <title>std::error_code - Boost.Outcome documentation</title>
- <link rel="stylesheet" href="../css/boost.css" type="text/css">
- <meta name="generator" content="Hugo 0.52 with Boostdoc theme">
- <meta name="viewport" content="width=device-width,initial-scale=1.0"/>
- <link rel="icon" href="../images/favicon.ico" type="image/ico"/>
- <body><div class="spirit-nav">
- <a accesskey="p" href="../motivation/error_codes.html"><img src="../images/prev.png" alt="Prev"></a>
- <a accesskey="u" href="../motivation.html"><img src="../images/up.png" alt="Up"></a>
- <a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../motivation/plug_error_code.html"><img src="../images/next.png" alt="Next"></a></div><div id="content">
- <div class="titlepage"><div><div><h1 style="clear: both">std::error_code</h1></div></div></div>
- <p>Type <code>std::error_code</code> has been designed to be sufficiently small and trivial
- to be cheaply passed around, and at the same time be able to store sufficient
- information to represent any error situation from any library/sub-system in the
- world without a clash. Its representation is basically:</p>
- <div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="k">class</span><span class="err"> </span><span class="nc">error_code</span>
- <span class="p">{</span>
- <span class="n">error_category</span><span class="o">*</span> <span class="n">domain</span><span class="p">;</span> <span class="c1">// domain from which the error originates
- </span><span class="c1"></span> <span class="kt">int</span> <span class="n">value</span><span class="p">;</span> <span class="c1">// numeric value of error within the domain
- </span><span class="c1"></span><span class="p">};</span>
- </code></pre></div>
- <p>Here, <code>domain</code> indicates the library from which the error originates. It is a
- pointer to a global object representing a given library/domain. Different
- libraries will be represented by different pointers to different globals.
- Each domain is expected to be represented by a global object derived from
- <code>std::error_category</code>. The uniqueness of the domain pointer value is guaranteed
- by the uniqueness of addresses of different global objects.</p>
- <p>Now, <code>value</code> represents a numeric value of a particular error situation within
- the domain. Thus, different domains can use the same numeric value <code>1</code> to
- indicate different error situations, but two <code>std::error_code</code> objects will be
- different because the pointers representing domains will be different.</p>
- <p><code>std::error_code</code> comes with additional tools: a facility for defining custom
- domains with their set of error codes, and a facility for building predicates
- that allow classifying errors.</p>
- <p>Once created and passed around (either inside a thrown exception or returned from functions by value) there is never a need to change the value of <code>error_code</code>
- object at any level. But at different levels one can use different predicates
- for classifying error situations appropriately to the program layer.</p>
- <p>When a new library needs to represent its own set of error situations in an
- <code>error_code</code> it first has to declare the list of numeric value as an enumeration:</p>
- <div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="k">enum</span> <span class="k">class</span><span class="err"> </span><span class="nc">ConvertErrc</span>
- <span class="p">{</span>
- <span class="n">StringTooLong</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="c1">// 0 should not represent an error
- </span><span class="c1"></span> <span class="n">EmptyString</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
- <span class="n">IllegalChar</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span>
- <span class="p">};</span>
- </code></pre></div>
- <p>Then it has to put some boiler-plate code to plug the new enumeration into the
- <code>std::error_code</code> system. Then, it can use the enum as an <code>error_code</code>:</p>
- <div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="n">ec</span> <span class="o">=</span> <span class="n">ConvertErrc</span><span class="o">::</span><span class="n">EmptyString</span><span class="p">;</span>
- <span class="n">assert</span><span class="p">(</span><span class="n">ec</span> <span class="o">==</span> <span class="n">ConvertErrc</span><span class="o">::</span><span class="n">EmptyString</span><span class="p">);</span>
- </code></pre></div>
- <p>Member <code>value</code> is mapped directly from the numeric value in the enumeration, and
- member <code>domain</code> is mapped from the type of the enumeration. Thus, this is a form
- of type erasure, but one that does allow type <code>std::error_code</code> to be trivial
- and standard-layout.</p>
- </div><p><small>Last revised: January 16, 2019 at 01:05:39 +0100</small></p>
- <hr>
- <div class="spirit-nav">
- <a accesskey="p" href="../motivation/error_codes.html"><img src="../images/prev.png" alt="Prev"></a>
- <a accesskey="u" href="../motivation.html"><img src="../images/up.png" alt="Up"></a>
- <a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../motivation/plug_error_code.html"><img src="../images/next.png" alt="Next"></a></div></body>
- </html>
|