Home Explore Help
Register Sign In
devn00b
/
EQ2EMu
9
3
Fork 0
Files Issues 59
Tree: ff02b05cfd
Branches Tags
EQ2EMu
/
EQ2
/
source
/
depends
/
boost_1_72_0
/
libs
/
outcome
/
doc
/
html
/
tutorial
/
essential
/
result.html

result.html 12 KB
History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119 
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
    2. 

  2. <html><meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    3. 

  3. <title>result&lt;&gt; - Boost.Outcome documentation</title>
    4. 

  4. <link rel="stylesheet" href="../../css/boost.css" type="text/css">
    5. 

  5. <meta name="generator" content="Hugo 0.52 with Boostdoc theme">
    6. 

  6. <meta name="viewport" content="width=device-width,initial-scale=1.0"/>
    7. 

  7. 

  8. <link rel="icon" href="../../images/favicon.ico" type="image/ico"/>
    9. 

  9. <body><div class="spirit-nav">
    10. 

  10. <a accesskey="p" href="../../tutorial/essential/before.html"><img src="../../images/prev.png" alt="Prev"></a>
    11. 

  11.     <a accesskey="u" href="../../tutorial/essential.html"><img src="../../images/up.png" alt="Up"></a>
    12. 

  12.     <a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../../tutorial/essential/result/inspecting.html"><img src="../../images/next.png" alt="Next"></a></div><div id="content">
    13. 

  13. 

  14.   <div class="titlepage"><div><div><h1 style="clear: both">result&lt;&gt;</h1></div></div></div>
    15. 

  15. <p>We will define a function that converts a <code>std::string</code> to an <code>int</code>. This function can fail for a number of reasons;
    16. 

  16. if it does we want to communicate the failure reason.</p>
    17. 

  17. 

  18. <div class="code-snippet"><div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="n">outcome</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;</span><span class="kt">int</span><span class="o">&gt;</span> <span class="n">convert</span><span class="p">(</span><span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">&amp;</span> <span class="n">str</span><span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
    19. 

  19. </code></pre></div><a href="https://github.com/boostorg/outcome/tree/master/doc/src/snippets/using_result.cpp#L42" class="code-snippet-url" target="_blank">View this code on Github</a></div>
    20. 

  20. 

  21. 

  22. <p>Template alias <a href="../../reference/aliases/result.html" class="api-reference"><code>result&lt;T, E = varies, NoValuePolicy = policy::default_policy&lt;T, E, void&gt;&gt;</code></a>
    23. 

  23. 

  24. has three template parameters, but the last two have default values. The first
    25. 

  25. (<code>T</code>) represents the type of the object returned from the function upon success.
    26. 

  26. The second (<code>EC</code>) is the type of object containing information about the reason
    27. 

  27. for failure when the function fails. A result object stores either a <code>T</code> or an
    28. 

  28. <code>EC</code> at any given moment, and is therefore conceptually similar to <code>variant&lt;T, EC&gt;</code>.
    29. 

  29. <code>EC</code> is defaulted to <code>std::error_code</code> in standalone Outcome, or to <code>boost::system::error_code</code>
    30. 

  30. in Boost.Outcome<sup class="footnote-ref" id="fnref:1"><a href="#fn:1">1</a></sup>. The third parameter (<code>NoValuePolicy</code>) is called a
    31. 

  31. no-value policy. We will cover it later.</p>
    32. 

  32. 

  33. <p>If both <code>T</code> and <code>EC</code> are <a href="https://en.cppreference.com/w/cpp/named_req/TriviallyCopyable">trivially copyable</a>, <code>result&lt;T, EC, NVP&gt;</code> is also trivially copyable.
    34. 

  34. Triviality, complexity and constexpr-ness of each operation (construction, copy construction, assignment,
    35. 

  35. destruction etc) is always the intersection of the corresponding operation in <code>T</code> and <code>EC</code>,
    36. 

  36. so for example if both <code>T</code> and <code>EC</code> are <a href="https://en.cppreference.com/w/cpp/named_req/LiteralType">literal types</a>, so will be <code>result&lt;T, EC, NVP&gt;</code>.
    37. 

  37. Additionally, if both <code>T</code> and <code>EC</code> have <a href="https://en.cppreference.com/w/cpp/named_req/StandardLayoutType">standard layout</a>, <code>result&lt;T, EC, NVP&gt;</code> has standard layout;
    38. 

  38. thus if both <code>T</code> and <code>EC</code> are C-compatible, so will <code>result&lt;T, EC, NVP&gt;</code> be C-compatible.</p>
    39. 

  39. 

  40. <p>Now, we will define an enumeration describing different failure situations during conversion.</p>
    41. 

  41. 

  42. <div class="code-snippet"><div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="k">enum</span> <span class="k">class</span><span class="err"> </span><span class="nc">ConversionErrc</span>
    43. 

  43. <span class="p">{</span>
    44. 

  44.   <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
    45. 

  45. </span><span class="c1"></span>  <span class="n">EmptyString</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="c1">// (for rationale, see tutorial on error codes)
    46. 

  46. </span><span class="c1"></span>  <span class="n">IllegalChar</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
    47. 

  47.   <span class="n">TooLong</span>     <span class="o">=</span> <span class="mi">3</span><span class="p">,</span>
    48. 

  48. <span class="p">};</span>
    49. 

  49. 

  50. <span class="c1">// all boilerplate necessary to plug ConversionErrc
    51. 

  51. </span><span class="c1">// into std::error_code framework
    52. 

  52. </span><span class="c1"></span></code></pre></div><a href="https://github.com/boostorg/outcome/tree/master/doc/src/snippets/using_result.cpp#L46" class="code-snippet-url" target="_blank">View this code on Github</a></div>
    53. 

  53. 

  54. 

  55. <p>Assume we have plugged it into <code>std::error_code</code> framework, as described in <a href="../../../motivation/plug_error_code">this section</a>.</p>
    56. 

  56. 

  57. <p>One notable effect of such plugging is that <code>ConversionErrc</code> is now convertible to <code>std::error_code</code>.
    58. 

  58. Now we can implement function <code>convert</code> as follows:</p>
    59. 

  59. 

  60. <div class="code-snippet"><div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="n">outcome</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;</span><span class="kt">int</span><span class="o">&gt;</span> <span class="n">convert</span><span class="p">(</span><span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">&amp;</span> <span class="n">str</span><span class="p">)</span> <span class="k">noexcept</span>
    61. 

  61. <span class="p">{</span>
    62. 

  62.   <span class="k">if</span> <span class="p">(</span><span class="n">str</span><span class="p">.</span><span class="n">empty</span><span class="p">())</span>
    63. 

  63.     <span class="k">return</span> <span class="n">ConversionErrc</span><span class="o">::</span><span class="n">EmptyString</span><span class="p">;</span>
    64. 

  64. 

  65.   <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">std</span><span class="o">::</span><span class="n">all_of</span><span class="p">(</span><span class="n">str</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">str</span><span class="p">.</span><span class="n">end</span><span class="p">(),</span> <span class="o">::</span><span class="n">isdigit</span><span class="p">))</span>
    66. 

  66.     <span class="k">return</span> <span class="n">ConversionErrc</span><span class="o">::</span><span class="n">IllegalChar</span><span class="p">;</span>
    67. 

  67. 

  68.   <span class="k">if</span> <span class="p">(</span><span class="n">str</span><span class="p">.</span><span class="n">length</span><span class="p">()</span> <span class="o">&gt;</span> <span class="mi">9</span><span class="p">)</span>
    69. 

  69.     <span class="k">return</span> <span class="n">ConversionErrc</span><span class="o">::</span><span class="n">TooLong</span><span class="p">;</span>
    70. 

  70. 

  71.   <span class="k">return</span> <span class="nf">atoi</span><span class="p">(</span><span class="n">str</span><span class="p">.</span><span class="n">c_str</span><span class="p">());</span>
    72. 

  72. <span class="p">}</span>
    73. 

  73. </code></pre></div><a href="https://github.com/boostorg/outcome/tree/master/doc/src/snippets/using_result.cpp#L65" class="code-snippet-url" target="_blank">View this code on Github</a></div>
    74. 

  74. 

  75. 

  76. <p><code>result&lt;T, EC&gt;</code> is convertible from any <code>T2</code> convertible to <code>T</code> as well as any <code>EC2</code> convertible to <code>EC</code>,
    77. 

  77. provided that there is no constructability possible in either direction between <code>T</code> and <code>EC</code>. If there is,
    78. 

  78. all implicit conversion is disabled, and you will need to use one of the tagged constructors:</p>
    79. 

  79. 

  80. <div class="code-snippet"><div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="n">outcome</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;</span><span class="kt">int</span><span class="o">&gt;</span> <span class="n">r</span> <span class="p">{</span><span class="n">outcome</span><span class="o">::</span><span class="n">in_place_type</span><span class="o">&lt;</span><span class="n">std</span><span class="o">::</span><span class="n">error_code</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">ConversionErrc</span><span class="o">::</span><span class="n">EmptyString</span><span class="p">};</span>
    81. 

  81. <span class="n">outcome</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;</span><span class="kt">int</span><span class="o">&gt;</span> <span class="n">s</span> <span class="p">{</span><span class="n">outcome</span><span class="o">::</span><span class="n">in_place_type</span><span class="o">&lt;</span><span class="kt">int</span><span class="o">&gt;</span><span class="p">,</span> <span class="mi">1</span><span class="p">};</span>
    82. 

  82. </code></pre></div><a href="https://github.com/boostorg/outcome/tree/master/doc/src/snippets/using_result.cpp#L115" class="code-snippet-url" target="_blank">View this code on Github</a></div>
    83. 

  83. 

  84. 

  85. <p>Or use helper functions:</p>
    86. 

  86. 

  87. <div class="code-snippet"><div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="n">outcome</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;</span><span class="kt">int</span><span class="o">&gt;</span> <span class="n">r</span> <span class="o">=</span> <span class="n">outcome</span><span class="o">::</span><span class="n">failure</span><span class="p">(</span><span class="n">ConversionErrc</span><span class="o">::</span><span class="n">EmptyString</span><span class="p">);</span>
    88. 

  88. <span class="n">outcome</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;</span><span class="kt">int</span><span class="o">&gt;</span> <span class="n">s</span> <span class="o">=</span> <span class="n">outcome</span><span class="o">::</span><span class="n">success</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
    89. 

  89. </code></pre></div><a href="https://github.com/boostorg/outcome/tree/master/doc/src/snippets/using_result.cpp#L123" class="code-snippet-url" target="_blank">View this code on Github</a></div>
    90. 

  90. 

  91. 

  92. <div class="notices note" style="background: url('../../images/note.png') top left no-repeat padding-box padding-box;">
    93. 

  93. <div class="notices heading">note</div>
    94. 

  94. <div class="notices message"><p>The functions <a href="../../reference/functions/failure.html" class="api-reference"><code>auto failure(T &amp;&amp;, &hellip;)</code></a>
    95. 

  95.  and <a href="../../reference/functions/success.html" class="api-reference"><code>auto success(T &amp;&amp;)</code></a>
    96. 

  96.  return special
    97. 

  97. types implicitly convertible to failed or successful <code>result</code> (and <code>outcome</code>).</p>
    98. 

  98. </div>
    99. 

  99. </div>
    100. 

  100. 

  101. <div class="footnotes">
    102. 

  102. 

  103. <hr />
    104. 

  104. 

  105. <ol>
    106. 

  106. <li id="fn:1">You can mandate a choice using <code>std_result&lt;T&gt;</code> or <code>boost_result&lt;T&gt;</code>.
    107. 

  107.  <a class="footnote-return" href="#fnref:1"><sup>[return]</sup></a></li>
    108. 

  108. </ol>
    109. 

  109. </div>
    110. 

  110. 

  111. 

  112. 

  113.         </div><p><small>Last revised: March 23, 2019 at 21:56:56 UTC</small></p>
    114. 

  114. <hr>
    115. 

  115. <div class="spirit-nav">
    116. 

  116. <a accesskey="p" href="../../tutorial/essential/before.html"><img src="../../images/prev.png" alt="Prev"></a>
    117. 

  117.     <a accesskey="u" href="../../tutorial/essential.html"><img src="../../images/up.png" alt="Up"></a>
    118. 

  118.     <a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../../tutorial/essential/result/inspecting.html"><img src="../../images/next.png" alt="Next"></a></div></body>
    119. 

  119. </html>
    120.