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>status_result and status_outcome - 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="../experimental/differences.html"><img src="../images/prev.png" alt="Prev"></a> 11 <a accesskey="u" href="../experimental.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="../experimental/worked-example.html"><img src="../images/next.png" alt="Next"></a></div><div id="content"> 13 <div class="titlepage"><div><div><h1 style="clear: both"><code>status_result</code> and <code>status_outcome</code></h1></div></div></div> 14 <p><code>status_result</code> and <code>status_outcome</code> are type aliases to <a href="../reference/types/basic_result.html" class="api-reference"><code>basic_result<T, E, NoValuePolicy></code></a> 15 16and <a href="../reference/types/basic_outcome.html" class="api-reference"><code>basic_outcome<T, EC, EP, NoValuePolicy></code></a> 17 in the usual way, but 18with a defaulted <code>NoValuePolicy</code> which selects on the basis of <code>status_code<DomainType></code> 19instead.</p> 20 21<div class="notices note" style="background: url('../images/note.png') top left no-repeat padding-box padding-box;"> 22<div class="notices heading">note</div> 23<div class="notices message"><p>If the <code>E</code> type is not some <code>status_code<></code>, the default policy selector 24will complain.</p> 25</div> 26</div> 27 28 29<p>The specifications are:</p> 30<div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="n">experimental</span><span class="o">::</span><span class="n">status_result</span><span class="o"><</span><span class="n">T</span><span class="p">,</span> <span class="n">E</span> <span class="o">=</span> <span class="n">experimental</span><span class="o">::</span><span class="n">system_code</span><span class="o">></span> 31<span class="n">experimental</span><span class="o">::</span><span class="n">status_outcome</span><span class="o"><</span><span class="n">T</span><span class="p">,</span> <span class="n">E</span> <span class="o">=</span> <span class="n">experimental</span><span class="o">::</span><span class="n">system_code</span><span class="p">,</span> <span class="n">EP</span> <span class="o">=</span> <span class="n">std</span><span class="o">::</span><span class="n">exception_ptr</span><span class="o">></span> 32</code></pre></div> 33<p>So, the default <code>E</code> is the erased status code <code>system_code</code>, which can represent 34any <code>generic_code</code>, <code>posix_code</code>, <code>win32_code</code>, <code>nt_code</code>, <code>com_code</code> and many 35other integer error and status 36codings. <strong>Note</strong> that <code>system_code</code> may represent successes as well as failures. 37This mirrors, somewhat, how <code>std::error_code</code> can have an all bits zero defaulted 38state.</p> 39 40<p>You can absolutely choose an <code>E</code> type which is non-erased e.g. <code>posix_code</code> directly. 41You can also choose an <code>E</code> type which is contract guaranteed to be a failure 42rather than an unknown success or failure – see <code>errored_status_code</code>.</p> 43 44<p>Whether to choose typed status codes versus the erased status codes depends on your 45use cases. Outcome replicates faithfully the implicit and explicit conversion 46semantics of its underlying types, so you can mix results and outcomes of 47<code><system_error2></code> types exactly as you can the <code><system_error2></code> types themselves 48e.g. typed forms will implicitly convert into erased forms if the source type 49is trivially copyable or move relocating. This means that you can return a 50<code>generic_code</code> from a function returning a <code>system_code</code> or <code>error</code>, and it’ll 51work exactly as you’d expect (implicit conversion).</p> 52 53<div class="notices note" style="background: url('../images/note.png') top left no-repeat padding-box padding-box;"> 54<div class="notices heading">note</div> 55<div class="notices message"><p>As <code>status_code<erased<T>></code> is move-only, so is any <code>status_result</code> or <code>status_outcome</code>. 56For some reason this surprises a lot of people, and they tend to react by not using the erased 57form because it seems “difficult”.</p> 58</div> 59</div> 60 61 62<p>It is actually, in fact, a wise discipline to follow to make all functions return 63move-only types if you care about determinism and performance. Whilst C++ 17 onwards 64does much to have the compiler avoid copying of identical function return values thanks to 65guaranteed copy elision, when a chain of functions return different types, if the 66programmer forgets to scatter <code>std::move()</code> appropriately, copies rather than moves 67tend to occur in non-obvious ways. No doubt future C++ standards will improve on the 68automatic use of moves instead of copies where possible, but until then making all 69your <code>result</code> and <code>outcome</code> types move-only is an excellent discipline.</p> 70 71<p>Note that move-only <code>result</code> and <code>outcome</code> capable code (i.e. your project is in Experimental 72Outcome configuration) usually compiles fine when <code>result</code> and <code>outcome</code> are copyable 73(i.e. your project is in Standard Outcome configuration), albeit sometimes with a few 74compiler warnings about unnecessary use of <code>std::move()</code>.</p> 75 76 77 </div><p><small>Last revised: February 05, 2019 at 17:14:18 UTC</small></p> 78<hr> 79<div class="spirit-nav"> 80<a accesskey="p" href="../experimental/differences.html"><img src="../images/prev.png" alt="Prev"></a> 81 <a accesskey="u" href="../experimental.html"><img src="../images/up.png" alt="Up"></a> 82 <a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../experimental/worked-example.html"><img src="../images/next.png" alt="Next"></a></div></body> 83</html> 84
