etl/docs/utilities/expected.md

title
expected

{{< callout type="info">}} Header: expected.h
From: 20.35.13
Similar to: std::expected {{< /callout >}}

A generic result type for returning either a result or an error.
Replacement for etl::result.

template <typename TValue, typename TError>
class expected

Specialisation for void result.

template <typename TError>
class expected<void, TError>

unexpected

template class unexpected

unexpect_t

A tag type for in-place construction of an unexpected value in an etl::expected object.

---

struct unexpect_t;

A constant of type etl::unexpect_t which is directly passed to a constructor of etl::expected to construct an unexpected value.

inline constexpr unexpect_t unexpect;

From: C++17.

static const unexpect_t unexpect;

Before: C++17.

unexpected

template <typename TError>
class unexpected<TError>

Types

error_type = TError

Member functions

ETL_CONSTEXPR
unexpected(const unexpected& other)

Description
Copy constructor

---

ETL_CONSTEXPR 
unexpected(unexpected&& other)

Description
Move constructor.
Since: C++11

---

template <typename TError>
constexpr explicit unexpected(TError&& e)

Description
Construct from an argument.
Since: C++11

---

template <typename TError>
explicit unexpected(const TError& e)

Description
Construct from argument. Before: C++11

---

template <typename... TArgs>
constexpr explicit unexpected(etl::in_place_t, TArgs&&... args)

Description
Construct from arguments. Since: C++11

---

template <typename U, typename... TArgs>
constexpr explicit unexpected(etl::in_place_t, std::initializer_list<U> init, TArgs&&... args)

Description
Construct from initializer_list and arguments. Since: C++11

---

ETL_CONSTEXPR14
etl::unexpected<TError>& operator =(const etl::unexpected<TError>& rhs)

Description
Assign from etl::unexpected

---

ETL_CONSTEXPR14
etl::unexpected<TError>& operator =(etl::unexpected<TError>&& rhs)

Description
Move assign from etl::unexpected Since: C++11

---

TError& error() & noexcept

Description
Get the error. Since: C++11

---

constexpr const TError& error() const& noexcept

Description
Get the error. Since: C++11

---

TError&& error() && noexcept

Description
Get the error. Since: C++11

---

constexpr TError&& error() const&& noexcept

Description
Get the error. Since: C++11

---

const TError& error() const

Description
Get the error. Before: C++11

---

void swap(etl::unexpected<TError>& other)

Description
Swap with another etl::unexpected

expected

template <typename TValue, typename TError>
class expected

Specialisation for void value type.

template <typename TError>
class expected<void, TError>

Types

this_type       etl::expected<TValue, TError>
value_type      TValue
error_type      TError
unexpected_type etl::unexpected<TError>

Member functions

ETL_CONSTEXPR14 expected() ETL_NOEXCEPT

Description
Default constructor

---

ETL_CONSTEXPR14 expected(const value_type& value) ETL_NOEXCEPT

Description
Constructor

---

ETL_CONSTEXPR14 expected(value_type&& value) ETL_NOEXCEPT

Description
Constructor Since: C++11

---

template <typename U>
ETL_CONSTEXPR14 expected(U&& value)

Description
Construct the value type from a value implicitly convertible to it. Not selected when U is an etl::expected, etl::unexpected, etl::in_place_t, etl::unexpect_t or value_type itself. Since: C++11

---

template <typename U>
ETL_CONSTEXPR14 explicit expected(U&& value)

Description
Construct the value type from a value that is only explicitly convertible to it. Constrained as above. Since: C++11

---

template <typename U, typename G>
expected(const etl::expected<U, G>& other)

Description
Copy construct from an etl::expected<U, G> whose value and error types are both implicitly convertible. Not selected when value_type can be constructed from, or etl::unexpected<error_type> built from, the source etl::expected itself. Since: C++11

---

template <typename U, typename G>
explicit expected(const etl::expected<U, G>& other)

Description
Copy construct from an etl::expected<U, G> whose value or error type is only explicitly convertible. Constrained as above. Since: C++11

---

template <typename U, typename G>
expected(etl::expected<U, G>&& other)

Description
Move construct from an etl::expected<U, G> whose value and error types are both implicitly convertible. Constrained as above. Since: C++11

---

template <typename U, typename G>
explicit expected(etl::expected<U, G>&& other)

Description
Move construct from an etl::expected<U, G> whose value or error type is only explicitly convertible. Constrained as above. Since: C++11

---

ETL_CONSTEXPR14 expected(const expected& other) ETL_NOEXCEPT

Description
Copy constructor

---

ETL_CONSTEXPR14 expected(expected&& other) ETL_NOEXCEPT

Description
Move constructor Since: C++11

---

template <typename F>
ETL_CONSTEXPR14 explicit expected(const etl::unexpected<F>& ue)

Description
Copy construct from unexpected type.

---

template <typename F>
ETL_CONSTEXPR14 explicit expected(etl::unexpected<F>&& ue)

Description
Move construct from unexpected type. Since: C++11

---

ETL_CONSTEXPR14 explicit expected(etl::in_place_t) ETL_NOEXCEPT

Description
Construct with default value type.

---

template <typename... TArgs>
ETL_CONSTEXPR14 explicit expected(etl::in_place_t, TArgs&&... args)

Description
Construct value type from arguments. Since: C++11

---

template <typename U, typename... TArgs>
ETL_CONSTEXPR14 explicit expected(etl::in_place_t, std::initializer_list<U> il, TArgs&&... args)

Description
Construct value type from initializer_list and arguments.

---

template <typename... TArgs>
ETL_CONSTEXPR14 explicit expected(etl::unexpect_t, TArgs&&... args)

Description
Construct error type from arguments. Since: C++11

---

template <typename U, typename... TArgs>
ETL_CONSTEXPR14 explicit expected(etl::unexpect_t, std::initializer_list<U> il, TArgs&&... args)

Description
Construct error type from initializer_list and arguments. Since: C++11

---

this_type& operator =(const this_type& other)

Description
Copy assign

---

this_type& operator =(this_type&& other)

Description
Move assign Since: C++11

---

expected& operator =(const value_type& value)

Description
Copy assign from value

---

expected& operator =(value_type&& value)

Description
Move assign from value Since: C++11

---

template <typename U>
expected& operator =(U&& value)

Description
Assign from a value convertible to value_type. Constrained like the value constructor. Since: C++11

---

expected& operator =(const unexpected_type& error)

Description
Copy assign from error

---

expected& operator =(unexpected_type&& error)

Description
Move assign from error Since: C++11

---

ETL_CONSTEXPR14 value_type& value()&

Description
Get the value. Undefined if has_value() returns false. Not valid for void specialisation. Since: C++11

---

ETL_CONSTEXPR14 const value_type& value() const&

Description
Get the value. Undefined if has_value() returns false. Not valid for void specialisation. Since: C++11

---

ETL_CONSTEXPR14 value_type&& value()&&

Description
Get the value. Undefined if has_value() returns false. Not valid for void specialisation. Since: C++11

---

ETL_CONSTEXPR14 const value_type&& value() const&&

Description
Get the value. Undefined if has_value() returns false. Not valid for void specialisation. Since: C++11

---

value_type& value() const

Description
Get the value. Undefined if has_value() returns false. Not valid for void specialisation. Before: C++11

---

ETL_NODISCARD
ETL_CONSTEXPR14
bool has_value() const

Description
Returns true if the class contains a value.

---

ETL_NODISCARD
ETL_CONSTEXPR14
operator bool() const

Description
Returns true if the class contains a value.

---

template <typename U>
ETL_NODISCARD
ETL_CONSTEXPR14
value_type value_or(U&& default_value) const&

Description
Returns the value or default_value if has_value() returns false. Since: C++11

---

template <typename U>
ETL_NODISCARD
ETL_CONSTEXPR14
value_type value_or(U&& default_value)&&

Description
Returns the value or default_value if has_value() returns false. Since: C++11

---

template <typename U>
value_type value_or(const U& default_value) const

Description
Returns the value or default_value if has_value() returns false. Before: C++11

---

ETL_NODISCARD
ETL_CONSTEXPR14
error_type& error()& ETL_NOEXCEPT

Description
Returns the error. Undefined if has_value() returns true. Since: C++11

---

ETL_NODISCARD
ETL_CONSTEXPR14
const error_type& error() const& ETL_NOEXCEPT

Description
Returns the error. Undefined if has_value() returns true. Since: C++11

---

ETL_NODISCARD
ETL_CONSTEXPR14
error_type&& error() && ETL_NOEXCEPT

Description
Returns the error. Undefined if has_value() returns true. Since: C++11

---

ETL_NODISCARD
ETL_CONSTEXPR14
const error_type&& error() const&& ETL_NOEXCEPT

Description
Returns the error. Undefined if has_value() returns true. Since: C++11

---

error_type& error() const

Description
Returns the error. Undefined if has_value() returns true. Before: C++11

---

template <typename G>
ETL_NODISCARD
ETL_CONSTEXPR14
error_type error_or(G&& default_error) const&

Description Returns default_error if has_value() returns true; otherwise returns the stored error. Since: C++11

---

template <typename G>
ETL_NODISCARD
ETL_CONSTEXPR14
error_type error_or(G&& default_error)&&

Description Returns default_error if has_value() returns true; otherwise returns the stored error. Since: C++11

---

template <typename G>
error_type error_or(const G& default_error) const

Description Returns default_error if has_value() returns true; otherwise returns the stored error. Before: C++11

---

template <typename... TArgs>
ETL_CONSTEXPR14 value_type& emplace(TArgs&&... args) ETL_NOEXCEPT

Description
Create from arguments. Since: C++11

---

template <typename U, typename... TArgs>
ETL_CONSTEXPR14 value_type& emplace(std::initializer_list<U>& il, TArgs&&... args) ETL_NOEXCEPT

Description
Create from arguments. Since: C++11

---

value_type* operator ->()

Description
Class member access operator.

---

const value_type* operator ->() const

Description
Const class member access operator.

---

value_type& operator *() &

Description Dereference operator.

---

const value_type& operator *() const&

Description Dereference operator.

---

value_type&& operator *() &&

Description Dereference operator. Since: C++11

---

const value_type&& operator *() const&&

Description Dereference operator. Since: C++11

---

ETL_NODISCARD
ETL_CONSTEXPR14
value_type* begin() ETL_NOEXCEPT

Description Returns a pointer to the value if has_value() returns true, otherwise returns nullptr. Allows expected to be used as a range of 0 or 1 elements. Not valid for void specialisation.

---

ETL_NODISCARD
ETL_CONSTEXPR14
const value_type* begin() const ETL_NOEXCEPT

Description Returns a pointer to the value if has_value() returns true, otherwise returns nullptr. Not valid for void specialisation.

---

ETL_NODISCARD
ETL_CONSTEXPR14
value_type* end() ETL_NOEXCEPT

Description Returns a pointer past the value if has_value() returns true, otherwise returns nullptr. Not valid for void specialisation.

---

ETL_NODISCARD
ETL_CONSTEXPR14
const value_type* end() const ETL_NOEXCEPT

Description Returns a pointer past the value if has_value() returns true, otherwise returns nullptr. Not valid for void specialisation.

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TValue&>::type>::type>
auto transform(F&& f) & -> expected<U, TError>

Description If has_value() returns true, it invokes f on the value and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error(). For void specialisation see below. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
auto transform(F&& f) & -> expected<U, TError>

Description For void specialisation. If has_value() returns true, it invokes f and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error(). Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TValue&>::type>::type>
auto transform(F&& f) const& -> expected<U, TError>

Description If has_value() returns true, it invokes f on the value and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error(). For void specialisation see below. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
auto transform(F&& f) const& -> expected<U, TError>

Description For void specialisation. If has_value() returns true, it invokes f and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error(). Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TValue&&>::type>::type>
auto transform(F&& f) && -> expected<U, TError>

Description If has_value() returns true, it invokes f on the value and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error(). For void specialisation see below. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
auto transform(F&& f) && -> expected<U, TError>

Description For void specialisation. If has_value() returns true, it invokes f and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error(). Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TValue&&>::type>::type>
auto transform(F&& f) const&& -> expected<U, TError>

Description If has_value() returns true, it invokes f and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error(). For void specialisation see below. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
auto transform(F&& f) const&& -> expected<U, TError>

Description For void specialisation. If has_value() returns true, it invokes f and returns the result wrapped in an expected object; otherwise it returns an expected object that contains error(). Since: C++11

---

template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TValue&>::type>::type>
auto and_then(F&& f) & -> U

Description If has_value() returns true, it invokes f on the value and returns the result; otherwise it returns an expected object that contains error(). For void specialisation see below. Since: C++11

---

template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>
auto and_then(F&& f) & -> U

Description For void specialisation. If has_value() returns true, it invokes f and returns the result; otherwise it returns an expected object that contains error(). Since: C++11

---

template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TValue&>::type>::type>
auto and_then(F&& f) const& -> U

Description If has_value() returns true, it invokes f on the value and returns the result; otherwise it returns an expected object that contains error(). For void specialisation see below. Since: C++11

---

template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
auto and_then(F&& f) const& -> U

Description For void specialisation. If has_value() returns true, it invokes f and returns the result; otherwise it returns an expected object that contains error(). Since: C++11

---

template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TValue&&>::type>::type>
auto and_then(F&& f) && -> U

Description If has_value() returns true, it invokes f on the value and returns the result; otherwise it returns an expected object that contains error(). For void specialisation see below. Since: C++11

---

template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
auto and_then(F&& f) && -> U

Description For void specialisation. If has_value() returns true, it invokes f and returns the result; otherwise it returns an expected object that contains error(). Since: C++11

---

template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TValue&&>::type>::type>
auto and_then(F&& f) const&& -> U

Description If has_value() returns true, it invokes f on the value and returns the result; otherwise it returns an expected object that contains error(). For void specialisation see below. Since: C++11

---

template < typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void>::type>::type>
auto and_then(F&& f) const&& -> U

Description For void specialisation. If has_value() returns true, it invokes f and returns the result; otherwise it returns an expected object that contains error(). Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&>::type>::type>
auto or_else(F&& f) & -> U

Description If has_value() returns true, it returns an expected object that contains value(); otherwise it invokes f on error() and returns the result. For void specialisation see below. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&>::type>::type>
auto or_else(F&& f) & -> U

Description For void specialisation. If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&>::type>::type>
auto or_else(F&& f) const& -> U

Description If has_value() returns true, it returns an expected object that contains value(); otherwise it invokes f on error() and returns the result. For void specialisation see below. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&>::type>::type>
auto or_else(F&& f) const& -> U

Description For void specialisation. If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&&>::type>::type>
auto or_else(F&& f) && -> U

Description If has_value() returns true, it returns an expected object that contains value(); otherwise it invokes f on error() and returns the result. For void specialisation see below. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&&>::type>::type>
auto or_else(F&& f) && -> U

Description For void specialisation. If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&&>::type>::type>
auto or_else(F&& f) const&& -> U

Description If has_value() returns true, it returns an expected object that contains value(); otherwise it invokes f on error() and returns the result. For void specialisation see below. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&&>::type>::type>
auto or_else(F&& f) const&& -> U

Description For void specialisation. If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&>::type>::type>
auto transform_error(F&& f) & -> expected<TValue, U>

Description If has_value() returns true, it returns an expected that contains value(); otherwise it invokes f on error() and returns the result wrapped in an expected object. For void specialisation see below. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&>::type>::type>
auto transform_error(F&& f) & -> expected<TValue, U>

Description For void specialisation. If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result wrapped in an expected object. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&>::type>::type>
auto transform_error(F&& f) const& -> expected<TValue, U>

Description If has_value() returns true, it returns an expected that contains value(); otherwise it invokes f on error() and returns the result wrapped in an expected object. For void specialisation see below. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&>::type>::type>
auto transform_error(F&& f) const& -> expected<TValue, U>

Description For void specialisation. If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result wrapped in an expected object. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&&>::type>::type>
auto transform_error(F&& f) && -> expected<TValue, U>

Description If has_value() returns true, it returns an expected that contains value(); otherwise it invokes f on error() and returns the result wrapped in an expected object. For void specialisation see below. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, TError&&>::type>::type>
auto transform_error(F&& f) && -> expected<TValue, U>

Description For void specialisation. If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result wrapped in an expected object. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&&>::type>::type>
auto transform_error(F&& f) const&& -> expected<TValue, U>

Description If has_value() returns true, it returns an expected that contains value(); otherwise it invokes f on error() and returns the result wrapped in an expected object. For void specialisation see below. Since: C++11

---

template <typename F, typename U = typename etl::remove_cvref< typename etl::invoke_result<F, void, const TError&&>::type>::type>
auto transform_error(F&& f) const&& -> expected<TValue, U>

Description For void specialisation. If has_value() returns true, it returns a default constructed expected object of the appropriate type; otherwise it invokes f on error() and returns the result wrapped in an expected object. Since: C++11