1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html><meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 3<title>Plugging a library into std::error_code - Boost.Outcome documentation</title> 4<link rel="stylesheet" href="../css/boost.css" type="text/css"> 5<meta name="generator" content="Hugo 0.52 with Boostdoc theme"> 6<meta name="viewport" content="width=device-width,initial-scale=1.0"/> 7 8<link rel="icon" href="../images/favicon.ico" type="image/ico"/> 9<body><div class="spirit-nav"> 10<a accesskey="p" href="../motivation/std_error_code.html"><img src="../images/prev.png" alt="Prev"></a> 11 <a accesskey="u" href="../motivation.html"><img src="../images/up.png" alt="Up"></a> 12 <a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../motivation/plug_error_code2.html"><img src="../images/next.png" alt="Next"></a></div><div id="content"> 13 <div class="titlepage"><div><div><h1 style="clear: both">Plugging a library into std::error_code`</h1></div></div></div> 14 <p><a href="../motivation/plug_error_code2.html">See here for this guide, but for <code>boost::system::error_code</code></a>.</p> 15 16<p>This section illustrates how you can hook into the <code>std::error_code</code> system from 17the Standard Library in order to work with your own set of error codes. As is usually 18the case in C++, doing this is straightforward but requires typing boilerplate 19to tell the C++ STL about your custom error type. This is not part of Outcome library, 20but we still provide this short guide here, because how to do this is not well documented [1].</p> 21 22<p>Suppose you want to report all reasons for failure in converting a <code>std::string</code> to a non-negative <code>int</code>. 23The list is:</p> 24 25<ul> 26<li><code>EmptyString</code> – the input string is empty,</li> 27<li><code>IllegalChar</code> – input contains characters that are not digits,</li> 28<li><code>TooLong</code> – input represents a number, but this number would not fit into a variable of type <code>int</code>.</li> 29</ul> 30 31<div class="code-snippet"><div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="cp">#include</span> <span class="cpf"><iostream></span><span class="cp"> 32</span><span class="cp">#include</span> <span class="cpf"><string> // for string printing</span><span class="cp"> 33</span><span class="cp">#include</span> <span class="cpf"><system_error> // bring in std::error_code et al</span><span class="cp"> 34</span><span class="cp"></span> 35<span class="c1">// This is the custom error code enum 36</span><span class="c1"></span><span class="k">enum</span> <span class="k">class</span><span class="err"> </span><span class="nc">ConversionErrc</span> 37<span class="p">{</span> 38 <span class="n">Success</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="c1">// 0 should not represent an error 39</span><span class="c1"></span> <span class="n">EmptyString</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> 40 <span class="n">IllegalChar</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span> 41 <span class="n">TooLong</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span> 42<span class="p">};</span> 43 44<span class="k">namespace</span> <span class="n">std</span> 45<span class="p">{</span> 46 <span class="c1">// Tell the C++ 11 STL metaprogramming that enum ConversionErrc 47</span><span class="c1"></span> <span class="c1">// is registered with the standard error code system 48</span><span class="c1"></span> <span class="k">template</span> <span class="o"><></span> <span class="k">struct</span> <span class="n">is_error_code_enum</span><span class="o"><</span><span class="n">ConversionErrc</span><span class="o">></span> <span class="o">:</span> <span class="n">true_type</span> 49 <span class="p">{</span> 50 <span class="p">};</span> 51<span class="p">}</span> 52 53<span class="k">namespace</span> <span class="n">detail</span> 54<span class="p">{</span> 55 <span class="c1">// Define a custom error code category derived from std::error_category 56</span><span class="c1"></span> <span class="k">class</span><span class="err"> </span><span class="nc">ConversionErrc_category</span> <span class="o">:</span> <span class="k">public</span> <span class="n">std</span><span class="o">::</span><span class="n">error_category</span> 57 <span class="p">{</span> 58 <span class="k">public</span><span class="o">:</span> 59 <span class="c1">// Return a short descriptive name for the category 60</span><span class="c1"></span> <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">name</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span> <span class="k">override</span> <span class="k">final</span> <span class="p">{</span> <span class="k">return</span> <span class="s">"ConversionError"</span><span class="p">;</span> <span class="p">}</span> 61 <span class="c1">// Return what each enum means in text 62</span><span class="c1"></span> <span class="k">virtual</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">message</span><span class="p">(</span><span class="kt">int</span> <span class="n">c</span><span class="p">)</span> <span class="k">const</span> <span class="k">override</span> <span class="k">final</span> 63 <span class="p">{</span> 64 <span class="k">switch</span> <span class="p">(</span><span class="k">static_cast</span><span class="o"><</span><span class="n">ConversionErrc</span><span class="o">></span><span class="p">(</span><span class="n">c</span><span class="p">))</span> 65 <span class="p">{</span> 66 <span class="k">case</span> <span class="n">ConversionErrc</span><span class="o">::</span><span class="nl">Success</span><span class="p">:</span> 67 <span class="k">return</span> <span class="s">"conversion successful"</span><span class="p">;</span> 68 <span class="k">case</span> <span class="n">ConversionErrc</span><span class="o">::</span><span class="nl">EmptyString</span><span class="p">:</span> 69 <span class="k">return</span> <span class="s">"converting empty string"</span><span class="p">;</span> 70 <span class="k">case</span> <span class="n">ConversionErrc</span><span class="o">::</span><span class="nl">IllegalChar</span><span class="p">:</span> 71 <span class="k">return</span> <span class="s">"got non-digit char when converting to a number"</span><span class="p">;</span> 72 <span class="k">case</span> <span class="n">ConversionErrc</span><span class="o">::</span><span class="nl">TooLong</span><span class="p">:</span> 73 <span class="k">return</span> <span class="s">"the number would not fit into memory"</span><span class="p">;</span> 74 <span class="k">default</span><span class="o">:</span> 75 <span class="k">return</span> <span class="s">"unknown"</span><span class="p">;</span> 76 <span class="p">}</span> 77 <span class="p">}</span> 78 <span class="c1">// OPTIONAL: Allow generic error conditions to be compared to me 79</span><span class="c1"></span> <span class="k">virtual</span> <span class="n">std</span><span class="o">::</span><span class="n">error_condition</span> <span class="n">default_error_condition</span><span class="p">(</span><span class="kt">int</span> <span class="n">c</span><span class="p">)</span> <span class="k">const</span> <span class="k">noexcept</span> <span class="k">override</span> <span class="k">final</span> 80 <span class="p">{</span> 81 <span class="k">switch</span> <span class="p">(</span><span class="k">static_cast</span><span class="o"><</span><span class="n">ConversionErrc</span><span class="o">></span><span class="p">(</span><span class="n">c</span><span class="p">))</span> 82 <span class="p">{</span> 83 <span class="k">case</span> <span class="n">ConversionErrc</span><span class="o">::</span><span class="nl">EmptyString</span><span class="p">:</span> 84 <span class="k">return</span> <span class="n">make_error_condition</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">errc</span><span class="o">::</span><span class="n">invalid_argument</span><span class="p">);</span> 85 <span class="k">case</span> <span class="n">ConversionErrc</span><span class="o">::</span><span class="nl">IllegalChar</span><span class="p">:</span> 86 <span class="k">return</span> <span class="n">make_error_condition</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">errc</span><span class="o">::</span><span class="n">invalid_argument</span><span class="p">);</span> 87 <span class="k">case</span> <span class="n">ConversionErrc</span><span class="o">::</span><span class="nl">TooLong</span><span class="p">:</span> 88 <span class="k">return</span> <span class="n">make_error_condition</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">errc</span><span class="o">::</span><span class="n">result_out_of_range</span><span class="p">);</span> 89 <span class="k">default</span><span class="o">:</span> 90 <span class="c1">// I have no mapping for this code 91</span><span class="c1"></span> <span class="k">return</span> <span class="n">std</span><span class="o">::</span><span class="n">error_condition</span><span class="p">(</span><span class="n">c</span><span class="p">,</span> <span class="o">*</span><span class="k">this</span><span class="p">);</span> 92 <span class="p">}</span> 93 <span class="p">}</span> 94 <span class="p">};</span> 95<span class="p">}</span> 96 97<span class="c1">// Define the linkage for this function to be used by external code. 98</span><span class="c1">// This would be the usual __declspec(dllexport) or __declspec(dllimport) 99</span><span class="c1">// if we were in a Windows DLL etc. But for this example use a global 100</span><span class="c1">// instance but with inline linkage so multiple definitions do not collide. 101</span><span class="c1"></span><span class="cp">#define THIS_MODULE_API_DECL extern inline 102</span><span class="cp"></span> 103<span class="c1">// Declare a global function returning a static instance of the custom category 104</span><span class="c1"></span><span class="n">THIS_MODULE_API_DECL</span> <span class="k">const</span> <span class="n">detail</span><span class="o">::</span><span class="n">ConversionErrc_category</span> <span class="o">&</span><span class="n">ConversionErrc_category</span><span class="p">()</span> 105<span class="p">{</span> 106 <span class="k">static</span> <span class="n">detail</span><span class="o">::</span><span class="n">ConversionErrc_category</span> <span class="n">c</span><span class="p">;</span> 107 <span class="k">return</span> <span class="n">c</span><span class="p">;</span> 108<span class="p">}</span> 109 110 111<span class="c1">// Overload the global make_error_code() free function with our 112</span><span class="c1">// custom enum. It will be found via ADL by the compiler if needed. 113</span><span class="c1"></span><span class="kr">inline</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="n">make_error_code</span><span class="p">(</span><span class="n">ConversionErrc</span> <span class="n">e</span><span class="p">)</span> 114<span class="p">{</span> 115 <span class="k">return</span> <span class="p">{</span><span class="k">static_cast</span><span class="o"><</span><span class="kt">int</span><span class="o">></span><span class="p">(</span><span class="n">e</span><span class="p">),</span> <span class="n">ConversionErrc_category</span><span class="p">()};</span> 116<span class="p">}</span> 117 118<span class="kt">int</span> <span class="n">main</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> 119<span class="p">{</span> 120 <span class="c1">// Note that we can now supply ConversionErrc directly to error_code 121</span><span class="c1"></span> <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">ConversionErrc</span><span class="o">::</span><span class="n">IllegalChar</span><span class="p">;</span> 122 123 <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"ConversionErrc::IllegalChar is printed by std::error_code as "</span> 124 <span class="o"><<</span> <span class="n">ec</span> <span class="o"><<</span> <span class="s">" with explanatory message "</span> <span class="o"><<</span> <span class="n">ec</span><span class="p">.</span><span class="n">message</span><span class="p">()</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span> 125 126 <span class="c1">// We can compare ConversionErrc containing error codes to generic conditions 127</span><span class="c1"></span> <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"ec is equivalent to std::errc::invalid_argument = "</span> 128 <span class="o"><<</span> <span class="p">(</span><span class="n">ec</span> <span class="o">==</span> <span class="n">std</span><span class="o">::</span><span class="n">errc</span><span class="o">::</span><span class="n">invalid_argument</span><span class="p">)</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span> 129 <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"ec is equivalent to std::errc::result_out_of_range = "</span> 130 <span class="o"><<</span> <span class="p">(</span><span class="n">ec</span> <span class="o">==</span> <span class="n">std</span><span class="o">::</span><span class="n">errc</span><span class="o">::</span><span class="n">result_out_of_range</span><span class="p">)</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span> 131 <span class="k">return</span> <span class="mi">0</span><span class="p">;</span> 132<span class="p">}</span> 133</code></pre></div><a href="https://github.com/boostorg/outcome/tree/master/doc/src/snippets/error_code_registration.cpp#L32" class="code-snippet-url" target="_blank">View this code on Github</a></div> 134 135 136<p>This might look like a lot of extra boilerplate over simply using your custom 137error code enum directly, but look at the advantages:</p> 138 139<ol> 140<li>Any code which can speak <code>std::error_code</code> can now work with errors from your 141code, AND without being recompiled.</li> 142<li><code>std::system_error</code> can now wrap your custom error codes seamlessly, allowing 143your custom error code to be converted into a C++ exception <em>and back out again</em> 144without losing information.</li> 145<li><code>std::error_code</code> knows how to print itself, and will print your custom error 146code without extra work from you. As usually you’d need to define a print routine 147for any custom error code you’d write anyway, there is actually very little extra 148boilerplate here.</li> 149<li>If you implement the <code>default_error_condition()</code> override, you can allow code 150exclusively written to understand <code>std::errc</code> alone to examine your custom error 151code domain for equivalence to the standard error conditions, AND without being 152recompiled.</li> 153</ol> 154 155<div class="notices note" style="background: url('../images/note.png') top left no-repeat padding-box padding-box;"> 156<div class="notices heading">note</div> 157<div class="notices message"><p>This documentation recommends that when you define your custom <code>enum</code> for representing 158<code>error_code</code>s, you should always make sure that value 0 never represents an actual error: 159it should either represent a success or should not be provided at all. If you only 160intend to use your <code>enum</code> inside <code>result<></code> or <code>outcome<></code> you can just start your 161enumerations from 1. If you intend to also return <code>std::error_code</code> directly from 162functions, you should probably define value 0 as success, so that you are able to 163inform about function’s success by returning <code>MyEnum::Success</code>. This is because <code>error_code</code>’s 164contextual conversion to <code>bool</code> (which some people use to check if there was an error or not) 165only checks for the numeric value of the error code (without looking at error domain (category)).</p> 166</div> 167</div> 168 169 170<p>[1]: The only documentation I’m aware of is the quite old guide by Chris Kohlhoff, founder of ASIO and the Networking TS:</p> 171 172<ul> 173<li><a href="http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-1.html">http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-1.html</a></li> 174<li><a href="http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-2.html">http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-2.html</a></li> 175<li><a href="http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-3.html">http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-3.html</a></li> 176<li><a href="http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-4.html">http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-4.html</a></li> 177<li><a href="http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-5.html">http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-5.html</a></li> 178</ul> 179 180 181 </div><p><small>Last revised: June 21, 2019 at 22:46:55 +0100</small></p> 182<hr> 183<div class="spirit-nav"> 184<a accesskey="p" href="../motivation/std_error_code.html"><img src="../images/prev.png" alt="Prev"></a> 185 <a accesskey="u" href="../motivation.html"><img src="../images/up.png" alt="Up"></a> 186 <a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../motivation/plug_error_code2.html"><img src="../images/next.png" alt="Next"></a></div></body> 187</html> 188
