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>Conventions - 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="../../tutorial/essential/coroutines/co_await.html"><img src="../../images/prev.png" alt="Prev"></a> 11 <a accesskey="u" href="../../tutorial/essential.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="../../tutorial/advanced.html"><img src="../../images/next.png" alt="Next"></a></div><div id="content"> 13 14 <div class="titlepage"><div><div><h1 style="clear: both">Conventions</h1></div></div></div> 15 16 17<p>You now know everything you need to get started with using Outcome 18immediately.</p> 19 20<p>The initial temptation for most beginners will be to use a bespoke 21strongly typed enumeration on a case by case basis i.e. a “once off” 22custom <code>E</code> type. This is usually due to experience in other languages 23with sum types e.g. Rust, Haskell, Swift etc.</p> 24 25<p>However this is C++! Not Rust, not Swift, not Haskell! I must caution you to always avoid using 26custom <code>E</code> types in public APIs. The reason is that every time 27library A using custom <code>E1</code> type must interface with library B 28using custom <code>E2</code> type, you must map between those <code>E1</code> and <code>E2</code> 29types.</p> 30 31<p>This is information lossy, i.e. fidelity of failure gets lost 32after multiple translations. It involves writing, and then 33<em>maintaining</em>, a lot of annoying boilerplate. It leaks internal 34implementation detail, and fails to separate concerns. And one 35cannot use <a href="../../reference/macros/tryv.html" class="api-reference"><code>BOOST_OUTCOME_TRYV(expr)/BOOST_OUTCOME_TRY(expr)</code></a> 36 37if there is no convertibility between <code>E</code> types.</p> 38 39<p>The C++ 11 standard library, and Boost, 40specifically ships <code><system_error></code> for the purpose of wrapping up 41individual custom <code>E</code> types into a generic framework, where disparate 42custom <code>E</code> types can discover and interact with one another. 43That ships with every C++ compiler.</p> 44 45<p>For all these reasons, this is why <code>result</code> and <code>outcome</code> default 46the <code>EC</code> type to error code. You should leave that default alone 47where possible.</p> 48 49<hr /> 50 51<h3 id="tl-dr">tl;dr;</h3> 52 53<p>Please <a href="../../motivation/plug_error_code.html">plug your library into <code>std::error_code</code></a>, 54or <a href="../../experimental.html">equivalent</a>, and do not expose 55custom <code>E</code> types in ANY public API. <code>result</code> and <code>outcome</code> default 56<code>EC</code> to an error code for good reason.</p> 57 58 59 60 </div><p><small>Last revised: February 09, 2019 at 15:18:26 UTC</small></p> 61<hr> 62<div class="spirit-nav"> 63<a accesskey="p" href="../../tutorial/essential/coroutines/co_await.html"><img src="../../images/prev.png" alt="Prev"></a> 64 <a accesskey="u" href="../../tutorial/essential.html"><img src="../../images/up.png" alt="Up"></a> 65 <a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../../tutorial/advanced.html"><img src="../../images/next.png" alt="Next"></a></div></body> 66</html> 67
