basic_result<T, E, NoValuePolicy>
A sum type carrying either a T
or an E
, with NoValuePolicy
specifying what to do if one tries to read state which isn’t there. Either or both of T
and E
can be void
to indicate no value for that state is present. Note that E = void
makes basic result into effectively an optional<T>
, but with NoValuePolicy
configurable behaviour. Detectable using is_basic_result<T>
.
Requires: Concept requirements if C++ 20, else static asserted:
- That trait
type_can_be_used_in_basic_result<R>
is true for bothT
andE
. - That either
E
isvoid
orDefaultConstructible
.
Namespace: BOOST_OUTCOME_V2_NAMESPACE
Header: <boost/outcome/basic_result.hpp>
Inclusions: The very lightest weight of C and C++ header files:
<cstdint>
<initializer_list>
<iosfwd>
<new>
<type_traits>
- If
BOOST_OUTCOME_USE_STD_IN_PLACE_TYPE
is1
,<utility>
(defaults to1
for C++ 17 or later only) - If C++ exceptions disabled and
BOOST_OUTCOME_DISABLE_EXECINFO
undefined only (used to print stack backtraces on “exception throw”):<sal.h>
(Windows only)<stddef.h>
(Windows only)<string.h>
(Windows only)<execinfo.h>
(POSIX only)
<cstdio>
<cstdlib>
<cassert>
This very light weight set of inclusion dependencies makes basic result suitable for use in global header files of very large C++ codebases.
Design rationale
The basic result type is the main workhorse type of the Outcome library, providing a simple sum type with optional values representing success or disappointment. Unlike
P0323 std::expected<T, E>
, Outcome’s result type is designed specifically for convenience when implementing failure handling across very large codebases, and it has a number of API differences to facilitate that.
The first major design difference is that basic result models its constructor design on
std::variant<...>
, rather than modelling
std::optional<T>
’s constructor design like std::expected<T, E>
does. This means that basic result will implicitly construct either a T
or an E
if doing so is unambiguous, same as variant
does. Where implicit construction is ambiguous, the implicit constructors disable and a T
or E
can be specified via in_place_type_t<T>
, or via success_type<T>
or failure_type<T>
. We implement a subset of variant’s constructors for improved compile time impact, so the implicit and explicit constructor design is split into fixed subsets to reduce SFINAE execution.
The second major design difference is that union storage is NOT used, as it is assumed that sizeof(E)
will be small for failure handling. This very considerably reduces load on the compiler, and substantially improves compile times in very large C++ 14 codebases, because copies and moves do not need to jump through complex ceremony in order to implement the never-empty guarantees which would be required in a union storage based implementation (C++ 17 onwards does far fewer copy and move constructor instantiations, but it all adds up – work avoided is always the fastest).
Public member type aliases
value_type
isT
.error_type
isE
.value_type_if_enabled
isT
if construction fromT
is available, else it is a usefully named unusable internal type.error_type_if_enabled
isE
if construction fromE
is available, else it is a usefully named unusable internal type.rebind<A, B = E, C = NoValuePolicy>
isbasic_result<A, B, C>
.
Protected member predicate booleans
predicate::constructors_enabled
is constexpr boolean true if decayedvalue_type
and decayederror_type
are not the same type.predicate::implicit_constructors_enabled
is constexpr boolean true if:predicate::constructors_enabled
is true.- Trait
is_error_type<E>
is not true for both decayedvalue_type
and decayederror_type
at the same time. value_type
is not implicitly constructible fromerror_type
anderror_type
is not implicitly constructible fromvalue_type
.
OR
traitis_error_type<E>
is true for decayederror_type
anderror_type
is not implicitly constructible fromvalue_type
andvalue_type
is an integral type.
predicate::enable_value_converting_constructor<A>
is constexpr boolean true if:predicate::constructors_enabled
is true.- Decayed
A
is not thisbasic_result
type. predicate::implicit_constructors_enabled
is true.- Decayed
A
is not anin_place_type_t
. - Trait
is_error_type_enum<E, Enum>
is false forerror_type
and decayedA
. value_type
is implicitly constructible fromA
anderror_type
is not implicitly constructible fromA
.
ORvalue_type
is the exact same type as decayedA
andvalue_type
is implicitly constructible fromA
.
predicate::enable_error_converting_constructor<A>
is constexpr boolean true if:predicate::constructors_enabled
is true.- Decayed
A
is not thisbasic_result
type. predicate::implicit_constructors_enabled
is true.- Decayed
A
is not anin_place_type_t
. - Trait
is_error_type_enum<E, Enum>
is false forerror_type
and decayedA
. value_type
is not implicitly constructible fromA
anderror_type
is implicitly constructible fromA
.
ORerror_type
is the exact same type as decayedA
anderror_type
is implicitly constructible fromA
.
predicate::enable_error_condition_converting_constructor<ErrorCondEnum>
is constexpr boolean true if:predicate::constructors_enabled
is true.- Decayed
ErrorCondEnum
is not thisbasic_result
type. - Decayed
ErrorCondEnum
is not anin_place_type_t
. - Trait
is_error_type_enum<E, Enum>
is true forerror_type
and decayedErrorCondEnum
.
predicate::enable_compatible_conversion<A, B, C>
is constexpr boolean true if:predicate::constructors_enabled
is true.basic_result<A, B, C>
is not thisbasic_result
type.A
isvoid
ORvalue_type
is explicitly constructible fromA
.B
isvoid
ORerror_type
is explicitly constructible fromB
.
predicate::enable_make_error_code_compatible_conversion<A, B, C>
is constexpr boolean true if:predicate::constructors_enabled
is true.basic_result<A, B, C>
is not thisbasic_result
type.- Trait "/home/travis/build/ned14/boost-outcome/doc/src/content/reference/types/basic_result/_index.md:92:14": API reference page for 'is_error_code_available<E>' not found, please use an identifier wholly contained in a page title
API NOT FOUND IN DOCS
is_error_code_available<E>
is true for decayederror_type
. predicate::enable_compatible_conversion<A, B, C>
is not true.A
isvoid
ORvalue_type
is explicitly constructible fromA
.error_type
is explicitly constructible frommake_error_code(B)
.
predicate::enable_make_exception_ptr_compatible_conversion<A, B, C>
is constexpr boolean true if:predicate::constructors_enabled
is true.basic_result<A, B, C>
is not thisbasic_result
type.- Trait "/home/travis/build/ned14/boost-outcome/doc/src/content/reference/types/basic_result/_index.md:100:14": API reference page for 'is_exception_ptr_available<E>' not found, please use an identifier wholly contained in a page title
API NOT FOUND IN DOCS
is_exception_ptr_available<E>
is true for decayederror_type
. predicate::enable_compatible_conversion<A, B, C>
is not true.A
isvoid
ORvalue_type
is explicitly constructible fromA
.error_type
is explicitly constructible frommake_exception_ptr(B)
.
predicate::enable_inplace_value_constructor<Args...>
is constexpr boolean true if:predicate::constructors_enabled
is true.value_type
isvoid
ORvalue_type
is explicitly constructible fromArgs...
.
predicate::enable_inplace_error_constructor<Args...>
is constexpr boolean true if:predicate::constructors_enabled
is true.error_type
isvoid
ORerror_type
is explicitly constructible fromArgs...
.
predicate::enable_inplace_value_error_constructor<Args...>
is constexpr boolean true if:predicate::constructors_enabled
is true.predicate::implicit_constructors_enabled
is true.- Either, but not both, of
value_type
is explicitly constructible fromArgs...
orerror_type
is explicitly constructible fromArgs...
.
Summary of standard requirements provided
, always deleted to force user to choose valued or errored for every result instanced.DefaultConstructible
MoveConstructible
, if bothvalue_type
anderror_type
implement move constructors.CopyConstructible
, if bothvalue_type
anderror_type
implement copy constructors.MoveAssignable
, if bothvalue_type
anderror_type
implement move constructors and move assignment.CopyAssignable
, if bothvalue_type
anderror_type
implement copy constructors and copy assignment.Destructible
.TriviallyCopyable
, if bothvalue_type
anderror_type
are trivially copyable.TrivialType
, if bothvalue_type
anderror_type
are trivial types.LiteralType
, if bothvalue_type
anderror_type
are literal types.StandardLayoutType
, if bothvalue_type
anderror_type
are standard layout types. If so, layout ofbasic_result
in C is guaranteed to be:struct result_layout { value_type value; unsigned int flags; error_type error; };
EqualityComparable
, if bothvalue_type
anderror_type
implement equality comparisons with one another., not implemented due to availability of implicit conversions fromLessThanComparable
value_type
anderror_type
, this can cause major surprise (i.e. hard to diagnose bugs), so we don’t implement these at all. ~Swappable
, not implemented as a generic implementation of a unique hash for non-valued items which are unequal would require a dependency on RTTI being enabled.Hash
Thus basic_result
meets the Regular
concept if both value_type
and error_type
are Regular
, except for the lack of a default constructor. Often where one needs a default constructor, wrapping basic_result
into
std::optional<T>
will suffice.
Public member functions
Disabling constructors
-
basic_result(Args...) = delete
Disabling catchall constructor used to give useful diagnostic error when trying to use non-inplace constructors when
predicate::constructors_enabled
is false. -
basic_result(X &&) = delete
Disabling implicit constructor used to give useful diagnostic error when trying to use implicit constructors when
predicate::implicit_constructors_enabled
is false.
Copy and move constructors and assignment, and destructor
-
basic_result() = delete
The default constructor (disabled).
-
basic_result(basic_result &&)
Move constructor. Constexpr, triviality and noexcept propagating.
-
basic_result(const basic_result &)
Copy constructor. Constexpr, triviality and noexcept propagating.
-
basic_result &operator=(basic_result &&)
Move assignment. Constexpr, triviality and noexcept propagating.
-
basic_result &operator=(const basic_result &)
Copy assignment. Constexpr, triviality and noexcept propagating.
-
~basic_result()
Destructor. Constexpr, triviality and noexcept propagating.
Converting constructors
-
basic_result(R &&)
Implicit
value_type
constructor. Available ifpredicate::enable_value_converting_constructor<R>
is true. Constexpr, triviality and noexcept propagating. -
basic_result(S &&)
Implicit
error_type
constructor. Available ifpredicate::enable_error_converting_constructor<S>
is true. Constexpr, triviality and noexcept propagating. -
basic_result(ErrorCondEnum &&)
Implicit
error_type
fromErrorCondEnum
constructor. Available ifpredicate::enable_error_condition_converting_constructor<ErrorCondEnum>
is true. Constexpr, triviality and noexcept propagating. -
explicit basic_result(ValueOrError<T, E> &&)
Explicit converting constructor from
ValueOrError<T, E>
concept matching types. Available ifconvert::value_or_error<>
permits it. Constexpr, triviality and noexcept propagating. -
explicit basic_result(const basic_result<R, S, P> &)
Explicit converting copy constructor from compatible
basic_result
. Available ifpredicate::enable_compatible_conversion<R, S, P>
is true. Constexpr, triviality and noexcept propagating. -
explicit basic_result(basic_result<R, S, P> &&)
Explicit converting move constructor from compatible
basic_result
. Available ifpredicate::enable_compatible_conversion<R, S, P>
is true. Constexpr, triviality and noexcept propagating. -
explicit basic_result(const basic_result<R, S, P> &)
Explicit converting copy constructor from compatible
basic_result
. Available ifpredicate::enable_make_error_code_compatible_conversion<R, S, P>
is true. Constexpr, triviality and noexcept propagating. -
explicit basic_result(basic_result<R, S, P> &&)
Explicit converting move constructor from compatible
basic_result
. Available ifpredicate::enable_make_error_code_compatible_conversion<R, S, P>
is true. Constexpr, triviality and noexcept propagating. -
explicit basic_result(const basic_result<R, S, P> &)
Explicit converting copy constructor from compatible
basic_result
. Available ifpredicate::enable_make_exception_ptr_compatible_conversion<R, S, P>
is true. Constexpr, triviality and noexcept propagating. -
explicit basic_result(basic_result<R, S, P> &&)
Explicit converting move constructor from compatible
basic_result
. Available ifpredicate::enable_make_exception_ptr_compatible_conversion<R, S, P>
is true. Constexpr, triviality and noexcept propagating.
Inplace constructors
-
explicit basic_result(in_place_type_t<value_type_if_enabled>, Args ...)
Explicit inplace value constructor. Available if
predicate::enable_inplace_value_constructor<Args ...>
is true. Constexpr, triviality and noexcept propagating. -
explicit basic_result(in_place_type_t<value_type_if_enabled>, std::initializer_list<U>, Args ...)
Explicit inplace value constructor. Available if
predicate::enable_inplace_value_constructor<std::initializer_list<U>, Args ...>
is true. Constexpr, triviality and noexcept propagating. -
explicit basic_result(in_place_type_t<error_type_if_enabled>, Args ...)
Explicit inplace error constructor. Available if
predicate::enable_inplace_error_constructor<Args ...>
is true. Constexpr, triviality and noexcept propagating. -
explicit basic_result(in_place_type_t<error_type_if_enabled>, std::initializer_list<U>, Args ...)
Explicit inplace error constructor. Available if
predicate::enable_inplace_error_constructor<std::initializer_list<U>, Args ...>
is true. Constexpr, triviality and noexcept propagating. -
basic_result(A1 &&, A2 &&, Args ...)
Implicit inplace value or error constructor. Available if
predicate::enable_inplace_value_error_constructor<A1, A2, Args ...>
is true. Constexpr, triviality and noexcept propagating.
Tagged constructors
-
basic_result(const success_type<T> &)
Implicit value-from-success-type-sugar copy constructor. Available if
predicate::enable_compatible_conversion<T, void, void>
is true, orT
isvoid
. Constexpr, triviality and noexcept propagating. -
basic_result(success_type<T> &&)
Implicit value-from-success-type-sugar move constructor. Available if
predicate::enable_compatible_conversion<T, void, void>
is true, orT
isvoid
. Constexpr, triviality and noexcept propagating. -
basic_result(const failure_type<T> &)
Implicit error-from-failure-type-sugar copy constructor. Available if
predicate::enable_compatible_conversion<void, T, void>
is true, orT
isvoid
. Constexpr, triviality and noexcept propagating. -
basic_result(failure_type<T> &&)
Implicit error-from-failure-type-sugar move constructor. Available if
predicate::enable_compatible_conversion<void, T, void>
is true, orT
isvoid
. Constexpr, triviality and noexcept propagating. -
basic_result(const failure_type<T> &)
Implicit error-from-failure-type-sugar copy constructor. Available if
predicate::enable_make_error_code_compatible_conversion<void, T, void>
is true, orT
isvoid
. Constexpr, triviality and noexcept propagating. -
basic_result(failure_type<T> &&)
Implicit error-from-failure-type-sugar move constructor. Available if
predicate::enable_make_error_code_compatible_conversion<void, T, void>
is true, orT
isvoid
. Constexpr, triviality and noexcept propagating. -
basic_result(const failure_type<T> &)
Implicit error-from-failure-type-sugar copy constructor. Available if
predicate::enable_make_exception_ptr_compatible_conversion<void, T, void>
is true, orT
isvoid
. Constexpr, triviality and noexcept propagating. -
basic_result(failure_type<T> &&)
Implicit error-from-failure-type-sugar move constructor. Available if
predicate::enable_make_exception_ptr_compatible_conversion<void, T, void>
is true, orT
isvoid
. Constexpr, triviality and noexcept propagating.
Observers
-
explicit operator bool() const noexcept
Returns true if a value is present. Constexpr, never throws.
-
bool has_value() const noexcept
Returns true if a value is present. Constexpr, never throws.
-
bool has_error() const noexcept
Returns true if an error is present. Constexpr, never throws.
-
bool has_exception() const noexcept
Always returns false for
basic_result
. Constexpr, never throws. -
bool has_failure() const noexcept
Returns true if there is either an error or an exception. Constexpr, never throws.
-
bool has_lost_consistency() const noexcept
Returns true if a preceding swap involving this object failed to preserve the strong guarantee. Constexpr, never throws.
-
value_type &assume_value() & noexcept
Narrow contract lvalue reference observer of any value present. Constexpr propagating, never throws.
-
const value_type &assume_value() const & noexcept
Narrow contract const lvalue reference observer of any value present. Constexpr propagating, never throws.
-
value_type &&assume_value() && noexcept
Narrow contract rvalue reference observer of any value present. Constexpr propagating, never throws.
-
const value_type &&assume_value() const && noexcept
Narrow contract const rvalue reference observer of any value present. Constexpr propagating, never throws.
-
value_type &value() &
Wide contract lvalue reference observer of any value present. Constexpr propagating.
-
const value_type &value() const &
Wide contract const lvalue reference observer of any value present. Constexpr propagating.
-
value_type &&value() &&
Wide contract rvalue reference observer of any value present. Constexpr propagating.
-
const value_type &&value() const &&
Wide contract const rvalue reference observer of any value present. Constexpr propagating.
-
error_type &assume_error() & noexcept
Narrow contract lvalue reference observer of the stored error. Constexpr propagating, never throws.
-
const error_type &assume_error() const & noexcept
Narrow contract const lvalue reference observer of the stored error. Constexpr propagating, never throws.
-
error_type &&assume_error() && noexcept
Narrow contract rvalue reference observer of the stored error. Constexpr propagating, never throws.
-
const error_type &&assume_error() const && noexcept
Narrow contract const rvalue reference observer of the stored error. Constexpr propagating, never throws.
-
error_type &error() &
Wide contract lvalue reference observer of the stored error. Constexpr propagating.
-
const error_type &error() const &
Wide contract const lvalue reference observer of the stored error. Constexpr propagating.
-
error_type &&error() &&
Wide contract rvalue reference observer of the stored error. Constexpr propagating.
-
const error_type &&error() const &&
Wide contract const rvalue reference observer of the stored error. Constexpr propagating.
-
auto as_failure() const &
Return the output from free function
failure()
containing a copy of any errored state.
Modifiers
-
void swap(basic_result &)
Swap one basic_result with another, with the strong guarantee. Noexcept propagating.
-
auto as_failure() &&
Return the output from free function
failure()
containing a move of any errored state.
Comparisons
See above for why LessThanComparable
is not implemented.
-
bool operator==(const basic_result<A, B, C> &) const
Returns true if this result compares equal to the other result. Constexpr and noexcept propagating.
-
bool operator==(const success_type<A> &) const
Returns true if this result compares equal to the success type sugar. Constexpr and noexcept propagating.
-
bool operator==(const failure_type<A, void> &) const
Returns true if this result compares equal to the failure type sugar. Constexpr and noexcept propagating.
-
bool operator!=(const basic_result<A, B, C> &) const
Returns true if this result does not compare equal to the other result. Constexpr and noexcept propagating.
-
bool operator!=(const success_type<A> &) const
Returns true if this result does not compare equal to the success type sugar. Constexpr and noexcept propagating.
-
bool operator!=(const failure_type<A, void> &) const
Returns true if this result does not compare equal to the failure type sugar. Constexpr and noexcept propagating.