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"/> 7 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"> 13 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/enable_legacy_support_for.html" ><code>BOOST_OUTCOME_ENABLE_LEGACY_SUPPORT_FOR</code></a> 34<p>Enables backwards features and naming compatibility for earlier versions of Outcome.</p><li> 35 <a href="./reference/macros/nodiscard.html" ><code>BOOST_OUTCOME_NODISCARD</code></a> 36<p>How to tell the compiler than the return value of a function should not be discarded without examining it.</p><li> 37 <a href="./reference/macros/requires.html" ><code>BOOST_OUTCOME_REQUIRES(...)</code></a> 38<p>A C++ 20 <code>requires(...)</code>, if available.</p><li> 39 <a href="./reference/macros/symbol_visible.html" ><code>BOOST_OUTCOME_SYMBOL_VISIBLE</code></a> 40<p>How to mark throwable types as always having default ELF symbol visibility.</p><li> 41 <a href="./reference/macros/thread_local.html" ><code>BOOST_OUTCOME_THREAD_LOCAL</code></a> 42<p>How to mark variables as having thread local storage duration.</p><li> 43 <a href="./reference/macros/throw_exception.html" ><code>BOOST_OUTCOME_THROW_EXCEPTION(expr)</code></a> 44<p>How to throw a C++ exception, or equivalent thereof.</p><li> 45 <a href="./reference/macros/try.html" ><code>BOOST_OUTCOME_TRY(var, expr)</code></a> 46<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> 47 <a href="./reference/macros/tryv.html" ><code>BOOST_OUTCOME_TRYV(expr)/BOOST_OUTCOME_TRY(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/tryv_failure_likely.html" ><code>BOOST_OUTCOME_TRYV_FAILURE_LIKELY(expr)/BOOST_OUTCOME_TRY_FAILURE_LIKELY(expr)</code></a> 50<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> 51 <a href="./reference/macros/tryx.html" ><code>BOOST_OUTCOME_TRYX(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/tryx_failure_likely.html" ><code>BOOST_OUTCOME_TRYX_FAILURE_LIKELY(expr)</code></a> 54<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> 55 <a href="./reference/macros/try_failure_likely.html" ><code>BOOST_OUTCOME_TRY_FAILURE_LIKELY(var, expr)</code></a> 56<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> 57 <a href="./reference/macros/in_place_type.html" ><code>BOOST_OUTCOME_USE_STD_IN_PLACE_TYPE</code></a> 58<p>How to implement <code>in_place_type_t<T></code> and <code>in_place_type<T></code>.</p><li> 59 <a href="./reference/macros/is_nothrow_swappable.html" ><code>BOOST_OUTCOME_USE_STD_IS_NOTHROW_SWAPPABLE</code></a> 60<p>How to implement <code>is_nothrow_swappable<T></code>.</p></li></ol><li> 61 <a href="./reference/concepts.html" >Concepts</a><ol><li> 62 <a href="./reference/concepts/basic_outcome.html" ><code>basic_outcome<T></code></a> 63<p>A boolean concept matching types which are convertible to a <code>basic_outcome<T, EC, EP, NoValuePolicy></code>.</p><li> 64 <a href="./reference/concepts/basic_result.html" ><code>basic_result<T></code></a> 65<p>A boolean concept matching types which are convertible to a <code>basic_result<T, E, NoValuePolicy></code>.</p><li> 66 <a href="./reference/concepts/value_or_error.html" ><code>value_or_error<T></code></a> 67<p>A boolean concept matching types with either a value or an error.</p><li> 68 <a href="./reference/concepts/value_or_none.html" ><code>value_or_none<T></code></a> 69<p>A boolean concept matching types with an optional value.</p></li></ol><li> 70 <a href="./reference/converters.html" >Converters</a><ol><li> 71 <a href="./reference/converters/value_or_error.html" ><code>value_or_error<T, U></code></a> 72<p>A customisable converter of <code>ValueOrError<T, E></code> concept matching types.</p></li></ol><li> 73 <a href="./reference/traits.html" >Traits</a><ol><li> 74 <a href="./reference/traits/is_basic_outcome.html" ><code>is_basic_outcome<T></code></a> 75<p>An integral constant type true for <code>basic_outcome<T, EC, EP, NoValuePolicy></code> types.</p><li> 76 <a href="./reference/traits/is_basic_result.html" ><code>is_basic_result<T></code></a> 77<p>An integral constant type true for <code>basic_result<T, E, NoValuePolicy></code> types.</p><li> 78 <a href="./reference/traits/is_error_code_available.html" ><code>is_error_code_available<T></code></a> 79<p>True if an error code can be constructed from a <code>T</code>.</p><li> 80 <a href="./reference/traits/is_error_type.html" ><code>is_error_type<E></code></a> 81<p>A customisable integral constant type true for <code>E</code> types which are to receive error throwing no-value policies.</p><li> 82 <a href="./reference/traits/is_error_type_enum.html" ><code>is_error_type_enum<E, Enum></code></a> 83<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> 84 <a href="./reference/traits/is_exception_ptr_available.html" ><code>is_exception_ptr_available<T></code></a> 85<p>True if an exception ptr can be constructed from a <code>T</code>.</p><li> 86 <a href="./reference/traits/is_failure_type.html" ><code>is_failure_type<T></code></a> 87<p>An integral constant boolean variable true for <code>failure_type<EC, E = void></code> types.</p><li> 88 <a href="./reference/traits/is_success_type.html" ><code>is_success_type<T></code></a> 89<p>An integral constant boolean variable true for <code>success_type<T></code> types.</p><li> 90 <a href="./reference/traits/type_can_be_used_in_basic_result.html" ><code>type_can_be_used_in_basic_result<R></code></a> 91<p>A constexpr boolean true for types permissible in <code>basic_result<T, E, NoValuePolicy></code>.</p></li></ol><li> 92 <a href="./reference/policies.html" >Policies</a><ol><li> 93 <a href="./reference/policies/base.html" ><code>base</code></a> 94<p>Base class of most policy classes defining the narrow observer policies.</p><li> 95 <a href="./reference/policies/all_narrow.html" ><code>all_narrow</code></a> 96<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> 97 <a href="./reference/policies/error_code_throw_as_system_error_outcome.html" ><code>error_code_throw_as_system_error<T, EC, EP></code></a> 98<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> 99 <a href="./reference/policies/error_code_throw_as_system_error_result.html" ><code>error_code_throw_as_system_error<T, EC, void></code></a> 100<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> 101 <a href="./reference/policies/exception_ptr_rethrow_outcome.html" ><code>exception_ptr_rethrow<T, EC, EP></code></a> 102<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> 103 <a href="./reference/policies/exception_ptr_rethrow_result.html" ><code>exception_ptr_rethrow<T, EC, void></code></a> 104<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> 105 <a href="./reference/policies/fail_to_compile_observers.html" ><code>fail_to_compile_observers</code></a> 106<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> 107 <a href="./reference/policies/terminate.html" ><code>terminate</code></a> 108<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> 109 <a href="./reference/policies/throw_bad_result_access.html" ><code>throw_bad_result_access<EC></code></a> 110<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> 111 <a href="./reference/types.html" >Types</a><ol><li> 112 <a href="./reference/types/basic_outcome.html" ><code>basic_outcome<T, EC, EP, NoValuePolicy></code></a> 113<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> 114 <a href="./reference/types/basic_result.html" ><code>basic_result<T, E, NoValuePolicy></code></a> 115<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> 116 <a href="./reference/types/bad_outcome_access.html" ><code>bad_outcome_access</code></a> 117<p>Exception type publicly inheriting from <code>std::logic_error</code> indicating an incorrect observation of value or error or exception occurred.</p><li> 118 <a href="./reference/types/bad_result_access_with.html" ><code>bad_result_access_with<EC></code></a> 119<p>Exception type publicly inheriting from <code>bad_result_access</code> indicating an incorrect observation of value occurred, supplying the error value.</p><li> 120 <a href="./reference/types/bad_result_access.html" ><code>bad_result_access</code></a> 121<p>Exception type publicly inheriting from <code>std::logic_error</code> indicating an incorrect observation of value or error occurred.</p><li> 122 <a href="./reference/types/awaitables/eager.html" ><code>eager<T>/atomic_eager<T></code></a> 123<p>An eagerly evaluated coroutine awaitable with Outcome customisation.</p><li> 124 <a href="./reference/types/failure_type.html" ><code>failure_type<EC, EP = void></code></a> 125<p>Type sugar for constructing an unsuccessful result or outcome.</p><li> 126 <a href="./reference/types/in_place_type_t.html" ><code>in_place_type_t<T></code></a> 127<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> 128 <a href="./reference/types/awaitables/lazy.html" ><code>lazy<T>/atomic_lazy<T></code></a> 129<p>A lazily evaluated coroutine awaitable with Outcome customisation.</p><li> 130 <a href="./reference/types/success_type.html" ><code>success_type<T></code></a> 131<p>Type sugar for constructing a successful result or outcome.</p></li></ol><li> 132 <a href="./reference/aliases.html" >Aliases</a><ol><li> 133 <a href="./reference/aliases/boost_checked.html" ><code>boost_checked<T, E = boost::system::error_code></code></a> 134<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> 135 <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> 136<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> 137 <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> 138<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> 139 <a href="./reference/aliases/boost_unchecked.html" ><code>boost_unchecked<T, E = boost::system::error_code></code></a> 140<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> 141 <a href="./reference/aliases/checked.html" ><code>checked<T, E = varies></code></a> 142<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> 143 <a href="./reference/aliases/default_policy.html" ><code>default_policy<T, EC, EP></code></a> 144<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> 145 <a href="./reference/aliases/outcome.html" ><code>outcome<T, EC = varies, EP = varies, NoValuePolicy = policy::default_policy<T, EC, EP>></code></a> 146<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> 147 <a href="./reference/aliases/result.html" ><code>result<T, E = varies, NoValuePolicy = policy::default_policy<T, E, void>></code></a> 148<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> 149 <a href="./reference/aliases/std_checked.html" ><code>std_checked<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::throw_bad_result_access<EC></code>.</p><li> 151 <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> 152<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> 153 <a href="./reference/aliases/std_result.html" ><code>std_result<T, E = std::error_code, NoValuePolicy = policy::default_policy<T, E, void>></code></a> 154<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> 155 <a href="./reference/aliases/std_unchecked.html" ><code>std_unchecked<T, E = std::error_code></code></a> 156<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> 157 <a href="./reference/aliases/unchecked.html" ><code>unchecked<T, E = varies></code></a> 158<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> 159 <a href="./reference/functions.html" >Functions</a><ol><li> 160 <a href="./reference/functions/hooks.html" >Hooks</a> 161<p>Functions used to hook into the functionality of <code>basic_result</code> and <code>basic_outcome</code>.</p><li> 162 <a href="./reference/functions/iostream.html" >Iostream</a> 163<p>Functions used to print, serialise and deserialise <code>basic_result</code> and <code>basic_outcome</code>.</p><li> 164 <a href="./reference/functions/policy.html" >Policy</a> 165<p>Functions used to customise how the policy classes operate.</p><li> 166 <a href="./reference/functions/failure.html" ><code>auto failure(T &&, ...)</code></a> 167<p>Returns appropriate type sugar for constructing an unsuccessful result or outcome.</p><li> 168 <a href="./reference/functions/success.html" ><code>auto success(T &&)</code></a> 169<p>Returns appropriate type sugar for constructing a successful result or outcome.</p><li> 170 <a href="./reference/functions/try_operation_has_value.html" ><code>bool try_operation_has_value(X)</code></a> 171<p>Default implementation of <code>try_operation_has_value(X)</code> ADL customisation point for <code>BOOST_OUTCOME_TRY</code>.</p><li> 172 <a href="./reference/functions/try_operation_extract_value.html" ><code>decltype(auto) try_operation_extract_value(X)</code></a> 173<p>Default implementation of <code>try_operation_extract_value(X)</code> ADL customisation point for <code>BOOST_OUTCOME_TRY</code>.</p><li> 174 <a href="./reference/functions/try_operation_return_as.html" ><code>decltype(auto) try_operation_return_as(X)</code></a> 175<p>Default implementation of <code>try_operation_return_as(X)</code> ADL customisation point for <code>BOOST_OUTCOME_TRY</code>.</p><li> 176 <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> 177<p>Returns an error code matching a thrown standard library exception.</p><li> 178 <a href="./reference/functions/strong_swap.html" ><code>void strong_swap(bool &all_good, T &a, T &b)</code></a> 179<p>Tries to perform a strong guarantee swap.</p><li> 180 <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> 181<p>Try to throw a standard library exception type matching an error code.</p></li></ol></li></ol> 182 183 184 185 186 187 188 189 190 </div><p><small>Last revised: December 10, 2018 at 20:32:00 UTC</small></p> 191<hr> 192<div class="spirit-nav"> 193<a accesskey="p" href="./experimental/c-api/reference.html"><img src="./images/prev.png" alt="Prev"></a> 194 <a accesskey="u" href="./index.html"><img src="./images/up.png" alt="Up"></a> 195 <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> 196</html> 197
