Type that contains an ok value, or an error. More...

#include <sumty/result.hpp>

Inheritance diagram for result< T, E >:

Collaboration diagram for result< T, E >:

Public Types
using	value_type = ...

using	reference = ...

using	const_reference = ...

using	rvalue_reference = ...

using	const_rvalue_reference = ...

using	pointer = ...

using	const_pointer = ...

using	error_type = ...

using	error_reference = ...

using	error_const_reference = ...

using	error_rvalue_reference = ...

using	error_const_rvalue_reference = ...

using	error_pointer = ...

using	error_const_pointer = ...

template<typename U >
using	rebind = result< U, E >

template<typename V >
using	rebind_error = result< T, V >

using	unexpected_type = result< never, E >

Public Member Functions
constexpr	result () CONDITIONALLY_NOEXCEPT
	Default constructor. More...

constexpr	result (const result &) CONDITIONALLY_NOEXCEPT
	Copy constructor. More...

constexpr	result (result &&) CONDITIONALLY_NOEXCEPT
	Move constructor. More...

template<typename... Args>
constexpr CONDITONALLY_EXPLICIT	result ([[maybe_unused]] std::in_place_t inplace, Args &&... args)
	Emplacement constructor. More...

template<typename U , typename... Args>
constexpr	result ([[maybe_unused]] std::in_place_t inplace, std::initializer_list< U > init, Args &&... args)
	Emplacement constructor with initializer list. More...

template<typename... Args>
constexpr CONDITIONALLY_EXPLICIT	result (std::in_place_index_t< 0 > inplace, Args &&... args)
	Emplacement constructor. More...

template<typename U , typename... Args>
constexpr	result (std::in_place_index_t< 0 > inplace, std::initializer_list< U > init, Args &&... args)
	Emplacement constructor with initializer list. More...

template<typename... Args>
constexpr CONDITONALLY_EXPLICIT	result (in_place_error_t inplace, Args &&... args)
	Error emplacement constructor. More...

template<typename U , typename... Args>
constexpr	result (in_place_error_t inplace, std::initializer_list< U > init, Args &&... args)
	Error emplacement constructor with initializer list. More...

template<typename U >
constexpr CONDITIONALLY_EXPLICIT	result (U &&value)
	Forwarding constructor. More...

template<typename U , typename V >
constexpr CONDITIONALLY_EXPLICIT	result (const result< U, V > &other)
	Converting copy constructor. More...

template<typename U , typename V >
constexpr CONDITIONALLY_EXPLICIT	result (result< U, V > &&other)
	Converting move constructor. More...

constexpr	~result () CONDITIONALLY_NOEXCEPT
	Destructor. More...

constexpr result &	operator= (const result &) CONDITIONALLY_NOEXCEPT
	Copy assignment operator. More...

constexpr result &	operator= (result &&) CONDITIONALLY_NOEXCEPT
	Move assignment operator. More...

template<typename U >
constexpr result< T, E > &	operator= (U &&value)
	Value assignment operator. More...

constexpr	operator bool () const noexcept
	Implicit conversion to `bool`. More...

constexpr bool	has_value () const noexcept
	Returns `true` if the result contains an ok value. More...

constexpr bool	is_ok () const noexcept
	Returns `true` if the result contains an ok value. More...

constexpr bool	is_error () const noexcept
	Returns `true` if the result contains an error value. More...

constexpr reference	operator* () &noexcept
	Accesses the ok value contained in the result. More...

constexpr const_reference	operator* () const &noexcept
	Accesses the ok value contained in the result. More...

constexpr rvalue_reference	operator* () &&
	Accesses the ok value contained in the result. More...

constexpr const_rvalue_reference	operator* () const &&
	Accesses the ok value contained in the result. More...

constexpr pointer	operator-> () noexcept
	Accesses members of the ok value contained in the result. More...

constexpr const_pointer	operator-> () const noexcept
	Accesses members of the ok value contained in the result. More...

constexpr reference	value () &
	Accesses the ok value contained in the result. More...

constexpr const_reference	value () const &
	Accesses the ok value contained in the result. More...

constexpr rvalue_reference	value () &&
	Accesses the ok value contained in the result. More...

constexpr rvalue_reference	value () const &&
	Accesses the ok value contained in the result. More...

constexpr error_reference	error () &noexcept
	Accesses the error value contained in the result. More...

constexpr error_const_reference	error () const &noexcept
	Accesses the error value contained in the result. More...

constexpr error_rvalue_reference	error () &&
	Accesses the error value contained in the result. More...

constexpr error_const_rvalue_reference	error () const &&
	Accesses the error value contained in the result. More...

constexpr result< never, E >	prop_error () const &
	Extracts the error in order to propagate it. More...

constexpr result< never, E >	prop_error () &&
	Extracts the error in order to propagate it. More...

template<typename U >
constexpr value_type	value_or (U &&default_value) const &
	Gets the ok value, or a default if the result is an error. More...

template<typename U >
constexpr value_type	value_or (U &&default_value) &&
	Gets the ok value, or a default if the result is an error. More...

template<typename F >
constexpr value_type	value_or_else (F &&f) const &
	Gets the ok value, or returns the result of a callable. More...

template<typename F >
constexpr value_type	value_or_else (F &&f) &&
	Gets the ok value, or returns the result of a callable. More...

constexpr reference	ok () &
	Accesses the ok value contained in the result. More...

constexpr const_reference	ok () const &
	Accesses the ok value contained in the result. More...

constexpr rvalue_reference	ok () &&
	Accesses the ok value contained in the result. More...

constexpr rvalue_reference	ok () const &&
	Accesses the ok value contained in the result. More...

template<typename U >
constexpr value_type	ok_or (U &&default_value) const &
	Gets the ok value, or a default if the result is an error. More...

template<typename U >
constexpr value_type	ok_or (U &&default_value) &&
	Gets the ok value, or a default if the result is an error. More...

template<typename F >
constexpr value_type	ok_or_else (F &&f) const &
	Gets the ok value, or returns the result of a callable. More...

template<typename F >
constexpr value_type	ok_or_else (F &&f) &&
	Gets the ok value, or returns the result of a callable. More...

template<typename F >
constexpr auto	and_then (F &&f) &
	Applies a callable to the contents of a result. More...

template<typename F >
constexpr auto	and_then (F &&f) const &
	Applies a callable to the contents of a result. More...

template<typename F >
constexpr auto	and_then (F &&f) &&
	Applies a callable to the contents of a result. More...

template<typename F >
constexpr auto	and_then (F &&f) const &&
	Applies a callable to the contents of a result. More...

template<typename F >
constexpr auto	transform (F &&f) &
	Perforams a transformation on the ok value of a result. More...

template<typename F >
constexpr auto	transform (F &&f) const &
	Perforams a transformation on the ok value of a result. More...

template<typename F >
constexpr auto	transform (F &&f) &&
	Perforams a transformation on the ok value of a result. More...

template<typename F >
constexpr auto	transform (F &&f) const &&
	Perforams a transformation on the ok value of a result. More...

template<typename F >
constexpr auto	map (F &&f) &
	Perforams a transformation on the ok value of a result. More...

template<typename F >
constexpr auto	map (F &&f) const &
	Perforams a transformation on the ok value of a result. More...

template<typename F >
constexpr auto	map (F &&f) &&
	Perforams a transformation on the ok value of a result. More...

template<typename F >
constexpr auto	map (F &&f) const &&
	Perforams a transformation on the ok value of a result. More...

template<typename F >
constexpr result	or_else (F &&f) const &
	Returns the result of invoking `f` if the result is an error. More...

template<typename F >
constexpr result	or_else (F &&f) &&
	Returns the result of invoking `f` if the result is an error. More...

constexpr auto	flatten () const &
	Converts `result<result<T, E1>, E2>` into `result<T, E3>` More...

constexpr auto	flatten () &&
	Converts `result<result<T, E1>, E2>` into `result<T, E3>` More...

constexpr auto	flatten_all () const &
	Converts nested result types into a single result. More...

constexpr auto	flatten_all () &&
	Converts nested result types into a single result. More...

constexpr auto	transpose () const &
	Converts `result<option<T>, E>` into `option<result<T, E>>` More...

constexpr auto	transpose () &&
	Converts `result<option<T>, E>` into `option<result<T, E>>` More...

constexpr result< E, T >	invert () const &
	Swaps the ok and error types of a result. More...

constexpr result< E, T >	invert () &&
	Swaps the ok and error types of a result. More...

template<typename F >
constexpr auto	transform_error (F &&f) &
	Perforams a transformation on the error value of a result. More...

template<typename F >
constexpr auto	transform_error (F &&f) const &
	Perforams a transformation on the error value of a result. More...

template<typename F >
constexpr auto	transform_error (F &&f) &&
	Perforams a transformation on the error value of a result. More...

template<typename F >
constexpr auto	transform_error (F &&f) const &&
	Perforams a transformation on the error value of a result. More...

template<typename F >
constexpr auto	map_error (F &&f) &
	Perforams a transformation on the error value of a result. More...

template<typename F >
constexpr auto	map_error (F &&f) const &
	Perforams a transformation on the error value of a result. More...

template<typename F >
constexpr auto	map_error (F &&f) &&
	Perforams a transformation on the error value of a result. More...

template<typename F >
constexpr auto	map_error (F &&f) const &&
	Perforams a transformation on the error value of a result. More...

constexpr result< reference, error_reference >	ref () noexcept
	Converts a result reference into a result of references. More...

constexpr result< const_reference, error_const_reference >	ref () const noexcept
	Converts a result reference into a result of references. More...

constexpr result< const_reference, error_const_reference >	cref () const noexcept
	Converts a result reference into a result of references. More...

constexpr option< T >	or_none () const &noexcept
	Discards error values and converts into an option. More...

constexpr option< T >	or_none () &&
	Discards error values and converts into an option. More...

constexpr option< T >	ok_or_none () const &noexcept
	Discards error values and converts into an option. More...

constexpr option< T >	ok_or_none () &&
	Discards error values and converts into an option. More...

constexpr option< E >	error_or_none () const &noexcept
	Discards ok value and converts into an option. More...

constexpr option< E >	error_or_none () &&
	Discards ok value and converts into an option. More...

template<typename... Args>
constexpr reference	emplace (Args &&... args)
	Constructs a new ok value in place into the result. More...

template<typename U , typename... Args>
constexpr reference	emplace (std::initializer_list< U > ilist, Args &&... args)
	Constructs a new ok value in place into the result. More...

template<typename... Args>
constexpr error_reference	emplace_error (Args &&... args)
	Constructs a new error value in place into the result. More...

template<typename U , typename... Args>
constexpr error_reference	emplace_error (std::initializer_list< U > ilist, Args &&... args)
	Constructs a new error value in place into the result. More...

template<typename V >
constexpr DEDUCED	visit (V &&visitor) &
	Invokes a visitor witht he contained value. More...

template<typename V >
constexpr DEDUCED	visit (V &&visitor) const &
	Invokes a visitor witht he contained value. More...

template<typename V >
constexpr DEDUCED	visit (V &&visitor) &&
	Invokes a visitor witht he contained value. More...

template<typename V >
constexpr DEDUCED	visit (V &&visitor) const &&
	Invokes a visitor witht he contained value. More...

template<typename V >
constexpr DEDUCED	visit_informed (V &&visitor) &
	Invokes a visitor with the contained value and meta data. More...

template<typename V >
constexpr DEDUCED	visit_informed (V &&visitor) const &
	Invokes a visitor with the contained value and meta data. More...

template<typename V >
constexpr DEDUCED	visit_informed (V &&visitor) &&
	Invokes a visitor with the contained value and meta data. More...

template<typename V >
constexpr DEDUCED	visit_informed (V &&visitor) const &&
	Invokes a visitor with the contained value and meta data. More...

constexpr void	swap (result &other) CONDITIONALLY_NOEXCEPT
	Swaps two result instances. More...

Related Functions
(Note that these are not member functions.)
template<size_t IDX, typename T , typename E >
constexpr REFERENCE	get (result< T, E > &res)
	Gets a result value by index, as if it were a variant. More...

template<size_t IDX, typename T , typename E >
constexpr CONST_REFERENCE	get (const result< T, E > &res)
	Gets a result value by index, as if it were a variant. More...

template<size_t IDX, typename T , typename E >
constexpr RVALUE_REFERENCE	get (result< T, E > &&res)
	Gets a result value by index, as if it were a variant. More...

template<size_t IDX, typename T , typename E >
constexpr CONST_RVALUE_REFERENCE	get (const result< T, E > &&res)
	Gets a result value by index, as if it were a variant. More...

template<typename U , typename T , typename E >
constexpr REFERENCE	get (result< T, E > &res)
	Gets a result value by type, as if it were a variant. More...

template<typename U , typename T , typename E >
constexpr CONST_REFERENCE	get (const result< T, E > &res)
	Gets a result value by type, as if it were a variant. More...

template<typename U , typename T , typename E >
constexpr RVALUE_REFERENCE	get (result< T, E > &&res)
	Gets a result value by type, as if it were a variant. More...

template<typename U , typename T , typename E >
constexpr CONST_RVALUE_REFERENCE	get (const result< T, E > &&res)
	Gets a result value by type, as if it were a variant. More...

template<typename T , typename E , typename U , typename V >
constexpr bool	operator== (const result< T, E > &lhs, const result< U, V > &rhs)
	Compares two result instances for equality. More...

template<typename T , typename E , typename U >
constexpr bool	operator== (const result< T, E > &lhs, const U &rhs)
	Compares a result with a plain value for equality. More...

template<typename T , typename E , typename U >
constexpr bool	operator== (const U &lhs, const result< T, E > &rhs)
	Compares a result with a plain value for equality. More...

template<typename T , typename E >
constexpr void	swap (result< T, E > &a, result< T, E > &b) CONDITIONALLY_NOEXCEPT
	Swaps two result instances. More...

template<typename T , typename... Args>
constexpr result< T, never >	ok (Args &&... args)
	Creates an ok valued result, constructed in place. More...

template<typename T , typename U , typename... Args>
constexpr result< T, never >	ok (std::initializer_list< U > ilist, Args &&... args)
	Creates an ok valued result, constructed in place. More...

template<typename E , typename... Args>
constexpr result< never, E >	error (Args &&... args)
	Creates an error valued result, constructed in place. More...

template<typename E , typename U , typename... Args>
constexpr result< never, E >	error (std::initializer_list< U > ilist, Args &&... args)
	Creates an error valued result, constructed in place. More...

Related Functions inherited from variant< T, E >
constexpr REFERENCE	get (variant< T... > &v)
	Gets a variant alternative by index. More...

constexpr CONST_REFERENCE	get (const variant< T... > &v)
	Gets a variant alternative by index. More...

constexpr RVALUE_REFERENCE	get (variant< T... > &&v)
	Gets a variant alternative by index. More...

constexpr CONST_RVALUE_REFERENCE	get (const variant< T... > &&v)
	Gets a variant alternative by index. More...

constexpr REFERENCE	get (variant< U... > &v)
	Gets a variant alternative by type. More...

constexpr CONST_REFERENCE	get (const variant< U... > &v)
	Gets a variant alternative by type. More...

constexpr RVALUE_REFERENCE	get (variant< U... > &&v)
	Gets a variant alternative by type. More...

constexpr CONST_RVALUE_REFERENCE	get (const variant< U... > &&v)
	Gets a variant alternative by type. More...

constexpr POINTER	get_if (variant< T... > &v) noexcept
	Gets a variant alternative pointer by index if the variant holds it. More...

constexpr CONST_POINTER	get_if (const variant< T... > &v) noexcept
	Gets a variant alternative pointer by index if the variant holds it. More...

constexpr POINTER	get_if (variant< U... > &v) noexcept
	Gets a variant alternative pointer by type if the variant holds it. More...

constexpr CONST_POINTER	get_if (const variant< U... > &v) noexcept
	Gets a variant alternative pointer by type if the variant holds it. More...

constexpr bool	holds_alternative (const variant< U... > &v) noexcept
	Checks if a variant contains a particular alternative. More...

constexpr DEDUCED	visit (V &&visitor)
	Calls a visitor callable with the contained variant alternatives. More...

constexpr DEDUCED	visit (V &&visitor, T0 &&var0, TN &&... varn)
	Calls a visitor callable with the contained variant alternatives. More...

constexpr void	swap (variant< T... > &a, variant< T... > &b) CONDITIONALLY_NOEXCEPT
	Swaps two variant instances. More...

Detailed Description

template<typename T, typename E>
class sumty::result< T, E >

Type that contains an ok value, or an error.

result is a reimplementation of std::expected with several improvements. The key difference is that references (lvalue and rvalue) are can be used for both the value type and the error type, and void can be used for the error type (std::expected already allows void for the value type).

Internally, result<T, E> is represented as a variant<T, E>. Thus, result benefits from the size optimizations implemented by variant (see variant documentation for details). A couple special case result size examples are shown in the example below.

struct my_error {}; // NOTE: empty type
 
assert(sizeof(result<void, my_error>) == sizeof(bool));
 
assert(sizeof(result<int&, my_error>) == sizeof(int*));

In practice, the benefit of result over std::expected is that result can be used in more places, especially with generic code. A generic function (function template) that wants to be able to return a value of any type, but also allow that return value to instead communicate an error on failure can simply return a result<T, E>, where T is now allowed to be a reference or even void (and so is E, for that matter).

struct negative_number_error {};
 
// If value is negative, returns a negative_number_error. Otherwise,
// invokes func with the value as an argument and returns the result,
// even if the result is void or a reference.
template <typename F>
result<std::invoke_result_t<F>, negative_number_error>
call_if_non_negative(int value, F&& func) {
    if (value < 0) {
        return error<negative_number_error>();
    }
    // sumty::invoke needed to handle `void` return type
    return invoke(std::forward<F>(func), value);
}

The power of result is also enhanced when used in combination with error_set. error_set makes it easy to represent a set of different error possibilities of different types in a single value, and simplifies error propagation when used with result. See the documentation of error_set for more details and examples.

Constructor & Destructor Documentation

◆ result() [1/12]

constexpr result ( )

constexpr

Default constructor.

Initializes the result with a default constructed ok value.

Example

result<int, std::string> res{};
 
assert(res.has_value());
 
assert(*res == 0);

◆ result() [2/12]

constexpr result ( const result< T, E > & )

constexpr

Copy constructor.

If the source result has an ok value, the new result is initialized with a copy constructed ok value. If the source result has an error value, the new result is initialized with a copy constructed error.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
result<int, std::string> res1_copy{res1};
result<int, std::string> res2_copy{res2};
 
assert(res1_copy.has_value());
assert(*res1_copy == 42);
 
assert(!res2_copy.has_value());
assert(res2_copy.error() == "oh no");

◆ result() [3/12]

constexpr result ( result< T, E > && )

constexpr

Move constructor.

If the source result has an ok value, the new result is initialized with a move constructed ok value. If the source result has an error value, the new result is initialized with a move constructed error.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
result<int, std::string> res1_copy{std::move(res1)};
result<int, std::string> res2_copy{std::move(res2)};
 
assert(res1_copy.has_value());
assert(*res1_copy == 42);
 
assert(!res2_copy.has_value());
assert(res2_copy.error() == "oh no");

◆ result() [4/12]

constexpr CONDITONALLY_EXPLICIT result	(	[[maybe_unused] ] std::in_place_t	inplace,
		Args &&...	args
	)

inlineconstexpr

Emplacement constructor.

The result is initialized such that an ok value is constructed in place from the forwarded arguments.

This constructor is explicit if inplace is the only argument.

Example

result<std::string, std::string> res{std::in_place, 5, 'a'};
 
assert(res.has_value());
 
assert(*res == "aaaaa");

◆ result() [5/12]

constexpr result	(	[[maybe_unused] ] std::in_place_t	inplace,
		std::initializer_list< U >	init,
		Args &&...	args
	)

inlineconstexpr

Emplacement constructor with initializer list.

The result is initialized such that an ok value is constructed in place from the forwarded arguments.

Example

result<std::vector<int>, std::string> res{
        std::in_place, {1, 2, 3, 4, 5}};
 
assert(res.has_value());
 
assert(res->size() == 5);

◆ result() [6/12]

constexpr CONDITIONALLY_EXPLICIT result	(	std::in_place_index_t< 0 >	inplace,
		Args &&...	args
	)

inlineconstexpr

Emplacement constructor.

The result is initialized such that an ok value is constructed in place from the forwarded arguments.

This constructor is explicit if inplace is the only argument.

Example

result<std::string, std::string> res{std::in_place_index<0>, 5, 'a'};
 
assert(res.has_value());
 
assert(*res == "aaaaa");

◆ result() [7/12]

constexpr result	(	std::in_place_index_t< 0 >	inplace,
		std::initializer_list< U >	init,
		Args &&...	args
	)

inlineconstexpr

Emplacement constructor with initializer list.

The result is initialized such that an ok value is constructed in place from the forwarded arguments.

Example

result<std::vector<int>, std::string> res{
        std::in_place_index<0>, {1, 2, 3, 4, 5}};
 
assert(res.has_value());
 
assert(res->size() == 5);

◆ result() [8/12]

constexpr CONDITONALLY_EXPLICIT result	(	in_place_error_t	inplace,
		Args &&...	args
	)

inlineconstexpr

Error emplacement constructor.

The result is initialized such that an error value is constructed in place from the forwarded arguments.

Example

result<void, std::string> res{in_place_error, 5, 'a'};
 
assert(!res.has_value());
 
assert(res.error() == "aaaaa");

◆ result() [9/12]

constexpr result	(	in_place_error_t	inplace,
		std::initializer_list< U >	init,
		Args &&...	args
	)

inlineconstexpr

Error emplacement constructor with initializer list.

The result is initialized such that an error value is constructed in place from the forwarded arguments.

Example

result<void, std::vector<int>> res{in_place_error, {1, 2, 3, 4, 5}};
 
assert(!res.has_value());
 
assert(res.error().size() == 5);

◆ result() [10/12]

constexpr CONDITIONALLY_EXPLICIT result ( U && value )

inlineconstexpr

Forwarding constructor.

The result is initialized such that it contains an ok value that is constructed in place from the forwarded value.

This constructor only participates in overload resolution if the ok value is constructible from the forwarded value, the forwarded value is not of type std::in_place_t, sumty::in_place_t, std::in_place_index_t<0>, sumty::in_place_index_t<0>, std::in_place_index_t<1>, sumty::in_place_index_t<1>, or sumty::in_place_error_t, and either the ok value type is a scalar or the forwarded value is not a result instance.

This constructor is explicit if the forwarded value is not implicitly convertible to T.

Example

float value = 3.14;
 
result<int, std::string> res{value};
 
assert(res.has_value());
 
assert(*res == 3);

◆ result() [11/12]

constexpr CONDITIONALLY_EXPLICIT result ( const result< U, V > & other )

inlineconstexpr

Converting copy constructor.

This constructor converts a result with one pair of ok and error types into a

Returns: of a different pair of ok and error types. This constructor behaves much like the copy constructor, except that a type conversion may occur.

This constructor only particpates in overload resolution if the ok type T of the destination result is constructible from the ok type U of the source result, and the error type E of the destiantion result is constructible from the error type V of the source result.

This constructor is explicit if either U or V is not implicitly convertible to T or E, respectively.

Example

result<float, const char*> res1{3.14};
result<float, const char*> res2{in_place_error, "oh no"};
 
result<int, std::string> res3{res1};
result<int, std::string> res4{res2};
 
assert(res3.has_value());
assert(*res3 == 3);
 
assert(!res4.has_value());
assert(res4.error() == "oh no");

◆ result() [12/12]

constexpr CONDITIONALLY_EXPLICIT result ( result< U, V > && other )

inlineconstexpr

Converting move constructor.

This constructor converts a result with one pair of ok and error types into a

Returns: of a different pair of ok and error types. This constructor behaves much like the move constructor, except that a type conversion may occur.

This constructor only particpates in overload resolution if the ok type T of the destination result is constructible from the moved ok type U of the source result, and the error type E of the destiantion result is constructible from the move error type V of the source result.

This constructor is explicit if either U or V is not implicitly convertible to T or E, respectively.

Example

result<float, const char*> res1{3.14};
result<float, const char*> res2{in_place_error, "oh no"};
 
result<int, std::string> res3{std::move(res1)};
result<int, std::string> res4{std::move(res2)};
 
assert(res3.has_value());
assert(*res3 == 3);
 
assert(!res4.has_value());
assert(res4.error() == "oh no");

◆ ~result()

constexpr ~result ( )

constexpr

Destructor.

Destroys the contained value in place.

The desctructor is noexcept if both T and E are nothrow destructible.

Member Function Documentation

◆ and_then() [1/4]

constexpr auto and_then ( F && f ) &

inlineconstexpr

Applies a callable to the contents of a result.

If the result contains an ok value, the value is passed into the callable, and the result of invoking the callable is returned from this function. If the result contains an error, the callable is not invoked, and a copy of the error is returned.

This function only participates in overload resultion if the result of invoking the callable is a result.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{-42};
result<int, std::string> res3{in_place_error, "oh no"};
 
auto callable = [](int value) -> result<unsigned int, const char*> {
    if (value < 0) {
        return error<const char*>("negaive value");
    } else {
        return static_cast<unsigned int>(value);
    }
};
 
auto res1_new = res1.and_then(callable);
auto res2_new = res2.and_then(callable);
auto res3_new = res3.and_then(callable);
 
assert(res1_new.is_ok());
assert(*res1_new == 42);
 
assert(res2_new.is_error());
assert(res2_new.error() == "negative value");
 
assert(res3_new.is_error());
assert(res3_new.error() == "oh no");

◆ and_then() [2/4]

constexpr auto and_then ( F && f ) &&

inlineconstexpr

Applies a callable to the contents of a result.

If the result contains an ok value, the value is passed into the callable, and the result of invoking the callable is returned from this function. If the result contains an error, the callable is not invoked, the error is returned.

This function only participates in overload resultion if the result of invoking the callable is a result.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{-42};
result<int, std::string> res3{in_place_error, "oh no"};
 
auto callable = [](int value) -> result<unsigned int, const char*> {
    if (value < 0) {
        return error<const char*>("negaive value");
    } else {
        return static_cast<unsigned int>(value);
    }
};
 
auto res1_new = std::move(res1).and_then(callable);
auto res2_new = std::move(res2).and_then(callable);
auto res3_new = std::move(res3).and_then(callable);
 
assert(res1_new.is_ok());
assert(*res1_new == 42);
 
assert(res2_new.is_error());
assert(res2_new.error() == "negative value");
 
assert(res3_new.is_error());
assert(res3_new.error() == "oh no");

◆ and_then() [3/4]

constexpr auto and_then ( F && f ) const &

inlineconstexpr

Applies a callable to the contents of a result.

If the result contains an ok value, the value is passed into the callable, and the result of invoking the callable is returned from this function. If the result contains an error, the callable is not invoked, and a copy of the error is returned.

This function only participates in overload resultion if the result of invoking the callable is a result.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{-42};
const result<int, std::string> res3{in_place_error, "oh no"};
 
auto callable = [](int value) -> result<unsigned int, const char*> {
    if (value < 0) {
        return error<const char*>("negaive value");
    } else {
        return static_cast<unsigned int>(value);
    }
};
 
auto res1_new = res1.and_then(callable);
auto res2_new = res2.and_then(callable);
auto res3_new = res3.and_then(callable);
 
assert(res1_new.is_ok());
assert(*res1_new == 42);
 
assert(res2_new.is_error());
assert(res2_new.error() == "negative value");
 
assert(res3_new.is_error());
assert(res3_new.error() == "oh no");

◆ and_then() [4/4]

constexpr auto and_then ( F && f ) const &&

inlineconstexpr

Applies a callable to the contents of a result.

If the result contains an ok value, the value is passed into the callable, and the result of invoking the callable is returned from this function. If the result contains an error, the callable is not invoked, the error is returned.

This function only participates in overload resultion if the result of invoking the callable is a result.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{-42};
const result<int, std::string> res3{in_place_error, "oh no"};
 
auto callable = [](int value) -> result<unsigned int, const char*> {
    if (value < 0) {
        return error<const char*>("negaive value");
    } else {
        return static_cast<unsigned int>(value);
    }
};
 
auto res1_new = std::move(res1).and_then(callable);
auto res2_new = std::move(res2).and_then(callable);
auto res3_new = std::move(res3).and_then(callable);
 
assert(res1_new.is_ok());
assert(*res1_new == 42);
 
assert(res2_new.is_error());
assert(res2_new.error() == "negative value");
 
assert(res3_new.is_error());
assert(res3_new.error() == "oh no");

◆ cref()

constexpr result<const_reference, error_const_reference> cref ( ) const

inlineconstexprnoexcept

Converts a result reference into a result of references.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
result<const int&, const std::string&> res1_ref = res1.cref();
result<const int&, const std::string&> ref2_ref = res2.cref();
 
assert(res1_ref.is_ok());
assert(&*res1_ref == &*res1);
 
assert(res2_ref.is_error());
assert(&res2_ref.error() == &res2.error());

◆ emplace() [1/2]

constexpr reference emplace ( Args &&... args )

inlineconstexpr

Constructs a new ok value in place into the result.

The value previously contained in the result, ok or error, is destroyed in place. The new ok value is then constructed in place as if by placement new.

Example

result<std::string, int> res1{in_place_error, 42};
result<std::string, int> res2{""};
 
res1.emplace(5, 'a');
res2.emplace(5, 'a');
 
assert(res1.is_ok());
assert(*res1 == "aaaaa");
 
assert(res2.is_ok());
assert(*res2 == "aaaaa");

◆ emplace() [2/2]

constexpr reference emplace	(	std::initializer_list< U >	ilist,
		Args &&...	args
	)

inlineconstexpr

Constructs a new ok value in place into the result.

The value previously contained in the result, ok or error, is destroyed in place. The new ok value is then constructed in place as if by placement new.

Example

result<std::vector<int>, int> res1{in_place_error, 42};
result<std::vector<int>, int> res2{};
 
res1.emplace({1, 2, 3, 4, 5});
res2.emplace({1, 2, 3, 4, 5});
 
assert(res1.is_ok());
assert(res1->size() == 5);
 
assert(res2.is_ok());
assert(res2->size() == 5);

◆ emplace_error() [1/2]

constexpr error_reference emplace_error ( Args &&... args )

inlineconstexpr

Constructs a new error value in place into the result.

The value previously contained in the result, ok or error, is destroyed in place. The new error value is then constructed in place as if by placement new.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, ""};
 
res1.emplace_error(5, 'a');
res2.emplace_error(5, 'a');
 
assert(res1.is_error());
assert(res1.error() == "aaaaa");
 
assert(res2.is_error());
assert(res2.error() == "aaaaa");

◆ emplace_error() [2/2]

constexpr error_reference emplace_error	(	std::initializer_list< U >	ilist,
		Args &&...	args
	)

inlineconstexpr

Constructs a new error value in place into the result.

The value previously contained in the result, ok or error, is destroyed in place. The new error value is then constructed in place as if by placement new.

Example

result<int, std::vector<int>> res1{42};
result<int, std::vector<int>> res2{in_place_error};
 
res1.emplace_error({1, 2, 3, 4, 5});
res2.emplace_error({1, 2, 3, 4, 5});
 
assert(res1.is_error());
assert(res1.error().size() == 5);
 
assert(res2.is_error());
assert(res2.error().size() == 5);

◆ error() [1/4]

constexpr error_rvalue_reference error ( ) &&

inlineconstexpr

Accesses the error value contained in the result.

This function does not check if the result contains an ok value. Use of this function when the result contains an error results in undefined behavior.

Example

result<int, std::string> res{in_place_error, "oh no"};
 
assert(std::move(res).error() == "oh no");

◆ error() [2/4]

constexpr error_reference error ( ) &

inlineconstexprnoexcept

Accesses the error value contained in the result.

This function does not check if the result contains an ok value. Use of this function when the result contains an error results in undefined behavior.

Example

result<int, std::string> res{in_place_error, "oh no"};
 
assert(res.error() == "oh no");

◆ error() [3/4]

constexpr error_const_rvalue_reference error ( ) const &&

inlineconstexpr

Accesses the error value contained in the result.

This function does not check if the result contains an ok value. Use of this function when the result contains an error results in undefined behavior.

Example

const result<int, std::string> res{in_place_error, "oh no"};
 
assert(std::move(res).error() == "oh no");

◆ error() [4/4]

constexpr error_const_reference error ( ) const &

inlineconstexprnoexcept

Accesses the error value contained in the result.

This function does not check if the result contains an ok value. Use of this function when the result contains an error results in undefined behavior.

Example

const result<int, std::string> res{in_place_error, "oh no"};
 
assert(res.error() == "oh no");

◆ error_or_none() [1/2]

constexpr option<E> error_or_none ( ) &&

inlineconstexpr

Discards ok value and converts into an option.

If the result contains an error value, that value is returned wrapped in an option. If the result contains an ok value, none is returned.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
option<std::string> opt1 = res1.error_or_none();
option<std::string> opt2 = res2.error_or_none();
 
assert(opt1.is_none());
 
assert(opt2.is_some());
assert(*opt2 == "oh no");

◆ error_or_none() [2/2]

constexpr option<E> error_or_none ( ) const &

inlineconstexprnoexcept

Discards ok value and converts into an option.

If the result contains an error value, a copy of that value is returned wrapped in an option. If the result contains an ok value, none is returned.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
option<std::string> opt1 = res1.error_or_none();
option<std::string> opt2 = res2.error_or_none();
 
assert(opt1.is_none());
 
assert(opt2.is_some());
assert(*opt2 == "oh no");

◆ flatten() [1/2]

constexpr auto flatten ( ) &&

inlineconstexpr

Converts result<result<T, E1>, E2> into result<T, E3>

If the outer result contains an error, that error is returned. If the outer result contains an ok value, and the inner result contains an error, that inner error is returned. If the outer result contains an ok value and the inner result contains an ok value, that inner ok value is returned.

If the outer result and the inner result have different error types, the returned result will be one of these two types based on the following priority rules:

If the outer error type is void, use the inner error type
Else, if the inner error type is void, use the outer error type
Else, if the outer error type is constructible from the inner error type, use the outer error type.
Else, if the inner error type is constructible from the outer error type, use the inner error type.

Note that only one level of result is removed. For example, a result<result<result<T, E>, E>, E> will flatten to a result<result<T, E>, E>.

Example

result<result<int, const char*>, std::string> res1{in_place, 42};
result<result<int, const char*>, std::string> res2{
        in_place, in_place_error, "oh no"};
result<result<int, const char*>, std::string> res3{
        in_place_error, "oh no"};
 
result<int, std::string> res1_flat = std::move(res1).flatten();
result<int, std::string> res2_flat = std::move(res2).flatten();
result<int, std::string> res3_flat = std::move(res3).flatten();
 
assert(res1_flat.is_ok());
assert(*res1_flat == 42);
 
assert(res2_flat.is_error());
assert(res2_flat.error() == "oh no");
 
assert(res3_flat.is_error());
assert(res3_flat.error() == "oh no");

◆ flatten() [2/2]

constexpr auto flatten ( ) const &

inlineconstexpr

Converts result<result<T, E1>, E2> into result<T, E3>

If the outer result contains an error, a copy of that error is returned. If the outer result contains an ok value, and the inner result contains an error, a copy of that inner error is returned. If the outer result contains an ok value and the inner result contains an ok value, a copy of that inner ok value is returned.

If the outer result and the inner result have different error types, the returned result will be one of these two types based on the following priority rules:

If the outer error type is void, use the inner error type
Else, if the inner error type is void, use the outer error type
Else, if the outer error type is constructible from the inner error type, use the outer error type.
Else, if the inner error type is constructible from the outer error type, use the inner error type.

Note that only one level of result is removed. For example, a result<result<result<T, E>, E>, E> will flatten to a result<result<T, E>, E>.

Example

result<result<int, const char*>, std::string> res1{in_place, 42};
result<result<int, const char*>, std::string> res2{
        in_place, in_place_error, "oh no"};
result<result<int, const char*>, std::string> res3{
        in_place_error, "oh no"};
 
result<int, std::string> res1_flat = res1.flatten();
result<int, std::string> res2_flat = res2.flatten();
result<int, std::string> res3_flat = res3.flatten();
 
assert(res1_flat.is_ok());
assert(*res1_flat == 42);
 
assert(res2_flat.is_error());
assert(res2_flat.error() == "oh no");
 
assert(res3_flat.is_error());
assert(res3_flat.error() == "oh no");

◆ flatten_all() [1/2]

constexpr auto flatten_all ( ) &&

inlineconstexpr

Converts nested result types into a single result.

Like flatten, this function removes nested layers of result, such as converting result<result<T, E>, E> into result<T, E>. However, unlike flatten, this function removes all layers of nesting and works for unnested result types. For example, result<result<result<T, E>, E, E> is converted directly to result<T, E>, and for result<T, E>, where T is not a result type, no layers of result are removed.

Example

using nested_result_t =
    result<result<result<int, std::string>, std::string, std::string>;
 
nested_result_t res1{in_place, in_place, in_place, 42};
nested_result_t res2{in_place_error, "oh no"};
nested_result_t res3{in_place, in_place_error, "oh no"};
nested_result_t res4{in_place, in_place, in_place_error, "oh no"};
 
result<int, std::string> res1_flat = std::move(res1).flatten_all();
result<int, std::string> res2_flat = std::move(res2).flatten_all();
result<int, std::string> res3_flat = std::move(res3).flatten_all();
result<int, std::string> res4_flat = std::move(res4).flatten_all();
 
assert(res1_flat.is_ok());
assert(*res1_flat == 42);
 
assert(res2_flat.is_error());
assert(res2_flat.error() == "oh no");
 
assert(res3_flat.is_error());
assert(res3_flat.error() == "oh no");
 
assert(res3_flat.is_error());
assert(res3_flat.error() == "oh no");

◆ flatten_all() [2/2]

constexpr auto flatten_all ( ) const &

inlineconstexpr

Converts nested result types into a single result.

Like flatten, this function removes nested layers of result, such as converting result<result<T, E>, E> into result<T, E>. However, unlike flatten, this function removes all layers of nesting and works for unnested result types. For example, result<result<result<T, E>, E, E> is converted directly to result<T, E>, and for result<T, E>, where T is not a result type, no layers of result are removed.

Example

using nested_result_t =
    result<result<result<int, std::string>, std::string, std::string>;
 
nested_result_t res1{in_place, in_place, in_place, 42};
nested_result_t res2{in_place_error, "oh no"};
nested_result_t res3{in_place, in_place_error, "oh no"};
nested_result_t res4{in_place, in_place, in_place_error, "oh no"};
 
result<int, std::string> res1_flat = res1.flatten_all();
result<int, std::string> res2_flat = res2.flatten_all();
result<int, std::string> res3_flat = res3.flatten_all();
result<int, std::string> res4_flat = res4.flatten_all();
 
assert(res1_flat.is_ok());
assert(*res1_flat == 42);
 
assert(res2_flat.is_error());
assert(res2_flat.error() == "oh no");
 
assert(res3_flat.is_error());
assert(res3_flat.error() == "oh no");
 
assert(res3_flat.is_error());
assert(res3_flat.error() == "oh no");

◆ has_value()

constexpr bool has_value ( ) const

inlineconstexprnoexcept

Returns true if the result contains an ok value.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{error<std::string>("oh no")};
 
assert(res1.has_value());
assert(!res1.has_value());

◆ invert() [1/2]

constexpr result<E, T> invert ( ) &&

inlineconstexpr

Swaps the ok and error types of a result.

If the result contains an ok value, a copy of the ok value will be returned as an error. If the result contains an error value, the error value will be returned as an ok value.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
result<std::string, int> res1_inv = std::move(res1).invert();
result<std::string, int> res2_inv = std::move(res2).invert();
 
assert(res1_inv.is_error());
assert(res1_inv.error() == 42);
 
assert(res2_inv.is_ok());
assert(*res2_inv == "oh no");

◆ invert() [2/2]

constexpr result<E, T> invert ( ) const &

inlineconstexpr

Swaps the ok and error types of a result.

If the result contains an ok value, a copy of the ok value will be returned as an error. If the result contains an error value, the error value will be returned as an ok value.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
result<std::string, int> res1_inv = res1.invert();
result<std::string, int> res2_inv = res2.invert();
 
assert(res1_inv.is_error());
assert(res1_inv.error() == 42);
 
assert(res2_inv.is_ok());
assert(*res2_inv == "oh no");

◆ is_error()

constexpr bool is_error ( ) const

inlineconstexprnoexcept

Returns true if the result contains an error value.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{error<std::string>("oh no")};
 
assert(!res1.is_error());
assert(res1.is_error());

◆ is_ok()

constexpr bool is_ok ( ) const

inlineconstexprnoexcept

Returns true if the result contains an ok value.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{error<std::string>("oh no")};
 
assert(res1.is_ok());
assert(!res1.is_ok());

◆ map() [1/4]

constexpr auto map ( F && f ) &

inlineconstexpr

Perforams a transformation on the ok value of a result.

If the result contains an ok value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the ok value of a new result, where ok type of the new result is the exact type returned from the callable. If the result contains an error value, a copy of the error is returned.

Note that this function is idential to transform, but the name map is the more typical name of this monadic operation outside of C++.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
auto res1_mapped = res1.map([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = res2.map([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_error());
assert(res1_mapped.error() == "oh no");
 
assert(res2_mapped.is_ok());
assert(*res2_mapped == "42");

◆ map() [2/4]

constexpr auto map ( F && f ) &&

inlineconstexpr

Perforams a transformation on the ok value of a result.

If the result contains an ok value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the ok value of a new result, where ok type of the new result is the exact type returned from the callable. If the result contains an error value, the error is returned.

Note that this function is idential to transform, but the name map is the more typical name of this monadic operation outside of C++.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
auto res1_mapped = std::move(res1).map([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = std::move(res2).map([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_error());
assert(res1_mapped.error() == "oh no");
 
assert(res2_mapped.is_ok());
assert(*res2_mapped == "42");

◆ map() [3/4]

constexpr auto map ( F && f ) const &

inlineconstexpr

Perforams a transformation on the ok value of a result.

If the result contains an ok value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the ok value of a new result, where ok type of the new result is the exact type returned from the callable. If the result contains an error value, a copy of the error is returned.

Note that this function is idential to transform, but the name map is the more typical name of this monadic operation outside of C++.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{in_place_error, "oh no"};
 
auto res1_mapped = res1.map([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = res2.map([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_error());
assert(res1_mapped.error() == "oh no");
 
assert(res2_mapped.is_ok());
assert(*res2_mapped == "42");

◆ map() [4/4]

constexpr auto map ( F && f ) const &&

inlineconstexpr

Perforams a transformation on the ok value of a result.

If the result contains an ok value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the ok value of a new result, where ok type of the new result is the exact type returned from the callable. If the result contains an error value, the error is returned.

Note that this function is idential to transform, but the name map is the more typical name of this monadic operation outside of C++.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{in_place_error, "oh no"};
 
auto res1_mapped = std::move(res1).map([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = std::move(res2).map([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_error());
assert(res1_mapped.error() == "oh no");
 
assert(res2_mapped.is_ok());
assert(*res2_mapped == "42");

◆ map_error() [1/4]

constexpr auto map_error ( F && f ) &

inlineconstexpr

Perforams a transformation on the error value of a result.

If the result contains an error value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the error value of a new result, where the error type of the new result is the exact type returned from the callable. If the result contains an ok value, a copy of the ok value is returned.

Note that this function is identical to transform_error, but the name map_error is more typical for this sort of monadic operation outside of C++.

Example

result<void, int> res1{};
result<void, int> res2{in_place_error, 42};
 
auto res1_mapped = res1.map_error([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = res2.map_error([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_ok());
 
assert(res2_mapped.is_error());
assert(*res2_mapped == "42");

◆ map_error() [2/4]

constexpr auto map_error ( F && f ) &&

inlineconstexpr

Perforams a transformation on the error value of a result.

If the result contains an error value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the error value of a new result, where the error type of the new result is the exact type returned from the callable. If the result contains an ok value, the ok value is returned.

Note that this function is identical to transform_error, but the name map_error is more typical for this sort of monadic operation outside of C++.

Example

result<void, int> res1{};
result<void, int> res2{in_place_error, 42};
 
auto res1_mapped = std::move(res1).map_error([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = std::move(res2).map_error([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_ok());
 
assert(res2_mapped.is_error());
assert(*res2_mapped == "42");

◆ map_error() [3/4]

constexpr auto map_error ( F && f ) const &

inlineconstexpr

Perforams a transformation on the error value of a result.

If the result contains an error value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the error value of a new result, where the error type of the new result is the exact type returned from the callable. If the result contains an ok value, a copy of the ok value is returned.

Note that this function is identical to transform_error, but the name map_error is more typical for this sort of monadic operation outside of C++.

Example

const result<void, int> res1{};
const result<void, int> res2{in_place_error, 42};
 
auto res1_mapped = res1.map_error([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = res2.map_error([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_ok());
 
assert(res2_mapped.is_error());
assert(*res2_mapped == "42");

◆ map_error() [4/4]

constexpr auto map_error ( F && f ) const &&

inlineconstexpr

Perforams a transformation on the error value of a result.

If the result contains an error value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the error value of a new result, where the error type of the new result is the exact type returned from the callable. If the result contains an ok value, the ok value is returned.

Note that this function is identical to transform_error, but the name map_error is more typical for this sort of monadic operation outside of C++.

Example

result<void, int> res1{};
result<void, int> res2{in_place_error, 42};
 
auto res1_mapped = std::move(res1).map_error([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = std::move(res2).map_error([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_ok());
 
assert(res2_mapped.is_error());
assert(*res2_mapped == "42");

◆ ok() [1/4]

constexpr reference ok ( ) &

inlineconstexpr

Accesses the ok value contained in the result.

This function first checks if the result contains an ok value before attempting to access the value. If the result contains an error, then this function throws an exception.

Example

result<int, std::string> res{42};
 
assert(res.ok() == 42);

Exceptions

bad_result_access Thrown if the result contains an error

◆ ok() [2/4]

constexpr rvalue_reference ok ( ) &&

inlineconstexpr

Accesses the ok value contained in the result.

This function first checks if the result contains an ok value before attempting to access the value. If the result contains an error, then this function throws an exception.

Example

result<int, std::string> res{42};
 
assert(std::move(res).ok() == 42);

Exceptions

bad_result_access Thrown if the result contains an error

◆ ok() [3/4]

constexpr const_reference ok ( ) const &

inlineconstexpr

Accesses the ok value contained in the result.

This function first checks if the result contains an ok value before attempting to access the value. If the result contains an error, then this function throws an exception.

Example

const result<int, std::string> res{42};
 
assert(res.ok() == 42);

Exceptions

bad_result_access Thrown if the result contains an error

◆ ok() [4/4]

constexpr rvalue_reference ok ( ) const &&

inlineconstexpr

Accesses the ok value contained in the result.

This function first checks if the result contains an ok value before attempting to access the value. If the result contains an error, then this function throws an exception.

Example

const result<int, std::string> res{42};
 
assert(std::move(res).ok() == 42);

Exceptions

bad_result_access Thrown if the result contains an error

◆ ok_or() [1/2]

constexpr value_type ok_or ( U && default_value ) &&

inlineconstexpr

Gets the ok value, or a default if the result is an error.

If the result contains an ok value, that ok value is returned. If the result contains an error value, the provided default value is forwarded, cast, and returned as by the following: static_cast<T>(std::forward<U>(default_value)).

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(std::move(res1).ok_or(0) == 42);
 
assert(std::move(res2).ok_or(0) == 0);

◆ ok_or() [2/2]

constexpr value_type ok_or ( U && default_value ) const &

inlineconstexpr

Gets the ok value, or a default if the result is an error.

If the result contains an ok value, a copy of that ok value is returned. If the result contains an error value, the provided default value is forwarded, cast, and returned as by the following: static_cast<T>(std::forward<U>(default_value)).

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(res1.ok_or(0) == 42);
 
assert(res2.ok_or(0) == 0);

◆ ok_or_else() [1/2]

constexpr value_type ok_or_else ( F && f ) &&

inlineconstexpr

Gets the ok value, or returns the result of a callable.

If the result contains an ok value, a copy of that ok value is returned. If the result contains an error, the provided callable is invoked and the result is cast and returned, as if by: static_cast<T>(std::invoke(std::forward<F>(f))).

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(std::move(res1).ok_or_else([] { return 0; }) == 42);
 
assert(std::move(res2).ok_or_else({] { return 0; }) == 0);

◆ ok_or_else() [2/2]

constexpr value_type ok_or_else ( F && f ) const &

inlineconstexpr

Gets the ok value, or returns the result of a callable.

If the result contains an ok value, a copy of that ok value is returned. If the result contains an error, the provided callable is invoked and the result is cast and returned, as if by: static_cast<T>(std::invoke(std::forward<F>(f))).

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(res1.ok_or_else([] { return 0; }) == 42);
 
assert(res2.ok_or_else({] { return 0; }) == 0);

◆ ok_or_none() [1/2]

constexpr option<T> ok_or_none ( ) &&

inlineconstexpr

Discards error values and converts into an option.

If the result contains an ok value, that value is returned wrapped in an option. If the result contains an error, none is returned.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
option<int> opt1 = std::move(res1).ok_or_none();
option<int> opt2 = std::move(res2).ok_or_none();
 
assert(opt1.is_some());
assert(*opt1 == 42);
 
assert(opt2.is_none());

◆ ok_or_none() [2/2]

constexpr option<T> ok_or_none ( ) const &

inlineconstexprnoexcept

Discards error values and converts into an option.

If the result contains an ok value, a copy of that value is returned wrapped in an option. If the result contains an error, none is returned.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
option<int> opt1 = res1.ok_or_none();
option<int> opt2 = res2.ok_or_none();
 
assert(opt1.is_some());
assert(*opt1 == 42);
 
assert(opt2.is_none());

◆ operator bool()

constexpr operator bool ( ) const

inlineconstexprnoexcept

Implicit conversion to bool.

This implicit conversion allows a result to be used directly in a condition to check if the result contains an ok value.

Example

result<int, std::string> res1{42};
result<int, std::string> res2 = error<std::string>("oh no");
 
if (res1) {
    assert(*res1 == 42);
} else {
    assert(false);
}
 
if (res2) {
    assert(false);
} else {
    assert(res2.error() == "oh no");
}

◆ operator*() [1/4]

constexpr rvalue_reference operator* ( ) &&

inlineconstexpr

Accesses the ok value contained in the result.

This operator does not check if the result contains an ok value. Use of this operator when the result contains an error results in undefined behavior.

Example

result<int, std::string> res{42};
 
assert(*std::move(res) == 42);

◆ operator*() [2/4]

constexpr reference operator* ( ) &

inlineconstexprnoexcept

Accesses the ok value contained in the result.

This operator does not check if the result contains an ok value. Use of this operator when the result contains and error results in undefined behavior.

Example

result<int, std::string> res{42};
 
assert(*res == 42);

◆ operator*() [3/4]

constexpr const_rvalue_reference operator* ( ) const &&

inlineconstexpr

Accesses the ok value contained in the result.

This operator does not check if the result contains an ok value. Use of this operator when the result contains an error results in undefined behavior.

Example

const result<int, std::string> res{42};
 
assert(*std::move(res) == 42);

◆ operator*() [4/4]

constexpr const_reference operator* ( ) const &

inlineconstexprnoexcept

Accesses the ok value contained in the result.

This operator does not check if the result contains an ok value. Use of this operator when the result contains an error results in undefined behavior.

Example

const result<int, std::string> res{42};
 
assert(*res == 42);

◆ operator->() [1/2]

constexpr const_pointer operator-> ( ) const

inlineconstexprnoexcept

Accesses members of the ok value contained in the result.

This operator does not check if the result contains an ok value. Use of this operator when the result contains an error results in undefined behavior.

Example

const result<std::string, int> res{"hello"};
 
assert(res->size() == 5);

◆ operator->() [2/2]

constexpr pointer operator-> ( )

inlineconstexprnoexcept

Accesses members of the ok value contained in the result.

This operator does not check if the result contains an ok value. Use of this operator when the result contains an error results in undefined behavior.

Example

result<std::string, int> res{"hello"};
 
assert(res->size() == 5);

◆ operator=() [1/3]

constexpr result& operator= ( const result< T, E > & )

constexpr

Copy assignment operator.

The destination result is reassigned such that it will now contain a copy of the contained value of the source result, which may be either the ok type or the error type.

If both the source and destination contain the ok type, or both contain the error type, the values are copy assigned directly. Otherwise, the old value in the destination is destroyed and the new value is copy constructed.

This function is noexcept if both T and E are all of the following:

Nothrow copy assignable
Nothrow copy constructible
Nothrow destructible

Example

result<float, const char*> res1{3.14};
result<float, const char*> res2{in_place_error, "oh no"};
 
result<int, std::string> res3{};
result<int, std::string> res4{};
 
res3 = res1;
res4 = res2;
 
assert(res3.has_value());
assert(*res3 == 3);
 
assert(!res4.has_value());
assert(res4.error() == "oh no");

◆ operator=() [2/3]

constexpr result& operator= ( result< T, E > && )

constexpr

Move assignment operator.

The destination result is reassigned such that it will now contain the moved contained value of the source result, which may be either the ok type or the error type.

If both the source and destination contain the ok type, or both contain the error type, the values are move assigned directly. Otherwise, the old value in the destination is destroyed and the new value is move constructed.

This function is noexcept if both T and E are all of the following:

Nothrow move assignable
Nothrow move constructible
Nothrow destructible

Example

result<float, const char*> res1{3.14};
result<float, const char*> res2{in_place_error, "oh no"};
 
result<int, std::string> res3{};
result<int, std::string> res4{};
 
res3 = std::move(res1);
res4 = std::move(res2);
 
assert(res3.has_value());
assert(*res3 == 3);
 
assert(!res4.has_value());
assert(res4.error() == "oh no");

◆ operator=() [3/3]

constexpr result<T, E>& operator= ( U && value )

inlineconstexpr

Value assignment operator.

Sets the result to contain the forwarded ok value, converted to T. If the result already contains an ok value, the forwarded value is assigned directly to the contained value. Otherwise, the error type is destroyed, and the ok type is constructed from the forwarded value.

This function only participates in overload resolution if:

The source value is not a result
T is constructible from U
T is assignable from U

Example

result<int, std::string> res{};
 
res = 3.14;
 
assert(res.has_value());
assert(*res == 3);

◆ or_else() [1/2]

constexpr result or_else ( F && f ) &&

inlineconstexpr

Returns the result of invoking f if the result is an error.

If the result contains an ok value, the entire result is returned. If the result contains an error value, f is invoked with the error value as an argument, and the returned value from invoking f is returned from this function, converting to result<T, E> if necessary.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
auto res1_new = std::move(res1).or_else([]([[maybe_unused]] auto err) {
    return 0;
});
auto res2_new = std::move(res2).or_else([]([[maybe_unused]] auto err) {
    return 0;
});
 
assert(res1_new.is_ok());
assert(*res1_new == 42);
 
assert(res2_new.is_ok());
assert(*res2_new == 0);

◆ or_else() [2/2]

constexpr result or_else ( F && f ) const &

inlineconstexpr

Returns the result of invoking f if the result is an error.

If the result contains an ok value, a copy of the entire result is returned. If the result contains an error value, f is invoked with the error value as an argument, and the returned value from invoking f is returned from this function, converting to result<T, E> if necessary.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
auto res1_new = res1.or_else([]([[maybe_unused]] const auto& err) {
    return 0;
});
auto res2_new = res2.or_else([]([[maybe_unused]] const auto& err) {
    return 0;
});
 
assert(res1_new.is_ok());
assert(*res1_new == 42);
 
assert(res2_new.is_ok());
assert(*res2_new == 0);

◆ or_none() [1/2]

constexpr option<T> or_none ( ) &&

inlineconstexpr

Discards error values and converts into an option.

If the result contains an ok value, that value is returned wrapped in an option. If the result contains an error, none is returned.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
option<int> opt1 = std::move(res1).or_none();
option<int> opt2 = std::move(res2).or_none();
 
assert(opt1.is_some());
assert(*opt1 == 42);
 
assert(opt2.is_none());

◆ or_none() [2/2]

constexpr option<T> or_none ( ) const &

inlineconstexprnoexcept

Discards error values and converts into an option.

If the result contains an ok value, a copy of that value is returned wrapped in an option. If the result contains an error, none is returned.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
option<int> opt1 = res1.or_none();
option<int> opt2 = res2.or_none();
 
assert(opt1.is_some());
assert(*opt1 == 42);
 
assert(opt2.is_none());

◆ prop_error() [1/2]

constexpr result<never, E> prop_error ( ) &&

inlineconstexpr

Extracts the error in order to propagate it.

This function returns the error value by itself. This value can then be converted into a different result type for the purpose of propagating the error.

This function does not check if the result contains an ok value. Use of this function when the result contains an error results in undefined behavior.

Example

result<void, std::string> func() {
    result<int, std::string> res{in_place_error, "oh no"};
 
    return std::move(res).prop_error();
}

◆ prop_error() [2/2]

constexpr result<never, E> prop_error ( ) const &

inlineconstexpr

Extracts the error in order to propagate it.

This function returns the error value by itself. This value can then be converted into a different result type for the purpose of propagating the error.

This function does not check if the result contains an ok value. Use of this function when the result contains an error results in undefined behavior.

Example

result<void, std::string> func() {
    result<int, std::string> res{in_place_error, "oh no"};
 
    return res.prop_error();
}

◆ ref() [1/2]

constexpr result<const_reference, error_const_reference> ref ( ) const

inlineconstexprnoexcept

Converts a result reference into a result of references.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{in_place_error, "oh no"};
 
result<const int&, const std::string&> res1_ref = res1.ref();
result<const int&, const std::string&> ref2_ref = res2.ref();
 
assert(res1_ref.is_ok());
assert(&*res1_ref == &*res1);
 
assert(res2_ref.is_error());
assert(&res2_ref.error() == &res2.error());

◆ ref() [2/2]

constexpr result<reference, error_reference> ref ( )

inlineconstexprnoexcept

Converts a result reference into a result of references.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
result<int&, std::string&> res1_ref = res1.ref();
result<int&, std::string&> ref2_ref = res2.ref();
 
assert(res1_ref.is_ok());
assert(&*res1_ref == &*res1);
 
assert(res2_ref.is_error());
assert(&res2_ref.error() == &res2.error());

◆ swap()

constexpr void swap ( result< T, E > & other )

inlineconstexpr

Swaps two result instances.

If both result instances contain an ok value or both contain an error value, the values are swapped directly. If the two result instances do not contain the same kind of value, the values are moved out of the results temporarily, the old values are destroyed, and new values a move constructed in to the opposite result.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
res1.swap(res2);
 
assert(res1.is_error());
assert(res1.error() == "oh no");
 
assert(res2.is_ok());
assert(*res2 == 42);

◆ transform() [1/4]

constexpr auto transform ( F && f ) &

inlineconstexpr

Perforams a transformation on the ok value of a result.

If the result contains an ok value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the ok value of a new result, where ok type of the new result is the exact type returned from the callable. If the result contains an error value, a copy of the error is returned.

Note that this function is identical to map, but the name transform makes result able to be a drop in replacement for std::expected. map is the more typical name of this monadic operation outside of C++.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
auto res1_mapped = res1.transform([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = res2.transform([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_error());
assert(res1_mapped.error() == "oh no");
 
assert(res2_mapped.is_ok());
assert(*res2_mapped == "42");

◆ transform() [2/4]

constexpr auto transform ( F && f ) &&

inlineconstexpr

Perforams a transformation on the ok value of a result.

If the result contains an ok value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the ok value of a new result, where ok type of the new result is the exact type returned from the callable. If the result contains an error value, the error is returned.

Note that this function is identical to map, but the name transform makes result able to be a drop in replacement for std::expected. map is the more typical name of this monadic operation outside of C++.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
auto res1_mapped = std::move(res1).transform([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = std::move(res2).transform([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_error());
assert(res1_mapped.error() == "oh no");
 
assert(res2_mapped.is_ok());
assert(*res2_mapped == "42");

◆ transform() [3/4]

constexpr auto transform ( F && f ) const &

inlineconstexpr

Perforams a transformation on the ok value of a result.

If the result contains an ok value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the ok value of a new result, where ok type of the new result is the exact type returned from the callable. If the result contains an error value, a copy of the error is returned.

Note that this function is identical to map, but the name transform makes result able to be a drop in replacement for std::expected. map is the more typical name of this monadic operation outside of C++.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{in_place_error, "oh no"};
 
auto res1_mapped = res1.transform([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = res2.transform([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_error());
assert(res1_mapped.error() == "oh no");
 
assert(res2_mapped.is_ok());
assert(*res2_mapped == "42");

◆ transform() [4/4]

constexpr auto transform ( F && f ) const &&

inlineconstexpr

Perforams a transformation on the ok value of a result.

If the result contains an ok value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the ok value of a new result, where ok type of the new result is the exact type returned from the callable. If the result contains an error value, the error is returned.

Note that this function is identical to map, but the name transform makes result able to be a drop in replacement for std::expected. map is the more typical name of this monadic operation outside of C++.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{in_place_error, "oh no"};
 
auto res1_mapped = std::move(res1).transform([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = std::move(res2).transform([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_error());
assert(res1_mapped.error() == "oh no");
 
assert(res2_mapped.is_ok());
assert(*res2_mapped == "42");

◆ transform_error() [1/4]

constexpr auto transform_error ( F && f ) &

inlineconstexpr

Perforams a transformation on the error value of a result.

If the result contains an error value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the error value of a new result, where the error type of the new result is the exact type returned from the callable. If the result contains an ok value, a copy of the ok value is returned.

Note that this function is identical to map_error, but the name transform_error makes result able to be a drop in replacement for std::expected. map_error would be the more typical name of this monadic operation outside of C++.

Example

result<void, int> res1{};
result<void, int> res2{in_place_error, 42};
 
auto res1_mapped = res1.transform_error([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = res2.transform_error([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_ok());
 
assert(res2_mapped.is_error());
assert(*res2_mapped == "42");

◆ transform_error() [2/4]

constexpr auto transform_error ( F && f ) &&

inlineconstexpr

Perforams a transformation on the error value of a result.

If the result contains an error value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the error value of a new result, where the error type of the new result is the exact type returned from the callable. If the result contains an ok value, the ok value is returned.

Note that this function is identical to map_error, but the name transform_error makes result able to be a drop in replacement for std::expected. map_error would be the more typical name of this monadic operation outside of C++.

Example

result<void, int> res1{};
result<void, int> res2{in_place_error, 42};
 
auto res1_mapped = std::move(res1).transform_error([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = std::move(res2).transform_error([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_ok());
 
assert(res2_mapped.is_error());
assert(*res2_mapped == "42");

◆ transform_error() [3/4]

constexpr auto transform_error ( F && f ) const &

inlineconstexpr

Perforams a transformation on the error value of a result.

If the result contains an error value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the error value of a new result, where the error type of the new result is the exact type returned from the callable. If the result contains an ok value, a copy of the ok value is returned.

Note that this function is identical to map_error, but the name transform_error makes result able to be a drop in replacement for std::expected. map_error would be the more typical name of this monadic operation outside of C++.

Example

const result<void, int> res1{};
const result<void, int> res2{in_place_error, 42};
 
auto res1_mapped = res1.transform_error([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = res2.transform_error([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_ok());
 
assert(res2_mapped.is_error());
assert(*res2_mapped == "42");

◆ transform_error() [4/4]

constexpr auto transform_error ( F && f ) const &&

inlineconstexpr

Perforams a transformation on the error value of a result.

If the result contains an error value, that value is passed to the transformation callable provided. The value returned from the callable is then returned from this function as the error value of a new result, where the error type of the new result is the exact type returned from the callable. If the result contains an ok value, the ok value is returned.

Note that this function is identical to map_error, but the name transform_error makes result able to be a drop in replacement for std::expected. map_error would be the more typical name of this monadic operation outside of C++.

Example

const result<void, int> res1{};
const result<void, int> res2{in_place_error, 42};
 
auto res1_mapped = std::move(res1).transform_error([](auto value) {
    return std::to_string(value);
});
auto res2_mapped = std::move(res2).transform_error([](auto value) {
    return std::to_string(value);
});
 
assert(res1_mapped.is_ok());
 
assert(res2_mapped.is_error());
assert(*res2_mapped == "42");

◆ transpose() [1/2]

constexpr auto transpose ( ) &&

inlineconstexpr

Converts result<option<T>, E> into option<result<T, E>>

If the result contains an error, the return value will be a option that contains a result that contains an error. If the result contains an option that contains a value, the return value will be a option that contains result that contains an ok value. If the result contains a option that is none, the return value will be an option that is none.

This function only participates in overload resolution of T is an option.

Example

result<option<int>, std::string> val1{42};
result<option<int>, std::string> val2{none};
result<option<int>, std::string> val3{in_place_error, "oh no"};
 
auto val1_trans = std::move(val1).transpose();
auto val2_trans = std::move(val2).transpose();
auto val3_trans = std::move(val3).transpose();
 
assert(val1_trans.is_some());
assert(val1_trans->is_ok());
assert(**val1_trans == 42);
 
assert(val2_trans.is_none());
 
assert(val3_trans.is_some());
assert(val3_trans->is_error());
assert(val3_trans->error() == "oh no");

◆ transpose() [2/2]

constexpr auto transpose ( ) const &

inlineconstexpr

Converts result<option<T>, E> into option<result<T, E>>

If the result contains an error, the return value will be a option that contains a result that contains an error. If the result contains an option that contains a value, the return value will be a option that contains result that contains an ok value. If the result contains a option that is none, the return value will be an option that is none.

This function only participates in overload resolution of T is an option.

Example

result<option<int>, std::string> val1{42};
result<option<int>, std::string> val2{none};
result<option<int>, std::string> val3{in_place_error, "oh no"};
 
auto val1_trans = val1.transpose();
auto val2_trans = val2.transpose();
auto val3_trans = val3.transpose();
 
assert(val1_trans.is_some());
assert(val1_trans->is_ok());
assert(**val1_trans == 42);
 
assert(val2_trans.is_none());
 
assert(val3_trans.is_some());
assert(val3_trans->is_error());
assert(val3_trans->error() == "oh no");

◆ value() [1/4]

constexpr reference value ( ) &

inlineconstexpr

Accesses the ok value contained in the result.

This function first checks if the result contains an ok value before attempting to access the value. If the result contains an error, then this function throws an exception.

Example

result<int, std::string> res{42};
 
assert(res.value() == 42);

Exceptions

bad_result_access Thrown if the result contains an error

◆ value() [2/4]

constexpr rvalue_reference value ( ) &&

inlineconstexpr

Accesses the ok value contained in the result.

This function first checks if the result contains an ok value before attempting to access the value. If the result contains an error, then this function throws an exception.

Example

result<int, std::string> res{42};
 
assert(std::move(res).value() == 42);

Exceptions

bad_result_access Thrown if the result contains an error

◆ value() [3/4]

constexpr const_reference value ( ) const &

inlineconstexpr

Accesses the ok value contained in the result.

This function first checks if the result contains an ok value before attempting to access the value. If the result contains an error, then this function throws an exception.

Example

const result<int, std::string> res{42};
 
assert(res.value() == 42);

Exceptions

bad_result_access Thrown if the result contains an error

◆ value() [4/4]

constexpr rvalue_reference value ( ) const &&

inlineconstexpr

Accesses the ok value contained in the result.

This function first checks if the result contains an ok value before attempting to access the value. If the result contains an error, then this function throws an exception.

Example

const result<int, std::string> res{42};
 
assert(std::move(res).value() == 42);

Exceptions

bad_result_access Thrown if the result contains an error

◆ value_or() [1/2]

constexpr value_type value_or ( U && default_value ) &&

inlineconstexpr

Gets the ok value, or a default if the result is an error.

If the result contains an ok value, that ok value is returned. If the result contains an error value, the provided default value is forwarded, cast, and returned as by the following: static_cast<T>(std::forward<U>(default_value)).

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(std::move(res1).value_or(0) == 42);
 
assert(std::move(res2).value_or(0) == 0);

◆ value_or() [2/2]

constexpr value_type value_or ( U && default_value ) const &

inlineconstexpr

Gets the ok value, or a default if the result is an error.

If the result contains an ok value, a copy of that ok value is returned. If the result contains an error value, the provided default value is forwarded, cast, and returned as by the following: static_cast<T>(std::forward<U>(default_value)).

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(res1.value_or(0) == 42);
 
assert(res2.value_or(0) == 0);

◆ value_or_else() [1/2]

constexpr value_type value_or_else ( F && f ) &&

inlineconstexpr

Gets the ok value, or returns the result of a callable.

If the result contains an ok value, a copy of that ok value is returned. If the result contains an error, the provided callable is invoked and the result is cast and returned, as if by: static_cast<T>(std::invoke(std::forward<F>(f))).

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(std::move(res1).value_or_else([] { return 0; }) == 42);
 
assert(std::move(res2).value_or_else({] { return 0; }) == 0);

◆ value_or_else() [2/2]

constexpr value_type value_or_else ( F && f ) const &

inlineconstexpr

Gets the ok value, or returns the result of a callable.

If the result contains an ok value, a copy of that ok value is returned. If the result contains an error, the provided callable is invoked and the result is cast and returned, as if by: static_cast<T>(std::invoke(std::forward<F>(f))).

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(res1.value_or_else([] { return 0; }) == 42);
 
assert(res2.value_or_else({] { return 0; }) == 0);

◆ visit() [1/4]

constexpr DEDUCED visit ( V && visitor ) &

inlineconstexpr

Invokes a visitor witht he contained value.

This function treats a result as if it was a variant of T and E (i.e. variant<T, E>). If the result contians an ok value, that value is passed to the visitor. If the result contains an error, the error is passed to the visitor. When either T or E are void, an instance of void_t is passed instead.

Note that the overload function can be helpful for defining a visiotr inline.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
res1.visit(overload([](int ok_val) {
    assert(ok_val == 42);
}, [](std::string& err_val) {
    assert(false);
}));
 
res2.visit(overload([](int ok_val) {
    assert(false);
}, [](std::string& err_val) {
    assert(err_val == "oh no");
}));

◆ visit() [2/4]

constexpr DEDUCED visit ( V && visitor ) &&

inlineconstexpr

Invokes a visitor witht he contained value.

This function treats a result as if it was a variant of T and E (i.e. variant<T, E>). If the result contians an ok value, that value is passed to the visitor. If the result contains an error, the error is passed to the visitor. When either T or E are void, an instance of void_t is passed instead.

Note that the overload function can be helpful for defining a visiotr inline.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
std::move(res1).visit(overload([](int ok_val) {
    assert(ok_val == 42);
}, [](std::string err_val) {
    assert(false);
}));
 
std::move(res2).visit(overload([](int ok_val) {
    assert(false);
}, [](std::string err_val) {
    assert(err_val == "oh no");
}));

◆ visit() [3/4]

constexpr DEDUCED visit ( V && visitor ) const &

inlineconstexpr

Invokes a visitor witht he contained value.

This function treats a result as if it was a variant of T and E (i.e. variant<T, E>). If the result contians an ok value, that value is passed to the visitor. If the result contains an error, the error is passed to the visitor. When either T or E are void, an instance of void_t is passed instead.

Note that the overload function can be helpful for defining a visiotr inline.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{in_place_error, "oh no"};
 
res1.visit(overload([](int ok_val) {
    assert(ok_val == 42);
}, [](const std::string& err_val) {
    assert(false);
}));
 
res2.visit(overload([](int ok_val) {
    assert(false);
}, [](const std::string& err_val) {
    assert(err_val == "oh no");
}));

◆ visit() [4/4]

constexpr DEDUCED visit ( V && visitor ) const &&

inlineconstexpr

Invokes a visitor witht he contained value.

This function treats a result as if it was a variant of T and E (i.e. variant<T, E>). If the result contians an ok value, that value is passed to the visitor. If the result contains an error, the error is passed to the visitor. When either T or E are void, an instance of void_t is passed instead.

Note that the overload function can be helpful for defining a visiotr inline.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{in_place_error, "oh no"};
 
std::move(res1).visit(overload([](int ok_val) {
    assert(ok_val == 42);
}, [](std::string err_val) {
    assert(false);
}));
 
std::move(res2).visit(overload([](int ok_val) {
    assert(false);
}, [](std::string err_val) {
    assert(err_val == "oh no");
}));

◆ visit_informed() [1/4]

constexpr DEDUCED visit_informed ( V && visitor ) &

inlineconstexpr

Invokes a visitor with the contained value and meta data.

This function treats a result as if it was a variant of T and E (i.e. variant<T, E>). If the result contians an ok value, that value is passed to the visitor. If the result contains an error, the error is passed to the visitor. When either T or E are void, an instance of void_t is passed instead.

Unlike visit, this function also passes an extra meta data value when invoking the visitor. This meta data object provides constexpr information about the type and index of the value being visited. The ok value has index 0 and the error value has index 1. This object has the the API shown below.

struct alternative_info {
    // index of the alternative (ok == 0, error == 1)
    static inline constexpr size_t index = ...;
 
    // type of the alternative (ok == T, error == E)
    using type = ...;
 
    // helper function for forwarding non-const alternative values
    // without needing to provide a template argument.
    static constexpr decltype(auto) forward(...);
}

Note that the overload function can be helpful for defining a visitor inline.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
res1.visit_informed([](auto&& value, auto info) {
    if constexpr (info.index == 0) { // ok
        assert(value == 42);
    } else if constexpr (info.index == 1) { // error
        assert(false);
    }
});
 
res2.visit_informed([](auto&& value, auto info) {
    if constexpr (info.index == 0) { // ok
        assert(false);
    } else if constexpr (info.index == 1) { // error
        assert(value == "oh no");
    }
});

◆ visit_informed() [2/4]

constexpr DEDUCED visit_informed ( V && visitor ) &&

inlineconstexpr

Invokes a visitor with the contained value and meta data.

This function treats a result as if it was a variant of T and E (i.e. variant<T, E>). If the result contians an ok value, that value is passed to the visitor. If the result contains an error, the error is passed to the visitor. When either T or E are void, an instance of void_t is passed instead.

Unlike visit, this function also passes an extra meta data value when invoking the visitor. This meta data object provides constexpr information about the type and index of the value being visited. The ok value has index 0 and the error value has index 1. This object has the the API shown below.

struct alternative_info {
    // index of the alternative (ok == 0, error == 1)
    static inline constexpr size_t index = ...;
 
    // type of the alternative (ok == T, error == E)
    using type = ...;
 
    // helper function for forwarding non-const alternative values
    // without needing to provide a template argument.
    static constexpr decltype(auto) forward(...);
}

Note that the overload function can be helpful for defining a visitor inline.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
std::move(res1).visit_informed([](auto&& value, auto info) {
    if constexpr (info.index == 0) { // ok
        assert(value == 42);
    } else if constexpr (info.index == 1) { // error
        assert(false);
    }
});
 
std::move(res2).visit_informed([](auto&& value, auto info) {
    if constexpr (info.index == 0) { // ok
        assert(false);
    } else if constexpr (info.index == 1) { // error
        assert(value == "oh no");
    }
});

◆ visit_informed() [3/4]

constexpr DEDUCED visit_informed ( V && visitor ) const &

inlineconstexpr

Invokes a visitor with the contained value and meta data.

This function treats a result as if it was a variant of T and E (i.e. variant<T, E>). If the result contians an ok value, that value is passed to the visitor. If the result contains an error, the error is passed to the visitor. When either T or E are void, an instance of void_t is passed instead.

Unlike visit, this function also passes an extra meta data value when invoking the visitor. This meta data object provides constexpr information about the type and index of the value being visited. The ok value has index 0 and the error value has index 1. This object has the the API shown below.

struct alternative_info {
    // index of the alternative (ok == 0, error == 1)
    static inline constexpr size_t index = ...;
 
    // type of the alternative (ok == T, error == E)
    using type = ...;
 
    // helper function for forwarding non-const alternative values
    // without needing to provide a template argument.
    static constexpr decltype(auto) forward(...);
}

Note that the overload function can be helpful for defining a visitor inline.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{in_place_error, "oh no"};
 
res1.visit_informed([](auto&& value, auto info) {
    if constexpr (info.index == 0) { // ok
        assert(value == 42);
    } else if constexpr (info.index == 1) { // error
        assert(false);
    }
});
 
res2.visit_informed([](auto&& value, auto info) {
    if constexpr (info.index == 0) { // ok
        assert(false);
    } else if constexpr (info.index == 1) { // error
        assert(value == "oh no");
    }
});

◆ visit_informed() [4/4]

constexpr DEDUCED visit_informed ( V && visitor ) const &&

inlineconstexpr

Invokes a visitor with the contained value and meta data.

This function treats a result as if it was a variant of T and E (i.e. variant<T, E>). If the result contians an ok value, that value is passed to the visitor. If the result contains an error, the error is passed to the visitor. When either T or E are void, an instance of void_t is passed instead.

Unlike visit, this function also passes an extra meta data value when invoking the visitor. This meta data object provides constexpr information about the type and index of the value being visited. The ok value has index 0 and the error value has index 1. This object has the the API shown below.

struct alternative_info {
    // index of the alternative (ok == 0, error == 1)
    static inline constexpr size_t index = ...;
 
    // type of the alternative (ok == T, error == E)
    using type = ...;
 
    // helper function for forwarding non-const alternative values
    // without needing to provide a template argument.
    static constexpr decltype(auto) forward(...);
}

Note that the overload function can be helpful for defining a visitor inline.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{in_place_error, "oh no"};
 
std::move(res1).visit_informed([](auto&& value, auto info) {
    if constexpr (info.index == 0) { // ok
        assert(value == 42);
    } else if constexpr (info.index == 1) { // error
        assert(false);
    }
});
 
std::move(res2).visit_informed([](auto&& value, auto info) {
    if constexpr (info.index == 0) { // ok
        assert(false);
    } else if constexpr (info.index == 1) { // error
        assert(value == "oh no");
    }
});

Friends And Related Function Documentation

◆ error() [1/2]

constexpr result< never, E > error ( Args &&... args )

Similar to STL functions like std::make_unique and std::make_optional, this function is provided a template argument to specify what contained error type should be constructed, and then is passed arguments that are forwarded to the constructor of the contained error type.

Example

result<void, std::string> ensure_positive(int value) {
  if (value < 0) {
      return error<std::string>("value is negative");
  }
  return value;
}

◆ error() [2/2]

constexpr result< never, E > error	(	std::initializer_list< U >	ilist,
		Args &&...	args
	)

Similar to STL functions like std::make_unique and std::make_optional, this function is provided a template argument to specify what contained error type should be constructed, and then is passed arguments that are forwarded to the constructor of the contained error type.

Example

result<void, std::vector<int>> ilist_error_example() {
  // returns a result<never, std::vector<int>> which gets converted
  // to a result<void, std::vector<int>>
  return error<std::vector<int>>({1, 2, 3, 4, 5});
}

◆ get() [1/8]

constexpr CONST_RVALUE_REFERENCE get ( const result< T, E > && res )

This function is provided to make result generically compatible with variant. This function treats result<T, E> as if it were variant<T, E>, where index 0 is T and index 1 is E.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{in_place_error, "oh no"};
 
assert(get<0>(std::move(res1)) == 42);
assert(get<1>(std::move(res2)) == "oh no");

Template Parameters

IDX	The "alternative" index

Parameters

res	The result to access

Returns: A const rvalue of the accessed "alternative"

Exceptions

bad_result_access Thrown if the result does not contain the matching index.

◆ get() [2/8]

constexpr CONST_RVALUE_REFERENCE get ( const result< T, E > && res )

This fucntion is provided to make result generically compatible with variant. This function treats result<T, E> as if it were variant<T, E>.

This function only participates in overload resolution if T and E are distinct types, in order to avoid ambiguity.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{in_place_error, "oh no"};
 
assert(get<int>(std::move(res1)) == 42);
assert(get<std::string>(std::move(res2)) == "oh no");

Template Parameters

U	The "alternative" type

Parameters

res	The result to access

Returns: A const rvalue of the accessed "alternative"

Exceptions

bad_result_access Thrown if the result does not contain the matching index.

◆ get() [3/8]

constexpr CONST_REFERENCE get ( const result< T, E > & res )

This function is provided to make result generically compatible with variant. This function treats result<T, E> as if it were variant<T, E>, where index 0 is T and index 1 is E.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{in_place_error, "oh no"};
 
assert(get<0>(res1) == 42);
assert(get<1>(res2) == "oh no");

Template Parameters

IDX	The "alternative" index

Parameters

res	The result to access

Returns: A const reference to the accessed "alternative"

Exceptions

bad_result_access Thrown if the result does not contain the matching index.

◆ get() [4/8]

constexpr CONST_REFERENCE get ( const result< T, E > & res )

This fucntion is provided to make result generically compatible with variant. This function treats result<T, E> as if it were variant<T, E>.

This function only participates in overload resolution if T and E are distinct types, in order to avoid ambiguity.

Example

const result<int, std::string> res1{42};
const result<int, std::string> res2{in_place_error, "oh no"};
 
assert(get<int>(res1) == 42);
assert(get<std::string>(res2) == "oh no");

Template Parameters

U	The "alternative" type

Parameters

res	The result to access

Returns: A const reference to the accessed "alternative"

Exceptions

bad_result_access Thrown if the result does not contain the matching index.

◆ get() [5/8]

constexpr RVALUE_REFERENCE get ( result< T, E > && res )

This function is provided to make result generically compatible with variant. This function treats result<T, E> as if it were variant<T, E>, where index 0 is T and index 1 is E.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(get<0>(std::move(res1)) == 42);
assert(get<1>(std::move(res2)) == "oh no");

Template Parameters

IDX	The "alternative" index

Parameters

res	The result to access

Returns: An rvalue of the accessed "alternative"

Exceptions

bad_result_access Thrown if the result does not contain the matching index.

◆ get() [6/8]

constexpr RVALUE_REFERENCE get ( result< T, E > && res )

This fucntion is provided to make result generically compatible with variant. This function treats result<T, E> as if it were variant<T, E>.

This function only participates in overload resolution if T and E are distinct types, in order to avoid ambiguity.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(get<int>(std::move(res1)) == 42);
assert(get<std::string>(std::move(res2)) == "oh no");

Template Parameters

U	The "alternative" type

Parameters

res	The result to access

Returns: An rvalue of the accessed "alternative"

Exceptions

bad_result_access Thrown if the result does not contain the matching index.

◆ get() [7/8]

constexpr REFERENCE get ( result< T, E > & res )

This function is provided to make result generically compatible with variant. This function treats result<T, E> as if it were variant<T, E>, where index 0 is T and index 1 is E.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(get<0>(res1) == 42);
assert(get<1>(res2) == "oh no");

Template Parameters

IDX	The "alternative" index

Parameters

res	The result to access

Returns: A reference to the accessed "alternative"

Exceptions

bad_result_access Thrown if the result does not contain the matching index.

◆ get() [8/8]

constexpr REFERENCE get ( result< T, E > & res )

This fucntion is provided to make result generically compatible with variant. This function treats result<T, E> as if it were variant<T, E>.

This function only participates in overload resolution if T and E are distinct types, in order to avoid ambiguity.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(get<int>(res1) == 42);
assert(get<std::string>(res2) == "oh no");

Template Parameters

U	The "alternative" type

Parameters

res	The result to access

Returns: A reference to the accessed "alternative"

Exceptions

bad_result_access Thrown if the result does not contain the matching index.

◆ ok() [1/2]

constexpr result< T, never > ok ( Args &&... args )

Similar to STL functions like std::make_unique and std::make_optional, this function is provided a template argument to specify what contained type should be constructed, and then is passed arguments that are forwarded to the constructor of the contained type.

Example

result<std::string, void> make_string() {
    // returns a result<std::string, never> which gets converted to
    // a result<std::string, void>
    return ok<std::string>("hello");
}

◆ ok() [2/2]

constexpr result< T, never > ok	(	std::initializer_list< U >	ilist,
		Args &&...	args
	)

Similar to STL functions like std::make_unique and std::make_optional, this function is provided a template argument to specify what contained type should be constructed, and then is passed arguments that are forwarded to the constructor of the contained type.

Example

result<std::vector<int>, void> make_nums() {
    // returns a result<std::vector<int>, never> which gets converted
    // to a result<std::vector<int>, void>
    return ok<std::vector<int>>({1, 2, 3, 4, 5});
}

◆ operator==() [1/3]

constexpr bool operator==	(	const result< T, E > &	lhs,
		const result< U, V > &	rhs
	)

Returns true if both result instances either both contain ok values or both contain error values, and the values compare equal.

Example

result<int, std::string> res1{42};
result<unsigned int, const char*> res2{42};
 
assert(res1 == res2);

◆ operator==() [2/3]

constexpr bool operator==	(	const result< T, E > &	lhs,
		const U &	rhs
	)

This function return true if the result contains an ok value and the ok value compares equal with the plain value.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(res1 == 42);
assert(res2 != 42);

◆ operator==() [3/3]

constexpr bool operator==	(	const U &	lhs,
		const result< T, E > &	rhs
	)

This function return true if the result contains an ok value and the ok value compares equal with the plain value.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
assert(42 == res1);
assert(42 != res2);

◆ swap()

constexpr void swap	(	result< T, E > &	a,
		result< T, E > &	b
	)

If both result instances contain an ok value or both contain an error value, the values are swapped directly. If the two result instances do not contain the same kind of value, the values are moved out of the results temporarily, the old values are destroyed, and new values a move constructed in to the opposite result.

Example

result<int, std::string> res1{42};
result<int, std::string> res2{in_place_error, "oh no"};
 
swap(res1, res2);
 
assert(res1.is_error());
assert(res1.error() == "oh no");
 
assert(res2.is_ok());
assert(*res2 == 42);

The documentation for this class was generated from the following files:

sumty/detail/fwd.hpp
sumty/result.hpp

Public Types

Public Member Functions

Related Functions

Detailed Description

template<typename T, typename E> class sumty::result< T, E >

Constructor & Destructor Documentation

◆ result() [1/12]

Example

◆ result() [2/12]

Example

◆ result() [3/12]

Example

◆ result() [4/12]

Example

◆ result() [5/12]

Example

◆ result() [6/12]

Example

◆ result() [7/12]

Example

◆ result() [8/12]

Example

◆ result() [9/12]

Example

◆ result() [10/12]

Example

◆ result() [11/12]

Example

◆ result() [12/12]

Example

◆ ~result()

Member Function Documentation

◆ and_then() [1/4]

Example

◆ and_then() [2/4]

Example

◆ and_then() [3/4]

Example

◆ and_then() [4/4]

Example

◆ cref()

Example

◆ emplace() [1/2]

Example

◆ emplace() [2/2]

Example

◆ emplace_error() [1/2]

Example

◆ emplace_error() [2/2]

Example

◆ error() [1/4]

Example

◆ error() [2/4]

Example

◆ error() [3/4]

Example

◆ error() [4/4]

Example

◆ error_or_none() [1/2]

Example

◆ error_or_none() [2/2]

Example

◆ flatten() [1/2]

Example

◆ flatten() [2/2]

Example

◆ flatten_all() [1/2]

Example

◆ flatten_all() [2/2]

Example

◆ has_value()

Example

◆ invert() [1/2]

Example

◆ invert() [2/2]

Example

◆ is_error()

Example

◆ is_ok()

Example

template<typename T, typename E>
class sumty::result< T, E >