71 lines
5.7 KiB
HTML
71 lines
5.7 KiB
HTML
<!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>
|