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
/
advanced
/
interop
/
app-go.html

app-go.html 8.4 KB
History Raw

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586 
  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>In use - 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/advanced/interop/app-map-tidylib.html"><img src="../../../images/prev.png" alt="Prev"></a>
    11. 

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

  13.   <div class="titlepage"><div><div><h1 style="clear: both">In use</h1></div></div></div>
    14. 

  14.   <p>This is how you might now write application code using these three libraries:</p>
    15. 

  15. 

  16. <div class="code-snippet"><div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="k">namespace</span> <span class="n">app</span>
    17. 

  17. <span class="p">{</span>
    18. 

  18.   <span class="c1">// A markup function to indicate when we are ValueOrError converting
    19. 

  19. </span><span class="c1"></span>  <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="o">&gt;</span> <span class="kr">inline</span> <span class="n">outcome</span><span class="o">&lt;</span><span class="k">typename</span> <span class="n">T</span><span class="o">::</span><span class="n">value_type</span><span class="o">&gt;</span> <span class="n">ext</span><span class="p">(</span><span class="n">T</span> <span class="o">&amp;&amp;</span><span class="n">v</span><span class="p">)</span>
    20. 

  20.   <span class="p">{</span>  <span class="c1">//
    21. 

  21. </span><span class="c1"></span>    <span class="k">return</span> <span class="n">outcome</span><span class="o">&lt;</span><span class="k">typename</span> <span class="n">T</span><span class="o">::</span><span class="n">value_type</span><span class="o">&gt;</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="n">v</span><span class="p">));</span>
    22. 

  22.   <span class="p">}</span>
    23. 

  23. 

  24.   <span class="n">outcome</span><span class="o">&lt;</span><span class="kt">void</span><span class="o">&gt;</span> <span class="n">go</span><span class="p">()</span>  <span class="c1">// NOT noexcept, this can throw STL exceptions e.g. bad_alloc
    25. 

  25. </span><span class="c1"></span>  <span class="p">{</span>
    26. 

  26.     <span class="c1">// Note that explicit construction is required when converting between differing types
    27. 

  27. </span><span class="c1"></span>    <span class="c1">// of outcome and result. This makes it explicit what you intend to do as conversion
    28. 

  28. </span><span class="c1"></span>    <span class="c1">// may be a lot more expensive than moves.
    29. 

  29. </span><span class="c1"></span>
    30. 

  30.     <span class="c1">// Try to GET this URL. If an unsuccessful HTTP status is returned, serialise a string
    31. 

  31. </span><span class="c1"></span>    <span class="c1">// containing a description of the HTTP status code and the URL which failed, storing
    32. 

  32. </span><span class="c1"></span>    <span class="c1">// that into a httplib_error exception type which is stored as an exception ptr. The
    33. 

  33. </span><span class="c1"></span>    <span class="c1">// TRY operation below will return that exception ptr to be rethrown in the caller.
    34. 

  34. </span><span class="c1"></span>    <span class="c1">// Otherwise the fetched data is returned in a std::string data.
    35. 

  35. </span><span class="c1"></span>    <span class="n">BOOST_OUTCOME_TRY</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">ext</span><span class="p">(</span><span class="n">httplib</span><span class="o">::</span><span class="n">get</span><span class="p">(</span><span class="s">&#34;http://www.nedproductions.biz/&#34;</span><span class="p">)));</span>
    36. 

  36.     <span class="n">string_view</span> <span class="nf">data_view</span><span class="p">(</span><span class="n">data</span><span class="p">);</span>
    37. 

  37. 

  38.     <span class="c1">// HTML tidy the fetched data. If the C library fails due to an error corresponding to
    39. 

  39. </span><span class="c1"></span>    <span class="c1">// a standard library exception type, throw that. Otherwise, synthesise an exception
    40. 

  40. </span><span class="c1"></span>    <span class="c1">// ptr of type tidylib_error which stores the error code returned in an error code with
    41. 

  41. </span><span class="c1"></span>    <span class="c1">// generic category (i.e. errno domain).
    42. 

  42. </span><span class="c1"></span>    <span class="c1">// TRY operation below will return that exception ptr to be rethrown in the caller.
    43. 

  43. </span><span class="c1"></span>    <span class="c1">// Otherwise the tidied data is returned into holdmem, with the string view updated to
    44. 

  44. </span><span class="c1"></span>    <span class="c1">// point at the tidied data.
    45. 

  45. </span><span class="c1"></span>    <span class="n">BOOST_OUTCOME_TRY</span><span class="p">(</span><span class="n">holdmem</span><span class="p">,</span> <span class="n">ext</span><span class="p">(</span><span class="n">tidy_html</span><span class="p">(</span><span class="n">data_view</span><span class="p">)));</span>
    46. 

  46. 

  47.     <span class="c1">// Write the tidied data to some file. If the write fails, synthesise a filesystem_error
    48. 

  48. </span><span class="c1"></span>    <span class="c1">// exception ptr exactly as if one called filelib::write_file(data_view).value().
    49. 

  49. </span><span class="c1"></span>    <span class="n">BOOST_OUTCOME_TRY</span><span class="p">(</span><span class="n">written</span><span class="p">,</span> <span class="n">ext</span><span class="p">(</span><span class="n">filelib</span><span class="o">::</span><span class="n">write_file</span><span class="p">(</span><span class="n">data_view</span><span class="p">)));</span>
    50. 

  50.     <span class="k">return</span> <span class="nf">success</span><span class="p">();</span>
    51. 

  51.   <span class="p">}</span>
    52. 

  52. <span class="p">}</span>  <span class="c1">// namespace app
    53. 

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

  54. 

  55. 

  56. <p>The curiosity will be surely the <code>ext()</code> markup function, which needs
    57. 

  57. explaining. It was felt
    58. 

  58. important during Outcome&rsquo;s design that <code>ValueOrError</code> conversions never
    59. 

  59. be implicit, as they almost always represent a transition across an
    60. 

  60. ABI or semantic boundary. They are also usually non-trivial to implement
    61. 

  61. and compile, and it was felt important that the programmer ought to
    62. 

  62. always mark the semantic boundary transition at the point of every use,
    63. 

  63. as considerable amounts of code may execute.</p>
    64. 

  64. 

  65. <p>How the end user chooses to mark up their code is up to them, however
    66. 

  66. above we use a simple <code>ext()</code> function to mark up that the function
    67. 

  67. being called is <em>external</em> to the application. This ticks our box of
    68. 

  68. requiring the documentation, at the point of use, of every transition
    69. 

  69. in failure handling boundaries.</p>
    70. 

  70. 

  71. <p>Note that we are able to use <code>TRY</code> as normal throughout this function.
    72. 

  72. Everything &ldquo;just works&rdquo;.</p>
    73. 

  73. 

  74. <p>And most especially note that we never, <strong>at any stage</strong>, needed to modify
    75. 

  75. the source code of <code>httplib</code>, <code>tidylib</code> nor <code>filelib</code>, nor inject
    76. 

  76. custom things into their namespaces. This entire worked example was
    77. 

  77. achieved solely by <code>app</code> based customisation points, and via <code>convert</code>.</p>
    78. 

  78. 

  79. 

  80.         </div><p><small>Last revised: February 11, 2019 at 13:38:04 UTC</small></p>
    81. 

  81. <hr>
    82. 

  82. <div class="spirit-nav">
    83. 

  83. <a accesskey="p" href="../../../tutorial/advanced/interop/app-map-tidylib.html"><img src="../../../images/prev.png" alt="Prev"></a>
    84. 

  84.     <a accesskey="u" href="../../../tutorial/advanced/interop.html"><img src="../../../images/up.png" alt="Up"></a>
    85. 

  85.     <a accesskey="h" href="../../../index.html"><img src="../../../images/home.png" alt="Home"></a><a accesskey="n" href="../../../tutorial/advanced/interop/conclusion.html"><img src="../../../images/next.png" alt="Next"></a></div></body>
    86. 

  86. </html>
    87.