Home Explore Help
Register Sign In
devn00b
/
EQ2EMu
9
3
Fork 0
Files Issues 59 Pull Requests 0 Wiki
Tree: ff02b05cfd
Branches Tags
EQ2EMu
/
EQ2
/
source
/
depends
/
boost_1_72_0
/
libs
/
outcome
/
doc
/
html
/
recipes
/
foreign-try.html

foreign-try.html 15 KB
History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178 
  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>Extending BOOST_OUTCOME_TRY - 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="../recipes/asio-integration-1-70.html"><img src="../images/prev.png" alt="Prev"></a>
    11. 

  11.     <a accesskey="u" href="../recipes.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="../experimental.html"><img src="../images/next.png" alt="Next"></a></div><div id="content">
    13. 

  13.   <div class="titlepage"><div><div><h1 style="clear: both">Extending <code>BOOST_OUTCOME_TRY</code></h1></div></div></div>
    14. 

  14.   
    15. 

  15. 

  16. <p>Outcome&rsquo;s <a href="../reference/macros/try.html" class="api-reference"><code>BOOST_OUTCOME_TRY(var, expr)</code></a>
    17. 

  17.  operation is fully extensible
    18. 

  18. to accept as input any foreign types.
    19. 

  19. It already recognises types matching the
    20. 

  20. <a href="../reference/concepts/valueorerror.html" class="api-reference"><code>ValueOrError&lt;T, E&gt;</code></a>
    21. 

  21.  concept, which is to say all types which have:</p>
    22. 

  22. 

  23. <ul>
    24. 

  24. <li>A public <code>.has_value()</code> member function which returns a <code>bool</code>.</li>
    25. 

  25. <li>In order of preference, a public <code>.assume_value()</code>/<code>.value()</code> member
    26. 

  26. function.</li>
    27. 

  27. <li>In order of preference, a public <code>.as_failure()</code>/<code>.assume_error()</code>/<code>.error()</code>
    28. 

  28. member function.</li>
    29. 

  29. </ul>
    30. 

  30. 

  31. <p>This should automatically handle inputs of <code>std::expected&lt;T, E&gt;</code>, and many others,
    32. 

  32. including intermixing Boost.Outcome and standalone Outcome within the same
    33. 

  33. translation unit.</p>
    34. 

  34. 

  35. <p><code>BOOST_OUTCOME_TRY</code> has the following free function customisation points:</p>
    36. 

  36. 

  37. <dl>
    38. 

  38. <dt><code>BOOST_OUTCOME_V2_NAMESPACE::</code><a href="../reference/functions/try_operation_has_value.html" class="api-reference"><code>try_operation_has_value(X)</code></a>
    39. 

  39. 

  40. <dd>Returns a `bool` which is true if the input to TRY has a value.
    41. 

  41. <dt><code>BOOST_OUTCOME_V2_NAMESPACE::</code><a href="../reference/functions/try_operation_return_as.html" class="api-reference"><code>try_operation_return_as(X)</code></a>
    42. 

  42. 

  43. <dd>Returns a suitable <a href="../reference/types/failure_type.html" class="api-reference"><code>failure_type&lt;EC, EP = void&gt;</code></a>
    44. 

  44.  which
    45. 

  45. is returned immediately to cause stack unwind. Ought to preserve rvalue
    46. 

  46. semantics (i.e. if passed an rvalue, move the error state into the failure
    47. 

  47. type).
    48. 

  48. <dt><code>BOOST_OUTCOME_V2_NAMESPACE::</code><a href="../reference/functions/try_operation_extract_value.html" class="api-reference"><code>try_operation_extract_value(X)</code></a>
    49. 

  49. 

  50. <dd>Extracts a value type from the input for the `TRY` to set its variable.
    51. 

  51. Ought to preserve rvalue semantics (i.e. if passed an rvalue, move the value).
    52. 

  52. </dl>
    53. 

  53. 

  54. <p>New overloads of these to support additional input types must be injected into
    55. 

  55. the <code>BOOST_OUTCOME_V2_NAMESPACE</code> namespace before the compiler parses the relevant
    56. 

  56. <code>BOOST_OUTCOME_TRY</code> in order to be found. This is called &lsquo;early binding&rsquo; in the two
    57. 

  57. phase name lookup model in C++. This was chosen over &lsquo;late binding&rsquo;, where an
    58. 

  58. <code>BOOST_OUTCOME_TRY</code> in a templated piece of code could look up overloads introduced after
    59. 

  59. parsing the template containing the <code>BOOST_OUTCOME_TRY</code>, because it has much lower
    60. 

  60. impact on build times, as binding is done once at the point of parse, instead
    61. 

  61. of on every occasion at the point of instantiation. If you are careful to ensure
    62. 

  62. that you inject the overloads which you need early in the parse of the
    63. 

  63. translation unit, all will be well.</p>
    64. 

  64. 

  65. <p>Let us work through an applied example.</p>
    66. 

  66. 

  67. <hr />
    68. 

  68. 

  69. <h2 id="a-very-foreign-pseudo-expected-type">A very foreign pseudo-Expected type</h2>
    70. 

  70. 

  71. <p>This is a paraphrase of a poorly written pseudo-Expected type which I once
    72. 

  72. encountered in the production codebase of a large multinational. Lots
    73. 

  73. of the code was already using it, and it was weird enough that it couldn&rsquo;t
    74. 

  74. be swapped out for something better easily.</p>
    75. 

  75. 

  76. <div class="code-snippet"><div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="k">enum</span> <span class="n">Errc</span>
    77. 

  77. <span class="p">{</span>
    78. 

  78.   <span class="n">kBadValue</span>
    79. 

  79. <span class="p">};</span>
    80. 

  80. <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err"> </span><span class="nc">T</span><span class="p">,</span> <span class="k">class</span><span class="err"> </span><span class="nc">E</span> <span class="o">=</span> <span class="n">Errc</span><span class="o">&gt;</span> <span class="k">struct</span> <span class="n">ForeignExpected</span>
    81. 

  81. <span class="p">{</span>
    82. 

  82.   <span class="n">T</span> <span class="n">Value</span><span class="p">;</span>
    83. 

  83.   <span class="n">E</span> <span class="n">Error</span><span class="p">;</span>
    84. 

  84.   <span class="kt">int</span> <span class="n">IsErrored</span><span class="p">;</span>
    85. 

  85. 

  86.   <span class="n">ForeignExpected</span><span class="p">(</span><span class="n">T</span> <span class="n">v</span><span class="p">)</span>
    87. 

  87.       <span class="o">:</span> <span class="n">Value</span><span class="p">(</span><span class="n">v</span><span class="p">)</span>
    88. 

  88.       <span class="p">,</span> <span class="n">Error</span><span class="p">()</span>
    89. 

  89.       <span class="p">,</span> <span class="n">IsErrored</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
    90. 

  90.   <span class="p">{</span>
    91. 

  91.   <span class="p">}</span>
    92. 

  92.   <span class="n">ForeignExpected</span><span class="p">(</span><span class="n">E</span> <span class="n">e</span><span class="p">)</span>
    93. 

  93.       <span class="o">:</span> <span class="n">Value</span><span class="p">()</span>
    94. 

  94.       <span class="p">,</span> <span class="n">Error</span><span class="p">(</span><span class="n">e</span><span class="p">)</span>
    95. 

  95.       <span class="p">,</span> <span class="n">IsErrored</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
    96. 

  96.   <span class="p">{</span>
    97. 

  97.   <span class="p">}</span>
    98. 

  98. <span class="p">};</span>
    99. 

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

  100. 

  101. 

  102. <p>What we would like is for new code to be written using Outcome, but be able
    103. 

  103. to transparently call old code, like this:</p>
    104. 

  104. 

  105. <div class="code-snippet"><div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="n">ForeignExpected</span><span class="o">&lt;</span><span class="kt">int</span><span class="o">&gt;</span> <span class="n">old_code</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>  <span class="c1">// old code
    106. 

  106. </span><span class="c1"></span><span class="p">{</span>
    107. 

  107.   <span class="k">if</span><span class="p">(</span><span class="mi">0</span> <span class="o">==</span> <span class="n">a</span><span class="p">)</span>
    108. 

  108.     <span class="k">return</span> <span class="n">kBadValue</span><span class="p">;</span>
    109. 

  109.   <span class="k">return</span> <span class="n">a</span><span class="p">;</span>
    110. 

  110. <span class="p">}</span>
    111. 

  111. 

  112. <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">new_code</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>  <span class="c1">// new code
    113. 

  113. </span><span class="c1"></span><span class="p">{</span>
    114. 

  114.   <span class="n">BOOST_OUTCOME_TRY</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">old_code</span><span class="p">(</span><span class="n">a</span><span class="p">));</span>
    115. 

  115.   <span class="k">return</span> <span class="n">x</span><span class="p">;</span>
    116. 

  116. <span class="p">}</span>
    117. 

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

  118. 

  119. 

  120. <p>Telling Outcome about this weird foreign Expected is straightforward:</p>
    121. 

  121. 

  122. <div class="code-snippet"><div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="n">BOOST_OUTCOME_V2_NAMESPACE_BEGIN</span>
    123. 

  123. <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err"> </span><span class="nc">T</span><span class="p">,</span> <span class="k">class</span><span class="err"> </span><span class="nc">E</span><span class="o">&gt;</span>  <span class="c1">//
    124. 

  124. </span><span class="c1"></span><span class="kr">inline</span> <span class="kt">bool</span> <span class="n">try_operation_has_value</span><span class="p">(</span><span class="k">const</span> <span class="n">ForeignExpected</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">E</span><span class="o">&gt;</span> <span class="o">&amp;</span><span class="n">v</span><span class="p">)</span>
    125. 

  125. <span class="p">{</span>
    126. 

  126.   <span class="k">return</span> <span class="mi">0</span> <span class="o">==</span> <span class="n">v</span><span class="p">.</span><span class="n">IsErrored</span><span class="p">;</span>
    127. 

  127. <span class="p">}</span>
    128. 

  128. <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err"> </span><span class="nc">T</span><span class="p">,</span> <span class="k">class</span><span class="err"> </span><span class="nc">E</span><span class="o">&gt;</span>  <span class="c1">//
    129. 

  129. </span><span class="c1"></span><span class="kr">inline</span> <span class="k">auto</span> <span class="n">try_operation_return_as</span><span class="p">(</span><span class="k">const</span> <span class="n">ForeignExpected</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">E</span><span class="o">&gt;</span> <span class="o">&amp;</span><span class="n">v</span><span class="p">)</span>
    130. 

  130. <span class="p">{</span>
    131. 

  131.   <span class="k">switch</span><span class="p">(</span><span class="n">v</span><span class="p">.</span><span class="n">Error</span><span class="p">)</span>
    132. 

  132.   <span class="p">{</span>
    133. 

  133.   <span class="k">case</span> <span class="nl">kBadValue</span><span class="p">:</span>
    134. 

  134.     <span class="k">return</span> <span class="n">failure</span><span class="p">(</span><span class="n">make_error_code</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">errc</span><span class="o">::</span><span class="n">argument_out_of_domain</span><span class="p">));</span>
    135. 

  135.   <span class="p">}</span>
    136. 

  136.   <span class="n">abort</span><span class="p">();</span>
    137. 

  137. <span class="p">}</span>
    138. 

  138. <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err"> </span><span class="nc">T</span><span class="p">,</span> <span class="k">class</span><span class="err"> </span><span class="nc">E</span><span class="o">&gt;</span>  <span class="c1">//
    139. 

  139. </span><span class="c1"></span><span class="kr">inline</span> <span class="k">auto</span> <span class="n">try_operation_extract_value</span><span class="p">(</span><span class="k">const</span> <span class="n">ForeignExpected</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">E</span><span class="o">&gt;</span> <span class="o">&amp;</span><span class="n">v</span><span class="p">)</span>
    140. 

  140. <span class="p">{</span>
    141. 

  141.   <span class="k">return</span> <span class="n">v</span><span class="p">.</span><span class="n">Value</span><span class="p">;</span>
    142. 

  142. <span class="p">}</span>
    143. 

  143. <span class="n">BOOST_OUTCOME_V2_NAMESPACE_END</span>
    144. 

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

  145. 

  146. 

  147. <p>And now <code>BOOST_OUTCOME_TRY</code> works exactly as expected:</p>
    148. 

  148. 

  149. <div class="code-snippet"><div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++">  <span class="k">auto</span> <span class="n">printresult</span> <span class="o">=</span> <span class="p">[](</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">desc</span><span class="p">,</span> <span class="k">auto</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span>
    150. 

  150.     <span class="k">if</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
    151. 

  151.     <span class="p">{</span>
    152. 

  152.       <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o">&lt;&lt;</span> <span class="n">desc</span> <span class="o">&lt;&lt;</span> <span class="s">&#34; returns successful &#34;</span> <span class="o">&lt;&lt;</span> <span class="n">x</span><span class="p">.</span><span class="n">value</span><span class="p">()</span> <span class="o">&lt;&lt;</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
    153. 

  153.     <span class="p">}</span>
    154. 

  154.     <span class="k">else</span>
    155. 

  155.     <span class="p">{</span>
    156. 

  156.       <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o">&lt;&lt;</span> <span class="n">desc</span> <span class="o">&lt;&lt;</span> <span class="s">&#34; returns failure &#34;</span> <span class="o">&lt;&lt;</span> <span class="n">x</span><span class="p">.</span><span class="n">error</span><span class="p">().</span><span class="n">message</span><span class="p">()</span> <span class="o">&lt;&lt;</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
    157. 

  157.     <span class="p">}</span>
    158. 

  158.   <span class="p">};</span>
    159. 

  159.   <span class="n">printresult</span><span class="p">(</span><span class="s">&#34;</span><span class="se">\n</span><span class="s">new_code(5)&#34;</span><span class="p">,</span> <span class="n">new_code</span><span class="p">(</span><span class="mi">5</span><span class="p">));</span>
    160. 

  160.   <span class="n">printresult</span><span class="p">(</span><span class="s">&#34;</span><span class="se">\n</span><span class="s">new_code(0)&#34;</span><span class="p">,</span> <span class="n">new_code</span><span class="p">(</span><span class="mi">0</span><span class="p">));</span>
    161. 

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

  162. 

  163. 

  164. <p>&hellip; which outputs:</p>
    165. 

  165. 

  166. <pre><code>new_code(5) returns successful 5
    167. 

  167. 

  168. new_code(0) returns failure argument out of domain
    169. 

  169. </code></pre>
    170. 

  170. 

  171. 

  172.         </div><p><small>Last revised: June 22, 2019 at 21:22:42 &#43;0100</small></p>
    173. 

  173. <hr>
    174. 

  174. <div class="spirit-nav">
    175. 

  175. <a accesskey="p" href="../recipes/asio-integration-1-70.html"><img src="../images/prev.png" alt="Prev"></a>
    176. 

  176.     <a accesskey="u" href="../recipes.html"><img src="../images/up.png" alt="Up"></a>
    177. 

  177.     <a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../experimental.html"><img src="../images/next.png" alt="Next"></a></div></body>
    178. 

  178. </html>
    179.