108 lines
7.1 KiB
HTML
108 lines
7.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>Upgrade guide v2.1 => v2.2 - 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="../changelog.html"><img src="../images/prev.png" alt="Prev"></a>
|
|
<a accesskey="u" href="../changelog.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="../changelog/v22.html"><img src="../images/next.png" alt="Next"></a></div><div id="content">
|
|
<div class="titlepage"><div><div><h1 style="clear: both">Upgrade guide v2.1 => v2.2</h1></div></div></div>
|
|
<p>In the start of 2020, after a year of listening to user feedback since
|
|
entering Boost, Outcome v2.2 was published with a number of breaking source
|
|
changes from Outcome v2.1 The full year of 2020 (three Boost releases) was given to
|
|
announcing those upcoming changes, and testing the v2.2 branch in
|
|
production. In late December 2020, Outcome v2.2 became the default Outcome,
|
|
and all Outcome v2.1 code shall need to be upgraded to work with v2.2.</p>
|
|
|
|
<p>To upgrade an Outcome v2.1 based codebase to Outcome v2.2 is very easy:</p>
|
|
|
|
<ol>
|
|
<li><p>You will need a tool capable of finding regular expressions in all source
|
|
files in a directory tree and replacing them – most IDEs such as Visual Studio
|
|
have such a tool with GUI, on POSIX a shell script such as this ought to work:</p>
|
|
|
|
<pre><code>find /path/to/project -type f -name "*.hpp" | xargs sed -i "s/_TRY\(([^(]*?),(.*?)\);/_TRY((auto &&, \1),\2);/g"
|
|
find /path/to/project -type f -name "*.cpp" | xargs sed -i "s/_TRY\(([^(]*?),(.*?)\);/_TRY((auto &&, \1),\2);/g"
|
|
find /path/to/project -type f -name "*.hpp" | xargs sed -i "s/_TRY\(([^(]*?)\);/_TRYV2(auto &&, \1);/g"
|
|
find /path/to/project -type f -name "*.cpp" | xargs sed -i "s/_TRY\(([^(]*?)\);/_TRYV2(auto &&, \1);/g"
|
|
</code></pre>
|
|
|
|
<p>The transformation needed are the regular expressions <code>_TRY\(([^(]*?),(.*?)\);</code> =>
|
|
<code>_TRY((auto &&, \1),\2);</code> and <code>TRY\(([^(]*?)\);</code> => <code>_TRYV2(auto &&, \1);</code>.
|
|
This is because in Outcome v2.2 onwards, <code>BOOST_OUTCOME_TRY(var, expr)</code>
|
|
no longer implicitly declares the variable created as <code>auto&&</code> on your behalf,
|
|
now you must specify the storage of the variable. It also declares the internal
|
|
uniquely named temporary as a value rather than as a reference, the initial
|
|
brackets overrides this to force the use of a rvalue reference for the internal
|
|
uniquely named temporary instead.</p>
|
|
|
|
<p>This makes use of Outcome’s <a href="../tutorial/essential/result/try_ref.html">new TRY syntax</a>
|
|
to tell the TRY operation to use references rather than values for the internal
|
|
uniquely named temporary, thus avoiding any copies and moves. The only way to
|
|
override the storage of the internal uniquely named temporary for non-value
|
|
outputting TRY is via the new <code>BOOST_OUTCOME_TRYV2()</code> which takes the storage specifier
|
|
you desire as its first parameter.</p>
|
|
|
|
<p>The principle advantage of this change is that you can now assign to
|
|
existing variables the successful results of expressions, instead of being
|
|
forced to TRY into a new variable, and move that variable into the destination
|
|
you intended. Also, because you can now specify storage, you can now assign
|
|
the result of a TRYied operation into static or thread local storage.</p></li>
|
|
|
|
<li><p>The find regex and replace rule above is to preserve exact semantics with
|
|
Outcome v2.1 whereby the internal uniquely named temporary and the variable for
|
|
the value are both rvalue references. If you’re feeling like more work, it is
|
|
safer if you convert as many <code>BOOST_OUTCOME_TRY((auto &&, v), expr)</code> to
|
|
<code>BOOST_OUTCOME_TRY(auto &&v, expr)</code> as possible. This will mean that TRY ‘consumes’
|
|
<code>expr</code> i.e. moves it into the internal uniquely named temporary, if expr is
|
|
an rvalue reference. Usually this does not affect existing code, but occasionally
|
|
it can, generally a bit of code reordering will fix it.</p></li>
|
|
|
|
<li><p>If your code uses <a href="../tutorial/advanced/hooks.html">the ADL discovered event hooks</a>
|
|
to intercept when <code>basic_result</code> and <code>basic_outcome</code> is constructed, copies or
|
|
moved, you will need to either define the macro <a href="../reference/macros/enable_legacy_support_for.html" class="api-reference"><code>BOOST_OUTCOME_ENABLE_LEGACY_SUPPORT_FOR</code></a>
|
|
|
|
to less than <code>220</code> to enable emulation, or upgrade the code to use the new mechanism.</p>
|
|
|
|
<p>The hooks themselves have identical signature, <a href="../tutorial/advanced/hooks.html">only the name and location has
|
|
changed</a>. Therefore upgrade is usually
|
|
a case of copy-pasting the hook implementation into a custom <code>NoValuePolicy</code>
|
|
implementation, and changing the ADL free function’s name from <code>hook_*</code> to <code>on_*</code>.</p>
|
|
|
|
<p>You are recommended to upgrade if possible, as the ADL discovered hooks were
|
|
found in real world code usage to be brittle and surprising.</p></li>
|
|
|
|
<li><p>Any usage of CamelCase named concepts from Outcome must be replaced with snake_case
|
|
named concepts instead:</p>
|
|
|
|
<ul>
|
|
<li><code>concepts::ValueOrError<T></code> => <code>concepts::value_or_error<T></code></li>
|
|
<li><code>concepts::ValueOrNone<T></code> => <code>concepts::value_or_none<T></code></li>
|
|
</ul>
|
|
|
|
<p>The CamelCase naming is aliased to the snake_case naming if the macro
|
|
<a href="../reference/macros/enable_legacy_support_for.html" class="api-reference"><code>BOOST_OUTCOME_ENABLE_LEGACY_SUPPORT_FOR</code></a>
|
|
is defined to less than <code>220</code>.
|
|
Nevertheless you ought to upgrade here is possible, as due to a late change
|
|
in C++ 20 all standard concepts are now snake_case named.</p></li>
|
|
|
|
<li><p>Finally, despite that Outcome does not currently offer a stable ABI guarantee
|
|
(hoped to begin in 2022), v2.1 had a stable storage layout for <code>basic_result</code> and
|
|
<code>basic_outcome</code>. In v2.2 that storage layout has changed, so the ABIs generated by
|
|
use of v2.1 and v2.2 are incompatible i.e. you will need to recompile everything
|
|
using Outcome after you upgrade to v2.2.</p></li>
|
|
</ol>
|
|
|
|
|
|
</div><p><small>Last revised: February 23, 2021 at 17:37:27 UTC</small></p>
|
|
<hr>
|
|
<div class="spirit-nav">
|
|
<a accesskey="p" href="../changelog.html"><img src="../images/prev.png" alt="Prev"></a>
|
|
<a accesskey="u" href="../changelog.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="../changelog/v22.html"><img src="../images/next.png" alt="Next"></a></div></body>
|
|
</html>
|