1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html><meta http-equiv="Content-Type" content="text/html; charset=utf-8">
3 <title>API reference - Boost.Outcome documentation</title>
4 <link rel="stylesheet" href="./css/boost.css" type="text/css">
5 <meta name="generator" content="Hugo 0.52 with Boostdoc theme">
6 <meta name="viewport" content="width=device-width,initial-scale=1.0"/>
8 <link rel="icon" href="./images/favicon.ico" type="image/ico"/>
9 <body><div class="spirit-nav">
10 <a accesskey="p" href="./experimental/c-api/reference.html"><img src="./images/prev.png" alt="Prev"></a>
11 <a accesskey="u" href="./index.html"><img src="./images/up.png" alt="Up"></a>
12 <a accesskey="h" href="./index.html"><img src="./images/home.png" alt="Home"></a><a accesskey="n" href="./reference/macros.html"><img src="./images/next.png" alt="Next"></a></div><div id="content">
14 <div class="titlepage"><div><div><h1 style="clear: both">API reference</h1></div></div></div>
15 <ol class="children children-li"><li>
16 <a href="./reference/macros.html" >Macros</a><ol><li>
17 <a href="./reference/macros/template.html" >Constrained template macros</a><li>
18 <a href="./reference/macros/version.html" >Version macros</a><li>
19 <a href="./reference/macros/co_try.html" ><code>BOOST_OUTCOME_CO_TRY(var, expr)</code></a>
20 <p>Evaluate within a coroutine an expression which results in an understood type, assigning <code>T</code> to a variable called <code>var</code> if successful, immediately returning <code>try_operation_return_as(X)</code> from the calling function if unsuccessful.</p><li>
21 <a href="./reference/macros/co_tryv.html" ><code>BOOST_OUTCOME_CO_TRYV(expr)/BOOST_OUTCOME_CO_TRY(expr)</code></a>
22 <p>Evaluate from within a coroutine an expression which results in an understood type, continuing execution if successful, immediately returning <code>try_operation_return_as(X)</code> from the calling function if unsuccessful.</p><li>
23 <a href="./reference/macros/co_tryv_failure_likely.html" ><code>BOOST_OUTCOME_CO_TRYV_FAILURE_LIKELY(expr)/BOOST_OUTCOME_CO_TRY_FAILURE_LIKELY(expr)</code></a>
24 <p>Evaluate from within a coroutine an expression which results in an understood type, continuing execution if successful, immediately returning <code>try_operation_return_as(X)</code> from the calling function if unsuccessful.</p><li>
25 <a href="./reference/macros/co_tryx.html" ><code>BOOST_OUTCOME_CO_TRYX(expr)</code></a>
26 <p>Evaluate from within a coroutine an expression which results in an understood type, emitting the <code>T</code> if successful, immediately returning <code>try_operation_return_as(X)</code> from the calling function if unsuccessful.</p><li>
27 <a href="./reference/macros/co_tryx_failure_likely.html" ><code>BOOST_OUTCOME_CO_TRYX_FAILURE_LIKELY(expr)</code></a>
28 <p>Evaluate from within a coroutine an expression which results in an understood type, emitting the <code>T</code> if successful, immediately returning <code>try_operation_return_as(X)</code> from the calling function if unsuccessful.</p><li>
29 <a href="./reference/macros/co_try_failure_likely.html" ><code>BOOST_OUTCOME_CO_TRY_FAILURE_LIKELY(var, expr)</code></a>
30 <p>Evaluate within a coroutine an expression which results in an understood type, assigning <code>T</code> to a variable called <code>var</code> if successful, immediately returning <code>try_operation_return_as(X)</code> from the calling function if unsuccessful.</p><li>
31 <a href="./reference/macros/disable_execinfo.html" ><code>BOOST_OUTCOME_DISABLE_EXECINFO</code></a>
32 <p>If defined, disables the use of the <code><execinfo.h></code> header (or the win32 emulation).</p><li>
33 <a href="./reference/macros/nodiscard.html" ><code>BOOST_OUTCOME_NODISCARD</code></a>
34 <p>How to tell the compiler than the return value of a function should not be discarded without examining it.</p><li>
35 <a href="./reference/macros/requires.html" ><code>BOOST_OUTCOME_REQUIRES(...)</code></a>
36 <p>A C++ 20 <code>requires(...)</code>, if available.</p><li>
37 <a href="./reference/macros/symbol_visible.html" ><code>BOOST_OUTCOME_SYMBOL_VISIBLE</code></a>
38 <p>How to mark throwable types as always having default ELF symbol visibility.</p><li>
39 <a href="./reference/macros/thread_local.html" ><code>BOOST_OUTCOME_THREAD_LOCAL</code></a>
40 <p>How to mark variables as having thread local storage duration.</p><li>
41 <a href="./reference/macros/throw_exception.html" ><code>BOOST_OUTCOME_THROW_EXCEPTION(expr)</code></a>
42 <p>How to throw a C++ exception, or equivalent thereof.</p><li>
43 <a href="./reference/macros/try.html" ><code>BOOST_OUTCOME_TRY(var, expr)</code></a>
44 <p>Evaluate an expression which results in an understood type, assigning <code>T</code> to a variable called <code>var</code> if successful, immediately returning <code>try_operation_return_as(X)</code> from the calling function if unsuccessful.</p><li>
45 <a href="./reference/macros/tryv.html" ><code>BOOST_OUTCOME_TRYV(expr)/BOOST_OUTCOME_TRY(expr)</code></a>
46 <p>Evaluate an expression which results in an understood type, continuing execution if successful, immediately returning <code>try_operation_return_as(X)</code> from the calling function if unsuccessful.</p><li>
47 <a href="./reference/macros/tryv_failure_likely.html" ><code>BOOST_OUTCOME_TRYV_FAILURE_LIKELY(expr)/BOOST_OUTCOME_TRY_FAILURE_LIKELY(expr)</code></a>
48 <p>Evaluate an expression which results in an understood type, continuing execution if successful, immediately returning <code>try_operation_return_as(X)</code> from the calling function if unsuccessful.</p><li>
49 <a href="./reference/macros/tryx.html" ><code>BOOST_OUTCOME_TRYX(expr)</code></a>
50 <p>Evaluate an expression which results in an understood type, emitting the <code>T</code> if successful, immediately returning <code>try_operation_return_as(X)</code> from the calling function if unsuccessful.</p><li>
51 <a href="./reference/macros/tryx_failure_likely.html" ><code>BOOST_OUTCOME_TRYX_FAILURE_LIKELY(expr)</code></a>
52 <p>Evaluate an expression which results in an understood type, emitting the <code>T</code> if successful, immediately returning <code>try_operation_return_as(X)</code> from the calling function if unsuccessful.</p><li>
53 <a href="./reference/macros/try_failure_likely.html" ><code>BOOST_OUTCOME_TRY_FAILURE_LIKELY(var, expr)</code></a>
54 <p>Evaluate an expression which results in an understood type, assigning <code>T</code> to a variable called <code>var</code> if successful, immediately returning <code>try_operation_return_as(X)</code> from the calling function if unsuccessful.</p><li>
55 <a href="./reference/macros/in_place_type.html" ><code>BOOST_OUTCOME_USE_STD_IN_PLACE_TYPE</code></a>
56 <p>How to implement <code>in_place_type_t<T></code> and <code>in_place_type<T></code>.</p><li>
57 <a href="./reference/macros/is_nothrow_swappable.html" ><code>BOOST_OUTCOME_USE_STD_IS_NOTHROW_SWAPPABLE</code></a>
58 <p>How to implement <code>is_nothrow_swappable<T></code>.</p></li></ol><li>
59 <a href="./reference/concepts.html" >Concepts</a><ol><li>
60 <a href="./reference/concepts/valueorerror.html" ><code>ValueOrError<T, E></code></a>
61 <p>A boolean concept matching types with either a value or an error.</p><li>
62 <a href="./reference/concepts/valueornone.html" ><code>ValueOrNone<T></code></a>
63 <p>A boolean concept matching types with an optional value.</p></li></ol><li>
64 <a href="./reference/converters.html" >Converters</a><ol><li>
65 <a href="./reference/converters/value_or_error.html" ><code>value_or_error<T, U></code></a>
66 <p>A customisable converter of <code>ValueOrError<T, E></code> concept matching types.</p></li></ol><li>
67 <a href="./reference/traits.html" >Traits</a><ol><li>
68 <a href="./reference/traits/is_basic_outcome.html" ><code>is_basic_outcome<T></code></a>
69 <p>An integral constant type true for <code>basic_outcome<T, EC, EP, NoValuePolicy></code> types.</p><li>
70 <a href="./reference/traits/is_basic_result.html" ><code>is_basic_result<T></code></a>
71 <p>An integral constant type true for <code>basic_result<T, E, NoValuePolicy></code> types.</p><li>
72 <a href="./reference/traits/is_error_code_available.html" ><code>is_error_code_available<T></code></a>
73 <p>True if an error code can be constructed from a <code>T</code>.</p><li>
74 <a href="./reference/traits/is_error_type.html" ><code>is_error_type<E></code></a>
75 <p>A customisable integral constant type true for <code>E</code> types which are to receive error throwing no-value policies.</p><li>
76 <a href="./reference/traits/is_error_type_enum.html" ><code>is_error_type_enum<E, Enum></code></a>
77 <p>A customisable integral constant type true for <code>E</code> types constructible from <code>Enum</code> types which are to receive error throwing no-value policies.</p><li>
78 <a href="./reference/traits/is_exception_ptr_available.html" ><code>is_exception_ptr_available<T></code></a>
79 <p>True if an exception ptr can be constructed from a <code>T</code>.</p><li>
80 <a href="./reference/traits/is_failure_type.html" ><code>is_failure_type<T></code></a>
81 <p>An integral constant boolean variable true for <code>failure_type<EC, E = void></code> types.</p><li>
82 <a href="./reference/traits/is_success_type.html" ><code>is_success_type<T></code></a>
83 <p>An integral constant boolean variable true for <code>success_type<T></code> types.</p><li>
84 <a href="./reference/traits/type_can_be_used_in_basic_result.html" ><code>type_can_be_used_in_basic_result<R></code></a>
85 <p>A constexpr boolean true for types permissible in <code>basic_result<T, E, NoValuePolicy></code>.</p></li></ol><li>
86 <a href="./reference/policies.html" >Policies</a><ol><li>
87 <a href="./reference/policies/base.html" ><code>base</code></a>
88 <p>Base class of most policy classes defining the narrow observer policies.</p><li>
89 <a href="./reference/policies/all_narrow.html" ><code>all_narrow</code></a>
90 <p>Policy class defining that hard undefined behaviour should occur on incorrect narrow and wide value, error or exception observation. Inherits publicly from <code>base</code>.</p><li>
91 <a href="./reference/policies/error_code_throw_as_system_error_outcome.html" ><code>error_code_throw_as_system_error<T, EC, EP></code></a>
92 <p>Policy class defining that <code>EP</code> ought to be rethrown if possible, then the ADL discovered free function <code>outcome_throw_as_system_error_with_payload()</code> should be called on incorrect wide value observation. Inherits publicly from <code>base</code>. Can only be used with <code>basic_outcome</code>.</p><li>
93 <a href="./reference/policies/error_code_throw_as_system_error_result.html" ><code>error_code_throw_as_system_error<T, EC, void></code></a>
94 <p>Policy class defining that the ADL discovered free function <code>outcome_throw_as_system_error_with_payload()</code> should be called on incorrect wide value observation. Inherits publicly from <code>base</code>. Can only be used with <code>basic_result</code>.</p><li>
95 <a href="./reference/policies/exception_ptr_rethrow_outcome.html" ><code>exception_ptr_rethrow<T, EC, EP></code></a>
96 <p>Policy class defining that the ADL discovered free function <code>rethrow_exception()</code> should be called on incorrect wide value observation. Inherits publicly from <code>base</code>. Can only be used with <code>basic_outcome</code>.</p><li>
97 <a href="./reference/policies/exception_ptr_rethrow_result.html" ><code>exception_ptr_rethrow<T, EC, void></code></a>
98 <p>Policy class defining that the ADL discovered free function <code>rethrow_exception()</code> should be called on incorrect wide value observation. Inherits publicly from <code>base</code>. Can only be used with <code>basic_result</code>.</p><li>
99 <a href="./reference/policies/fail_to_compile_observers.html" ><code>fail_to_compile_observers</code></a>
100 <p>Policy class defining that a static assertion should occur upon compilation of the wide value, error or exception observation. Inherits publicly from <code>base</code>.</p><li>
101 <a href="./reference/policies/terminate.html" ><code>terminate</code></a>
102 <p>Policy class defining that <code>std::terminate()</code> should be called on incorrect wide value, error or exception observation. Inherits publicly from <code>base</code>.</p><li>
103 <a href="./reference/policies/throw_bad_result_access.html" ><code>throw_bad_result_access<EC></code></a>
104 <p>Policy class defining that <code>bad_result_access_with<EC></code> should be thrown on incorrect wide value observation. Inherits publicly from <code>base</code>.</p></li></ol><li>
105 <a href="./reference/types.html" >Types</a><ol><li>
106 <a href="./reference/types/basic_outcome.html" ><code>basic_outcome<T, EC, EP, NoValuePolicy></code></a>
107 <p>A type carrying one of (i) a successful <code>T</code> (ii) a disappointment <code>EC</code> (iii) a failure <code>EP</code> (iv) both a disappointment <code>EC</code> and a failure <code>EP</code>, with <code>NoValuePolicy</code> specifying what to do if one tries to read state which isn’t there.</p><li>
108 <a href="./reference/types/basic_result.html" ><code>basic_result<T, E, NoValuePolicy></code></a>
109 <p>A sum type carrying either a successful <code>T</code>, or a disappointment <code>E</code>, with <code>NoValuePolicy</code> specifying what to do if one tries to read state which isn’t there.</p><li>
110 <a href="./reference/types/bad_outcome_access.html" ><code>bad_outcome_access</code></a>
111 <p>Exception type publicly inheriting from <code>std::logic_error</code> indicating an incorrect observation of value or error or exception occurred.</p><li>
112 <a href="./reference/types/bad_result_access_with.html" ><code>bad_result_access_with<EC></code></a>
113 <p>Exception type publicly inheriting from <code>bad_result_access</code> indicating an incorrect observation of value occurred, supplying the error value.</p><li>
114 <a href="./reference/types/bad_result_access.html" ><code>bad_result_access</code></a>
115 <p>Exception type publicly inheriting from <code>std::logic_error</code> indicating an incorrect observation of value or error occurred.</p><li>
116 <a href="./reference/types/failure_type.html" ><code>failure_type<EC, EP = void></code></a>
117 <p>Type sugar for constructing an unsuccessful result or outcome.</p><li>
118 <a href="./reference/types/in_place_type_t.html" ><code>in_place_type_t<T></code></a>
119 <p>Either <code>std::in_place_type_t<T></code> or a local emulation, depending on the <code>BOOST_OUTCOME_USE_STD_IN_PLACE_TYPE</code> macro.</p><li>
120 <a href="./reference/types/success_type.html" ><code>success_type<T></code></a>
121 <p>Type sugar for constructing a successful result or outcome.</p></li></ol><li>
122 <a href="./reference/aliases.html" >Aliases</a><ol><li>
123 <a href="./reference/aliases/boost_checked.html" ><code>boost_checked<T, E = boost::system::error_code></code></a>
124 <p>A type alias to a <code>basic_result</code> configured with <code>boost::system::error_code</code> and <code>policy::throw_bad_result_access<EC></code>.</p><li>
125 <a href="./reference/aliases/boost_outcome.html" ><code>boost_outcome<T, EC = boost::system::error_code, EP = boost::exception_ptr, NoValuePolicy = policy::default_policy<T, EC, EP>></code></a>
126 <p>A type alias to a <code>basic_outcome</code> configured with <code>boost::system::error_code</code>, <code>boost::exception_ptr</code> and <code>policy::default_policy</code>.</p><li>
127 <a href="./reference/aliases/boost_result.html" ><code>boost_result<T, E = boost::system::error_code, NoValuePolicy = policy::default_policy<T, E, void>></code></a>
128 <p>A type alias to a <code>basic_result</code> configured with <code>boost::system::error_code</code> and <code>policy::default_policy</code>.</p><li>
129 <a href="./reference/aliases/boost_unchecked.html" ><code>boost_unchecked<T, E = boost::system::error_code></code></a>
130 <p>A type alias to a <code>basic_result</code> configured with <code>boost::system::error_code</code> and <code>policy::all_narrow</code>.</p><li>
131 <a href="./reference/aliases/checked.html" ><code>checked<T, E = varies></code></a>
132 <p>A type alias to a <code>std_checked<T, E></code> (standalone edition) or <code>boost_checked<T, E></code> (Boost edition).</p><li>
133 <a href="./reference/aliases/default_policy.html" ><code>default_policy<T, EC, EP></code></a>
134 <p>A type alias to a no-value policy selected based on traits matching of <code>T</code>, <code>EC</code> and <code>EP</code>.</p><li>
135 <a href="./reference/aliases/eager.html" ><code>eager<T>/atomic_eager<T></code></a>
136 <p>An eagerly evaluated coroutine awaitable with Outcome customisation.</p><li>
137 <a href="./reference/aliases/lazy.html" ><code>lazy<T>/atomic_lazy<T></code></a>
138 <p>A lazily evaluated coroutine awaitable with Outcome customisation.</p><li>
139 <a href="./reference/aliases/outcome.html" ><code>outcome<T, EC = varies, EP = varies, NoValuePolicy = policy::default_policy<T, EC, EP>></code></a>
140 <p>A type alias to a <code>std_outcome<T, EC, EP, NoValuePolicy></code> (standalone edition) or <code>boost_outcome<T, EC, EP, NoValuePolicy></code> (Boost edition).</p><li>
141 <a href="./reference/aliases/result.html" ><code>result<T, E = varies, NoValuePolicy = policy::default_policy<T, E, void>></code></a>
142 <p>A type alias to a <code>std_result<T, E, NoValuePolicy></code> (standalone edition) or <code>boost_result<T, E, NoValuePolicy></code> (Boost edition).</p><li>
143 <a href="./reference/aliases/std_checked.html" ><code>std_checked<T, E = std::error_code></code></a>
144 <p>A type alias to a <code>basic_result</code> configured with <code>std::error_code</code> and <code>policy::throw_bad_result_access<EC></code>.</p><li>
145 <a href="./reference/aliases/std_outcome.html" ><code>std_outcome<T, EC = std::error_code, EP = std::exception_ptr, NoValuePolicy = policy::default_policy<T, EC, EP>></code></a>
146 <p>A type alias to a <code>basic_outcome</code> configured with <code>std::error_code</code>, <code>std::exception_ptr</code> and <code>policy::default_policy</code>.</p><li>
147 <a href="./reference/aliases/std_result.html" ><code>std_result<T, E = std::error_code, NoValuePolicy = policy::default_policy<T, E, void>></code></a>
148 <p>A type alias to a <code>basic_result</code> configured with <code>std::error_code</code> and <code>policy::default_policy</code>.</p><li>
149 <a href="./reference/aliases/std_unchecked.html" ><code>std_unchecked<T, E = std::error_code></code></a>
150 <p>A type alias to a <code>basic_result</code> configured with <code>std::error_code</code> and <code>policy::all_narrow</code>.</p><li>
151 <a href="./reference/aliases/unchecked.html" ><code>unchecked<T, E = varies></code></a>
152 <p>A type alias to a <code>std_unchecked<T, E></code> (standalone edition) or <code>boost_unchecked<T, E></code> (Boost edition).</p></li></ol><li>
153 <a href="./reference/functions.html" >Functions</a><ol><li>
154 <a href="./reference/functions/hooks.html" >Hooks</a>
155 <p>Functions used to hook into the functionality of <code>basic_result</code> and <code>basic_outcome</code>.</p><li>
156 <a href="./reference/functions/iostream.html" >Iostream</a>
157 <p>Functions used to print, serialise and deserialise <code>basic_result</code> and <code>basic_outcome</code>.</p><li>
158 <a href="./reference/functions/policy.html" >Policy</a>
159 <p>Functions used to customise how the policy classes operate.</p><li>
160 <a href="./reference/functions/failure.html" ><code>auto failure(T &&, ...)</code></a>
161 <p>Returns appropriate type sugar for constructing an unsuccessful result or outcome.</p><li>
162 <a href="./reference/functions/success.html" ><code>auto success(T &&)</code></a>
163 <p>Returns appropriate type sugar for constructing a successful result or outcome.</p><li>
164 <a href="./reference/functions/try_operation_has_value.html" ><code>bool try_operation_has_value(X)</code></a>
165 <p>Default implementation of <code>try_operation_has_value(X)</code> ADL customisation point for <code>BOOST_OUTCOME_TRY</code>.</p><li>
166 <a href="./reference/functions/try_operation_extract_value.html" ><code>decltype(auto) try_operation_extract_value(X)</code></a>
167 <p>Default implementation of <code>try_operation_extract_value(X)</code> ADL customisation point for <code>BOOST_OUTCOME_TRY</code>.</p><li>
168 <a href="./reference/functions/try_operation_return_as.html" ><code>decltype(auto) try_operation_return_as(X)</code></a>
169 <p>Default implementation of <code>try_operation_return_as(X)</code> ADL customisation point for <code>BOOST_OUTCOME_TRY</code>.</p><li>
170 <a href="./reference/functions/error_from_exception.html" ><code>std::error_code error_from_exception(std::exception_ptr &&ep = std::current_exception(), std::error_code not_matched = std::make_error_code(std::errc::resource_unavailable_try_again)) noexcept</code></a>
171 <p>Returns an error code matching a thrown standard library exception.</p><li>
172 <a href="./reference/functions/strong_swap.html" ><code>void strong_swap(bool &all_good, T &a, T &b)</code></a>
173 <p>Tries to perform a strong guarantee swap.</p><li>
174 <a href="./reference/functions/try_throw_std_exception_from_error.html" ><code>void try_throw_std_exception_from_error(std::error_code ec, const std::string &msg = std::string{})</code></a>
175 <p>Try to throw a standard library exception type matching an error code.</p></li></ol></li></ol>
184 </div><p><small>Last revised: December 10, 2018 at 20:32:00 UTC</small></p>
186 <div class="spirit-nav">
187 <a accesskey="p" href="./experimental/c-api/reference.html"><img src="./images/prev.png" alt="Prev"></a>
188 <a accesskey="u" href="./index.html"><img src="./images/up.png" alt="Up"></a>
189 <a accesskey="h" href="./index.html"><img src="./images/home.png" alt="Home"></a><a accesskey="n" href="./reference/macros.html"><img src="./images/next.png" alt="Next"></a></div></body>
projects / platform / upstream / boost.git / blob