67 lines
3.6 KiB
HTML
67 lines
3.6 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>Conventions - 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="../../tutorial/essential/no-value/builtin.html"><img src="../../images/prev.png" alt="Prev"></a>
|
|
<a accesskey="u" href="../../tutorial/essential.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="../../tutorial/advanced.html"><img src="../../images/next.png" alt="Next"></a></div><div id="content">
|
|
|
|
<div class="titlepage"><div><div><h1 style="clear: both">Conventions</h1></div></div></div>
|
|
|
|
|
|
<p>You now know everything you need to get started with using Outcome
|
|
immediately.</p>
|
|
|
|
<p>The initial temptation for most beginners will be to use a bespoke
|
|
strongly typed enumeration on a case by case basis i.e. a “once off”
|
|
custom <code>E</code> type. This is usually due to experience in other languages
|
|
with sum types e.g. Rust, Haskell, Swift etc.</p>
|
|
|
|
<p>However this is C++! Not Rust, not Swift, not Haskell! I must caution you to always avoid using
|
|
custom <code>E</code> types in public APIs. The reason is that every time
|
|
library A using custom <code>E1</code> type must interface with library B
|
|
using custom <code>E2</code> type, you must map between those <code>E1</code> and <code>E2</code>
|
|
types.</p>
|
|
|
|
<p>This is information lossy, i.e. fidelity of failure gets lost
|
|
after multiple translations. It involves writing, and then
|
|
<em>maintaining</em>, a lot of annoying boilerplate. It leaks internal
|
|
implementation detail, and fails to separate concerns. And one
|
|
cannot use <a href="../../reference/macros/tryv.html" class="api-reference"><code>BOOST_OUTCOME_TRYV(expr)/BOOST_OUTCOME_TRY(expr)</code></a>
|
|
|
|
if there is no convertibility between <code>E</code> types.</p>
|
|
|
|
<p>The C++ 11 standard library, and Boost,
|
|
specifically ships <code><system_error></code> for the purpose of wrapping up
|
|
individual custom <code>E</code> types into a generic framework, where disparate
|
|
custom <code>E</code> types can discover and interact with one another.
|
|
That ships with every C++ compiler.</p>
|
|
|
|
<p>For all these reasons, this is why <code>result</code> and <code>outcome</code> default
|
|
the <code>EC</code> type to error code. You should leave that default alone
|
|
where possible.</p>
|
|
|
|
<hr />
|
|
|
|
<h3 id="tl-dr">tl;dr;</h3>
|
|
|
|
<p>Please <a href="../../motivation/plug_error_code.html">plug your library into <code>std::error_code</code></a>,
|
|
or <a href="../../experimental.html">equivalent</a>, and do not expose
|
|
custom <code>E</code> types in ANY public API. <code>result</code> and <code>outcome</code> default
|
|
<code>EC</code> to an error code for good reason.</p>
|
|
|
|
|
|
|
|
</div><p><small>Last revised: February 09, 2019 at 15:18:26 UTC</small></p>
|
|
<hr>
|
|
<div class="spirit-nav">
|
|
<a accesskey="p" href="../../tutorial/essential/no-value/builtin.html"><img src="../../images/prev.png" alt="Prev"></a>
|
|
<a accesskey="u" href="../../tutorial/essential.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="../../tutorial/advanced.html"><img src="../../images/next.png" alt="Next"></a></div></body>
|
|
</html>
|