1+++
2title = "Before we begin"
3description = "Essential information before you begin the tutorial."
4weight = 5
5tags = ["namespace", "playpen"]
6+++
7
8## Outcome v2 namespace
9
10It is recommended that you refer to entities from this Outcome v2 via the following namespace alias:
11
12{{% snippet "using_result.cpp" "namespace" %}}
13
14On standalone Outcome only, as patches and modifications are applied to this library,
15namespaces get permuted in order to not to cause binary incompatibility. At some point
16namespace `outcome_v2` will be defined, and this will be the preferred namespace.
17Until then `BOOST_OUTCOME_V2_NAMESPACE` denotes the most recently
18updated version, getting closer to `outcome_v2`.
19
20On Boost.Outcome only, as Boost provides no binary compatibility across releases,
21`BOOST_OUTCOME_V2_NAMESPACE` always expands into `boost::outcome_v2`.
22
23## Online compilers
24
25If you've never used them before, you will find
26[Godbolt](https://godbolt.org/) and [Wandbox](https://wandbox.org/) invaluable.
27These let you play with C++ inside your web browser.
28
29Most of the source code snippets in Outcome have a link in their top right to
30the original source code on github. You can copy and paste this source code into
31Godbolt (if you wish to study the assembler generated) or Wandbox (if you
32wish to run the program).
33
34### Godbolt
35
36Godbolt is invaluable for visualising online the assembler generated for a
37piece of C++, for all the major compilers and CPU architectures.
38
39Standalone Outcome is built into Godbolt! In the right hand pane toolbar, click the
40libraries dropdown (currently third from the right, looks like a book), find
41Outcome and choose the version you want.
42
43After this is selected, you can `#include` any of these editions of Outcome:
44
45<dl>
46  <dt><code>&lt;outcome-basic.hpp&gt;</code></dt>
47  <dd>An inclusion of <code>basic_outcome.hpp</code> + <code>try.hpp</code> which includes as few
48  system headers as possible in order to give an absolute minimum compile time
49  impact edition of Outcome. See <a href="https://github.com/ned14/stl-header-heft">https://github.com/ned14/stl-header-heft</a>.
50  </dd>
51  <dt><code>&lt;outcome-experimental.hpp&gt;</code></dt>
52  <dd>An inclusion of <code>experimental/status_outcome.hpp</code> + <code>try.hpp</code> which
53  is the low compile time impact of the basic edition combined with
54  <code>status_code</code> from <a href="https://ned14.github.io/status-code/">https://ned14.github.io/status-code/</a>. If you are on an
55  embedded system where binary bloat must be absolutely avoided, and don't
56  mind the potentially unstable <code>status_code</code>, this is definitely the edition
57  for you.
58  </dd>
59  <dt><code>&lt;outcome.hpp&gt;</code></dt>
60  <dd>An inclusion of <code>outcome.hpp</code> which brings in all the specialisations
61  for the <code>std</code> STL types, plus iostreams support. If you don't know which
62  edition to use, you should use this one, it ought to "just work".</dd>
63</dl>
64
65Here is the first tutorial topic's source code loaded into Godbolt: https://godbolt.org/z/p-NAho
66
67### Wandbox
68
69Wandbox lets you place a third party header into a separate tab. It also
70comes with a recent Boost libraries. Either technique can be used to
71explore Outcome.
72
73Here is the first tutorial topic's source code loaded into Wandbox: https://wandbox.org/permlink/sJoeKHXSyCU5Avft
74