mirror of
https://github.com/boostorg/outcome.git
synced 2026-01-21 17:12:15 +00:00
86 lines
8.1 KiB
HTML
86 lines
8.1 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>Worked example: Custom domain (the short way) - 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="../experimental/outcome.html"><img src="../images/prev.png" alt="Prev"></a>
|
|
<a accesskey="u" href="../experimental.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="../experimental/worked-example/implicit-construction.html"><img src="../images/next.png" alt="Next"></a></div><div id="content">
|
|
|
|
<div class="titlepage"><div><div><h1 style="clear: both">Worked example: Custom domain (the short way)</h1></div></div></div>
|
|
<p>The section after this one will take the long way through defining a custom domain
|
|
which sometimes is necessary if you have particularly bespoke requirements.
|
|
If however you just want to wrap a custom <code>enum</code> type of yours into its
|
|
own custom code domain, the boilerplate can be automated away
|
|
by filling in a few simple fields like this:</p>
|
|
|
|
<div class="code-snippet"><div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="c1">// My custom enum type
|
|
</span><span class="c1"></span><span class="k">enum</span> <span class="k">class</span><span class="err"> </span><span class="nc">custom_failure</span>
|
|
<span class="p">{</span>
|
|
<span class="n">not_found</span><span class="p">,</span>
|
|
<span class="n">bad_argument</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="c1">// Tell `status_code` to stamp out a custom code domain for this enum type
|
|
</span><span class="c1"></span><span class="n">BOOST_OUTCOME_SYSTEM_ERROR2_NAMESPACE_BEGIN</span>
|
|
<span class="k">template</span> <span class="o"><></span> <span class="k">struct</span> <span class="n">quick_status_code_from_enum</span><span class="o"><</span><span class="n">custom_failure</span><span class="o">></span> <span class="o">:</span> <span class="n">quick_status_code_from_enum_defaults</span><span class="o"><</span><span class="n">custom_failure</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Text name of the enum
|
|
</span><span class="c1"></span> <span class="k">static</span> <span class="k">constexpr</span> <span class="k">const</span> <span class="k">auto</span> <span class="n">domain_name</span> <span class="o">=</span> <span class="s">"My custom failure"</span><span class="p">;</span>
|
|
<span class="c1">// Unique UUID for the enum. PLEASE use https://www.random.org/cgi-bin/randbyte?nbytes=16&format=h
|
|
</span><span class="c1"></span> <span class="k">static</span> <span class="k">constexpr</span> <span class="k">const</span> <span class="k">auto</span> <span class="n">domain_uuid</span> <span class="o">=</span> <span class="s">"{be201f65-3962-dd0e-1266-a72e63776a42}"</span><span class="p">;</span>
|
|
<span class="c1">// Map of each enum value to its text string, and list of semantically equivalent errc's
|
|
</span><span class="c1"></span> <span class="k">static</span> <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">initializer_list</span><span class="o"><</span><span class="n">mapping</span><span class="o">></span> <span class="o">&</span><span class="n">value_mappings</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="k">static</span> <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">initializer_list</span><span class="o"><</span><span class="n">mapping</span><span class="o">></span> <span class="n">v</span> <span class="o">=</span> <span class="p">{</span>
|
|
<span class="c1">// Format is: { enum value, "string representation", { list of errc mappings ... } }
|
|
</span><span class="c1"></span> <span class="p">{</span><span class="n">custom_failure</span><span class="o">::</span><span class="n">not_found</span><span class="p">,</span> <span class="s">"item not found"</span><span class="p">,</span> <span class="p">{</span><span class="n">errc</span><span class="o">::</span><span class="n">no_such_file_or_directory</span><span class="p">}},</span> <span class="c1">//
|
|
</span><span class="c1"></span> <span class="p">{</span><span class="n">custom_failure</span><span class="o">::</span><span class="n">bad_argument</span><span class="p">,</span> <span class="s">"invoked wrong"</span><span class="p">,</span> <span class="p">{</span><span class="n">errc</span><span class="o">::</span><span class="n">invalid_argument</span><span class="p">}},</span> <span class="c1">//
|
|
</span><span class="c1"></span> <span class="p">};</span>
|
|
<span class="k">return</span> <span class="n">v</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
<span class="c1">// Completely optional definition of mixin for the status code synthesised from `Enum`. It can be omitted.
|
|
</span><span class="c1"></span> <span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="err"> </span><span class="nc">Base</span><span class="o">></span> <span class="k">struct</span> <span class="nl">mixin</span> <span class="p">:</span> <span class="n">Base</span>
|
|
<span class="p">{</span>
|
|
<span class="k">using</span> <span class="n">Base</span><span class="o">::</span><span class="n">Base</span><span class="p">;</span>
|
|
<span class="k">constexpr</span> <span class="kt">int</span> <span class="nf">custom_method</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="mi">42</span><span class="p">;</span> <span class="p">}</span>
|
|
<span class="p">};</span>
|
|
<span class="p">};</span>
|
|
<span class="n">BOOST_OUTCOME_SYSTEM_ERROR2_NAMESPACE_END</span>
|
|
</code></pre></div><a href="https://github.com/boostorg/outcome/tree/master/doc/src/snippets/quick_status_code_from_enum.cpp#L37" class="code-snippet-url" target="_blank">View this code on Github</a></div>
|
|
|
|
|
|
<p>Here we supply the bare minimum requirements for a status code domain:</p>
|
|
|
|
<ol>
|
|
<li>The name in text, so it can be printed.</li>
|
|
<li>The unique UUID to identify when multiple copies of the domain are the same.
|
|
PLEASE use <a href="https://www.random.org/cgi-bin/randbyte?nbytes=16&format=h">https://www.random.org/cgi-bin/randbyte?nbytes=16&format=h</a> to generate
|
|
this, do not twiddle a few bits.</li>
|
|
<li>For each enum value, its printable text and a sequence of <code>errc::</code> enumerations
|
|
which you think it is semantically equivalent to i.e. its mapping onto <code>generic_code</code>
|
|
which is how status code defines the common mapping between status codes. If you later compare the
|
|
status code to one of those values (or to another status code which also provides
|
|
a mapping), if the generic codes are equivalent then the comparison will return true.
|
|
This means code like <code>if(sc == errc::no_such_file_or_directory) ...</code> would match
|
|
all custom error codes which mean ‘something was not found’.</li>
|
|
<li>OPTIONAL: if you would like the custom status code type generated by this
|
|
to have additional member functions or additional payload, you can define a mixin
|
|
here to inject either data or functions or both. If you omit this, nothing gets
|
|
injected.</li>
|
|
</ol>
|
|
|
|
|
|
|
|
</div><p><small>Last revised: July 16, 2024 at 21:33:35 +0100</small></p>
|
|
<hr>
|
|
<div class="spirit-nav">
|
|
<a accesskey="p" href="../experimental/outcome.html"><img src="../images/prev.png" alt="Prev"></a>
|
|
<a accesskey="u" href="../experimental.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="../experimental/worked-example/implicit-construction.html"><img src="../images/next.png" alt="Next"></a></div></body>
|
|
</html>
|