Skip to main content
Pigweed's logo Pigweed
code_xml
  1. Home
  2. Reference
  3. C/C++
  4. Data structures & utilities
  5. pw_result
  6. pw::Result< T, StatusType > Class Template Reference
pw::Result< T, StatusType > Class Template Referencefinal

Overview

template<typename T, typename StatusType>
class pw::Result< T, StatusType >

Error propagation primitive: value or error status.

The pw::Result<T, StatusType> class template is a union of a StatusType object (pw::Status by default) and an object of type T. Result<T, StatusType> models an object that is either a usable object, or an error status (of type StatusType) explaining why such an object is not present. It is typically the return value of a function which may fail.

To simplify its use in generic code and coroutines, Result is specialized for void.

Checking for success

Result<T, StatusType> can never hold an OK error status; instead, the presence of an object of type T indicates success (status().ok() == true). Use the Result<T, StatusType>::ok() member function to check for success.

Example:

Result<Foo> result = DoBigCalculationThatCouldFail();
if (result.ok()) {
result->DoSomethingCool();
} else {
PW_LOG_ERROR("Calculation failed: %s", result.status().str());
}
Definition: result.h:212
constexpr bool ok() const noexcept
Definition: result.h:590
constexpr status_type status() const noexcept
Definition: result.h:640

Accessing objects

Accessing the object held by a Result<T, StatusType> should be performed via operator* or operator->, after a call to ok() confirms that the Result<T, StatusType> holds an object of type T:

Example:

Result<int> i = GetCount();
if (i.ok()) {
updated_total += *i;
}

Using Result<T, StatusType>::value() when no valid value is present will trigger a PW_ASSERT.

Example:

Result<Foo> result = DoBigCalculationThatCouldFail();
const Foo& foo = result.value(); // Asserts/crashes if no value present
foo.DoSomethingCool();
constexpr const T & value() const &PW_ATTRIBUTE_LIFETIME_BOUND
Definition: result.h:706

Constructing result objects

A Result<T*> can be constructed from a null pointer like any other pointer value, and the result will be that ok() returns true and value() returns nullptr. Checking the value of a pointer in a Result<T*> generally requires a bit more care, to ensure both that a value is present and that value is not null:

Result<Foo*> result = LookUpTheFoo(arg);
if (!result.ok()) {
PW_LOG_ERROR("Unable to look up the Foo: %s", result.status().str());
} else if (*result == nullptr) {
PW_LOG_ERROR("Unexpected null pointer");
} else {
(*result)->DoSomethingCool();
}

Example factory implementation returning Result<T>:

Result<Foo> FooFactory::MakeFoo(int arg) {
if (arg <= 0) {
}
return Foo(arg);
}
static constexpr Status InvalidArgument() noexcept
Definition: status.h:244

<tt>Result<Status></tt> and <tt>Result<StatusType, StatusType></tt>

Prefer returning StatusType (or Result<void, StatusType> in generic code) instead of Result<StatusType, StatusType> when no additional value is needed. However, Result<StatusType, StatusType> is supported for generic code that wraps functions returning StatusType.

Because the value type and the status type are the same in Result<StatusType, StatusType>, constructing, assigning, or comparing with a StatusType (or StatusType::Code) always operates on the contained value (ok() == true), even if the provided status is not OK. To set an error status on a Result<StatusType, StatusType>, call reset(). To check or compare the status of the Result itself, use ok() or status().

Example
// Constructing or assigning from Status sets the contained value:
PW_ASSERT(res.ok()); // The Result has a value!
PW_ASSERT(res.status() == pw::OkStatus()); // The Result's status is OK.
PW_ASSERT(*res == pw::Status::NotFound()); // Contained value is NOT_FOUND.
PW_ASSERT(res == pw::Status::NotFound()); // Compares the contained value.
// Use reset() to set the Result's error status:
PW_ASSERT(!res.ok()); // No value is present.
PW_ASSERT(res != pw::Status::Internal()); // No value to compare equal.
constexpr void reset() noexcept
Definition: result.h:648
static constexpr Status Internal() noexcept
Definition: status.h:372
static constexpr Status NotFound() noexcept
Definition: status.h:270
#define PW_ASSERT(condition)
Definition: assert.h:33
constexpr Status OkStatus() noexcept
Definition: status.h:569
@ PW_STATUS_INTERNAL
Definition: status.h:68
Source: pw_result/result_test.cc
Template Parameters
TType of the contained value (or void).
StatusTypeStatus type that represents the error. Defaults to pw::Status. Must be derived from pw::StatusBase and use an enum code.
Inheritance diagram for pw::Result< T, StatusType >:

Public Types

using value_type = T
 
using status_type = StatusType
 

Public Member Functions

template<typename S = StatusType, std::enable_if_t< std::is_same_v< S, Status >, int > = 0>
constexpr Result () noexcept
 
template<typename S = StatusType, std::enable_if_t< std::is_same_v< S, HasValue >, int > = 0>
constexpr Result () noexcept
 Constructs an empty Optional<T> with no value (has_value() == false).
 
template<typename S = StatusType, std::enable_if_t< std::is_same_v< S, HasValue >, int > = 0>
constexpr Result (std::nullopt_t) noexcept
 
template<typename S = StatusType, std::enable_if_t< std::is_same_v< S, HasValue >, int > = 0>
constexpr Result & operator= (std::nullopt_t) noexcept
 Resets an Optional<T> to an empty state (has_value() == false).
 
constexpr Result (const Result &)=default
 
constexpr Result & operator= (const Result &)=default
 
constexpr Result (Result &&)=default
 
constexpr Result & operator= (Result &&)=default
 
template<typename U , std::enable_if_t< internal_result::kCanConvertFromResult< T, U, const U &, StatusType, true >, int > = 0>
constexpr Result (const Result< U, StatusType > &other) noexcept
 
template<typename U , std::enable_if_t< internal_result::kCanConvertFromResult< T, U, const U &, StatusType, false >, int > = 0>
constexpr Result (const Result< U, StatusType > &other) noexcept
 
template<typename U , std::enable_if_t< internal_result::kCanConvertFromResult< T, U, U &&, StatusType, true >, int > = 0>
constexpr Result (Result< U, StatusType > &&other) noexcept
 
template<typename U , std::enable_if_t< internal_result::kCanConvertFromResult< T, U, U &&, StatusType, false >, int > = 0>
constexpr Result (Result< U, StatusType > &&other) noexcept
 
template<typename U , std::enable_if_t< internal_result::kCanAssignFromResult< T, U, const U &, StatusType >, int > = 0>
constexpr Result & operator= (const Result< U, StatusType > &other) noexcept
 
template<typename U , std::enable_if_t< internal_result::kCanAssignFromResult< T, U, U &&, StatusType >, int > = 0>
constexpr Result & operator= (Result< U, StatusType > &&other) noexcept
 
template<typename U , std::enable_if_t< internal_result::kCanConvertFromStdOptional< T, U, const U &, StatusType, true >, int > = 0>
constexpr Result (const std::optional< U > &other) noexcept
 
template<typename U , std::enable_if_t< internal_result::kCanConvertFromStdOptional< T, U, const U &, StatusType, false >, int > = 0>
constexpr Result (const std::optional< U > &other) noexcept
 
template<typename U , std::enable_if_t< internal_result::kCanConvertFromStdOptional< T, U, U &&, StatusType, true >, int > = 0>
constexpr Result (std::optional< U > &&other) noexcept
 
template<typename U , std::enable_if_t< internal_result::kCanConvertFromStdOptional< T, U, U &&, StatusType, false >, int > = 0>
constexpr Result (std::optional< U > &&other) noexcept
 
template<typename U , std::enable_if_t< internal_result::kCanAssignFromStdOptional< T, U, const U &, StatusType >, int > = 0>
constexpr Result & operator= (const std::optional< U > &other) noexcept
 Assigns an Optional<T> from a std::optional<U>.
 
template<typename U , std::enable_if_t< internal_result::kCanAssignFromStdOptional< T, U, U &&, StatusType >, int > = 0>
constexpr Result & operator= (std::optional< U > &&other) noexcept
 Assigns an Optional<T> from a std::optional<U>.
 
template<typename U = status_type, std::enable_if_t< internal_result::kCanConstructFromStatus< T, U &&, StatusType, true >, int > = 0>
constexpr Result (U &&v)
 
template<typename U = status_type, std::enable_if_t< internal_result::kCanConstructFromStatus< T, U &&, StatusType, false >, int > = 0>
constexpr Result (U &&v)
 
template<typename U = status_type, std::enable_if_t< internal_result::kCanAssignFromStatus< T, U &&, StatusType >, int > = 0>
constexpr Result & operator= (U &&v)
 
template<typename U = std::remove_cv_t<T>, typename = std::enable_if_t< internal_result::kCanAssignFromValue<T, U&&, StatusType>>>
constexpr Result & operator= (U &&v) noexcept
 
template<typename... Args, std::enable_if_t< std::is_constructible_v< T, Args... >, int > = 0>
constexpr Result (std::in_place_t, Args &&... args) noexcept
 
template<typename U , typename... Args, std::enable_if_t< std::is_constructible_v< T, std::initializer_list< U > &, Args... >, int > = 0>
constexpr Result (std::in_place_t, std::initializer_list< U > ilist, Args &&... args) noexcept
 
template<typename U = std::remove_cv_t<T>, std::enable_if_t< internal_result::kCanConstructFromValue< T, U &&, StatusType, true >, int > = 0>
constexpr Result (U &&u) noexcept
 
template<typename U = std::remove_cv_t<T>, std::enable_if_t< internal_result::kCanConstructFromValue< T, U &&, StatusType, false >, int > = 0>
constexpr Result (U &&u) noexcept
 
constexpr bool ok () const noexcept
 
constexpr bool has_value () const noexcept
 
template<typename S = StatusType, std::enable_if_t< std::is_same_v< S, HasValue >, int > = 0>
constexpr operator bool () const noexcept
 
template<typename S = StatusType, typename U = std::remove_cv_t<T>, std::enable_if_t< std::is_same_v< S, HasValue > &&std::is_constructible_v< U, const T & >, int > = 0>
constexpr std::optional< U > std_optional () const &noexcept
 
template<typename S = StatusType, typename U = std::remove_cv_t<T>, std::enable_if_t< std::is_same_v< S, HasValue > &&std::is_constructible_v< U, T && >, int > = 0>
constexpr std::optional< U > std_optional () &&noexcept
 
constexpr status_type status () const noexcept
 
template<typename S = StatusType, std::enable_if_t< std::is_same_v< S, HasValue >, int > = 0>
constexpr void reset () noexcept
 
template<typename S = StatusType, std::enable_if_t<!std::is_same_v< S, HasValue >, int > = 0>
constexpr void reset (status_type error_status)
 
template<typename C , typename S = StatusType, std::enable_if_t<!std::is_same_v< S, HasValue > &&std::is_same_v< C, typename S::Code >, int > = 0>
constexpr void reset (C code)
 
template<typename status_type::Code kCode>
constexpr void reset () noexcept
 
constexpr const T & value () const &PW_ATTRIBUTE_LIFETIME_BOUND
 
constexpr T & value () &PW_ATTRIBUTE_LIFETIME_BOUND
 
constexpr const T && value () const &&PW_ATTRIBUTE_LIFETIME_BOUND
 
constexpr T && value () &&PW_ATTRIBUTE_LIFETIME_BOUND
 
constexpr const T & operator* () const &noexcept PW_ATTRIBUTE_LIFETIME_BOUND
 
constexpr T & operator* () &noexcept PW_ATTRIBUTE_LIFETIME_BOUND
 
constexpr const T && operator* () const &&noexcept PW_ATTRIBUTE_LIFETIME_BOUND
 
constexpr T && operator* () &&noexcept PW_ATTRIBUTE_LIFETIME_BOUND
 
constexpr const T * operator-> () const noexcept PW_ATTRIBUTE_LIFETIME_BOUND
 
constexpr T * operator-> () noexcept PW_ATTRIBUTE_LIFETIME_BOUND
 
template<typename U = std::remove_cv_t<T>>
constexpr std::remove_cv_t< T > value_or (U &&default_value) const &noexcept
 
template<typename U = std::remove_cv_t<T>>
constexpr std::remove_cv_t< T > value_or (U &&default_value) &&noexcept
 
constexpr void IgnoreError () const noexcept
 
template<typename... Args, std::enable_if_t< std::is_constructible_v< T, Args... >, int > = 0>
constexpr T & emplace (Args &&... args) noexcept
 
template<typename U , typename... Args, std::enable_if_t< std::is_constructible_v< T, std::initializer_list< U > &, Args... >, int > = 0>
constexpr T & emplace (std::initializer_list< U > ilist, Args &&... args) noexcept
 
void swap (Result &other) noexcept
 Swaps the contents of *this and other.
 
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, T & >, int > = 0, typename Ret = internal_result::InvokeResultType<Fn, T&>>
constexpr Ret and_then (Fn &&function) &
 
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, T && >, int > = 0, typename Ret = internal_result::InvokeResultType<Fn, T&&>>
constexpr Ret and_then (Fn &&function) &&
 
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, const T & >, int > = 0, typename Ret = internal_result::InvokeResultType<Fn, const T&>>
constexpr Ret and_then (Fn &&function) const &
 
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, const T && >, int > = 0, typename Ret = internal_result::InvokeResultType<Fn, const T&&>>
constexpr Ret and_then (Fn &&function) const &&
 
template<typename Fn , typename U = T, typename S = status_type, std::enable_if_t< std::is_copy_constructible_v< U > &&std::is_copy_constructible_v< S > &&internal_result::kIsOrElseInvocable< Fn, const status_type & >, int > = 0>
constexpr Result< T, StatusType > or_else (Fn &&function) const &
 
template<typename Fn , typename U = T, typename S = status_type, std::enable_if_t< std::is_move_constructible_v< U > &&std::is_move_constructible_v< S > &&internal_result::kIsOrElseInvocable< Fn, status_type && >, int > = 0>
constexpr Result< T, StatusType > or_else (Fn &&function) &&
 
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, T & >, int > = 0, typename Ret = internal_result::TransformResultType<StatusType, Fn, T&>>
constexpr Result< Ret, StatusType > transform (Fn &&function) &
 
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, T && >, int > = 0, typename Ret = internal_result::TransformResultType<StatusType, Fn, T&&>>
constexpr Result< Ret, StatusType > transform (Fn &&function) &&
 
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, const T & >, int > = 0, typename Ret = internal_result::TransformResultType<StatusType, Fn, const T&>>
constexpr Result< Ret, StatusType > transform (Fn &&function) const &
 
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, const T && >, int > = 0, typename Ret = internal_result::TransformResultType<StatusType, Fn, const T&&>>
constexpr Result< Ret, StatusType > transform (Fn &&function) const &&
 

Friends

struct internal_result::Monadic
 
template<typename U , typename S >
constexpr U && internal::ConvertToValue (Result< U, S > &result) noexcept
 
template<typename U = T, std::enable_if_t< std::is_move_constructible_v< U > &&std::is_swappable_v< U > &&std::is_move_constructible_v< status_type > &&std::is_swappable_v< status_type >, int > = 0>
void swap (Result &lhs, Result &rhs) noexcept
 
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusComparison< U, status_type >, int > = 0>
constexpr bool operator== (const Result &lhs, status_type rhs) noexcept
 
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusComparison< U, status_type >, int > = 0>
constexpr bool operator== (status_type lhs, const Result &rhs) noexcept
 
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusComparison< U, status_type >, int > = 0>
constexpr bool operator!= (const Result &lhs, status_type rhs) noexcept
 
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusComparison< U, status_type >, int > = 0>
constexpr bool operator!= (status_type lhs, const Result &rhs) noexcept
 
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusCodeComparison< U, status_type >, int > = 0>
constexpr bool operator== (const Result &lhs, typename status_type::Code rhs) noexcept
 
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusCodeComparison< U, status_type >, int > = 0>
constexpr bool operator== (typename status_type::Code lhs, const Result &rhs) noexcept
 
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusCodeComparison< U, status_type >, int > = 0>
constexpr bool operator!= (const Result &lhs, typename status_type::Code rhs) noexcept
 
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusCodeComparison< U, status_type >, int > = 0>
constexpr bool operator!= (typename status_type::Code lhs, const Result &rhs) noexcept
 

Member Typedef Documentation

◆ status_type

template<typename T , typename StatusType >
using pw::Result< T, StatusType >::status_type = StatusType

The status type used to represent the status of this Result. Defaults to pw::Status.

◆ value_type

template<typename T , typename StatusType >
using pw::Result< T, StatusType >::value_type = T

Generic value_type member for use within generic programming. This usage is analogous to that of std::optional::value_type.

Constructor & Destructor Documentation

◆ Result() [1/12]

template<typename T , typename StatusType >
template<typename S = StatusType, std::enable_if_t< std::is_same_v< S, Status >, int > = 0>
constexpr pw::Result< T, StatusType >::Result ( )
inlineexplicitconstexprnoexcept

Constructs a new Result<T> with a pw::Status::Unknown() status.

This constructor is marked explicit to prevent usages in return values (e.g. return {}) under the misconception that Result<std::vector<int>> (for example) will be initialized with an empty vector.

Only enabled when StatusType is pw::Status.

◆ Result() [2/12]

template<typename T , typename StatusType >
template<typename S = StatusType, std::enable_if_t< std::is_same_v< S, HasValue >, int > = 0>
constexpr pw::Result< T, StatusType >::Result ( std::nullopt_t  )
inlineconstexprnoexcept

Constructs an empty Optional<T> from std::nullopt (has_value() == false).

◆ Result() [3/12]

template<typename T , typename StatusType >
constexpr pw::Result< T, StatusType >::Result ( const Result< T, StatusType > &  )
constexprdefault

Result<T, StatusType> is copy constructible if T is copy constructible (and trivially copy constructible if T and StatusType are trivially copy constructible).

◆ Result() [4/12]

template<typename T , typename StatusType >
constexpr pw::Result< T, StatusType >::Result ( Result< T, StatusType > &&  )
constexprdefault

Result<T, StatusType> is move constructible if T is move constructible (and trivially move constructible if T and StatusType are trivially move constructible).

◆ Result() [5/12]

template<typename T , typename StatusType >
template<typename U , std::enable_if_t< internal_result::kCanConvertFromResult< T, U, const U &, StatusType, true >, int > = 0>
constexpr pw::Result< T, StatusType >::Result ( const Result< U, StatusType > &  other)
inlineconstexprnoexcept

Constructs a new Result<T, StatusType> from a Result<U, StatusType> when T is constructible from U.

To avoid ambiguity, these constructors are disabled if T is also constructible from Result<U, StatusType>. This constructor is explicit if and only if the corresponding construction of T from U is explicit. (This constructor inherits its explicitness from the underlying constructor.)

◆ Result() [6/12]

template<typename T , typename StatusType >
template<typename U , std::enable_if_t< internal_result::kCanConvertFromStdOptional< T, U, const U &, StatusType, true >, int > = 0>
constexpr pw::Result< T, StatusType >::Result ( const std::optional< U > &  other)
inlineconstexprnoexcept

Constructs an Optional<T> from a std::optional<U> when T is constructible from U.

Disabled unless StatusType is HasValue and T is not constructible or convertible from std::optional<U> directly (except when T is bool; see LWG 3836). Explicit if and only if converting U to T is explicit.

◆ Result() [7/12]

template<typename T , typename StatusType >
template<typename U , std::enable_if_t< internal_result::kCanConvertFromStdOptional< T, U, const U &, StatusType, false >, int > = 0>
constexpr pw::Result< T, StatusType >::Result ( const std::optional< U > &  other)
inlineexplicitconstexprnoexcept

◆ Result() [8/12]

template<typename T , typename StatusType >
template<typename U , std::enable_if_t< internal_result::kCanConvertFromStdOptional< T, U, U &&, StatusType, true >, int > = 0>
constexpr pw::Result< T, StatusType >::Result ( std::optional< U > &&  other)
inlineconstexprnoexcept

◆ Result() [9/12]

template<typename T , typename StatusType >
template<typename U , std::enable_if_t< internal_result::kCanConvertFromStdOptional< T, U, U &&, StatusType, false >, int > = 0>
constexpr pw::Result< T, StatusType >::Result ( std::optional< U > &&  other)
inlineexplicitconstexprnoexcept

◆ Result() [10/12]

template<typename T , typename StatusType >
template<typename U = status_type, std::enable_if_t< internal_result::kCanConstructFromStatus< T, U &&, StatusType, true >, int > = 0>
constexpr pw::Result< T, StatusType >::Result ( U &&  v)
inlineconstexpr

Constructs a new Result<T, StatusType> with a non-OK status.

After calling this constructor, this->ok() will be false and calls to value() will trigger a PW_ASSERT.

The constructor takes any type U that is constructible/convertible to status_type. This constructor is explicit if and only if U is not implicitly convertible to status_type.

Disabled when T is StatusType (in which case constructing from a status initializes the contained value; use reset() to set an error status).

Precondition
!status_type(std::forward<U>(v)).ok(). This requirement is asserted via PW_ASSERT.

◆ Result() [11/12]

template<typename T , typename StatusType >
template<typename... Args, std::enable_if_t< std::is_constructible_v< T, Args... >, int > = 0>
constexpr pw::Result< T, StatusType >::Result ( std::in_place_t  ,
Args &&...  args 
)
inlineexplicitconstexprnoexcept

Constructs the inner value T in-place using the provided args, using the T(args...) constructor.

◆ Result() [12/12]

template<typename T , typename StatusType >
template<typename U = std::remove_cv_t<T>, std::enable_if_t< internal_result::kCanConstructFromValue< T, U &&, StatusType, true >, int > = 0>
constexpr pw::Result< T, StatusType >::Result ( U &&  u)
inlineconstexprnoexcept

Constructs the inner value T in-place using the provided arg, using the T(U) (direct-initialization) constructor.

Precondition
This constructor is only valid if T can be constructed from a U. Can accept move or copy constructors.

This constructor is explicit if U is not convertible to T. To avoid ambiguity, this constructor is disabled if U is a Result<J, StatusType>, where J is convertible to T.

Member Function Documentation

◆ and_then() [1/4]

template<typename T , typename StatusType >
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, T & >, int > = 0, typename Ret = internal_result::InvokeResultType<Fn, T&>>
constexpr Ret pw::Result< T, StatusType >::and_then ( Fn &&  function) &
inlineconstexpr
Returns
The Result from invoking function on the held value if ok(). Otherwise, returns a Result with the contained error status.

◆ and_then() [2/4]

template<typename T , typename StatusType >
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, T && >, int > = 0, typename Ret = internal_result::InvokeResultType<Fn, T&&>>
constexpr Ret pw::Result< T, StatusType >::and_then ( Fn &&  function) &&
inlineconstexpr

Returns
The Result from invoking function on the held value if ok(). Otherwise, returns a Result with the contained error status.

◆ and_then() [3/4]

template<typename T , typename StatusType >
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, const T & >, int > = 0, typename Ret = internal_result::InvokeResultType<Fn, const T&>>
constexpr Ret pw::Result< T, StatusType >::and_then ( Fn &&  function) const &
inlineconstexpr

Returns
The Result from invoking function on the held value if ok(). Otherwise, returns a Result with the contained error status.

◆ and_then() [4/4]

template<typename T , typename StatusType >
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, const T && >, int > = 0, typename Ret = internal_result::InvokeResultType<Fn, const T&&>>
constexpr Ret pw::Result< T, StatusType >::and_then ( Fn &&  function) const &&
inlineconstexpr

Returns
The Result from invoking function on the held value if ok(). Otherwise, returns a Result with the contained error status.

◆ emplace() [1/2]

template<typename T , typename StatusType >
template<typename... Args, std::enable_if_t< std::is_constructible_v< T, Args... >, int > = 0>
constexpr T & pw::Result< T, StatusType >::emplace ( Args &&...  args)
inlineconstexprnoexcept

Reconstructs the inner value T in-place using the provided args, using the T(args...) constructor.

Returns
A reference to the reconstructed T.

◆ emplace() [2/2]

template<typename T , typename StatusType >
template<typename U , typename... Args, std::enable_if_t< std::is_constructible_v< T, std::initializer_list< U > &, Args... >, int > = 0>
constexpr T & pw::Result< T, StatusType >::emplace ( std::initializer_list< U >  ilist,
Args &&...  args 
)
inlineconstexprnoexcept

Reconstructs the inner value T in-place using the provided args, using the T(args...) constructor.

Returns
A reference to the reconstructed T.

◆ has_value()

template<typename T , typename StatusType >
constexpr bool pw::Result< T, StatusType >::has_value ( ) const
inlineconstexprnoexcept
Returns
true if this Result<T, StatusType> holds a T value (ok() == true). Provided for compatibility with std::optional.

◆ IgnoreError()

template<typename T , typename StatusType >
constexpr void pw::Result< T, StatusType >::IgnoreError ( ) const
inlineconstexprnoexcept

Ignores any errors. This method does nothing except potentially suppress complaints from any tools that are checking that errors are not dropped.

◆ ok()

template<typename T , typename StatusType >
constexpr bool pw::Result< T, StatusType >::ok ( ) const
inlineconstexprnoexcept
Returns
Whether or not this Result<T, StatusType> holds a T value. This member function is analogous to Status::ok() and should be used similarly to check the status of return values.

Example:

Result<Foo> result = DoBigCalculationThatCouldFail();
if (result.ok()) {
// Handle result
} else {
// Handle error
}

◆ operator bool()

template<typename T , typename StatusType >
template<typename S = StatusType, std::enable_if_t< std::is_same_v< S, HasValue >, int > = 0>
constexpr pw::Result< T, StatusType >::operator bool ( ) const
inlineexplicitconstexprnoexcept

Explicit boolean conversion operator for Optional<T>. Returns true if a value is present (has_value() == true).

◆ operator*() [1/4]

template<typename T , typename StatusType >
constexpr T && pw::Result< T, StatusType >::operator* ( ) &&
inlineconstexprnoexcept

Returns
A reference to the current value. Only checks if a value is present if PW_ASSERT_ENABLE_DEBUG is enabled (via PW_DASSERT).
Precondition
this->ok() == true, otherwise the behavior is undefined.

Use this->ok() to verify that there is a current value within the Result<T, StatusType>. Alternatively, see the value() member function for a similar API that guarantees crashing if there is no current value.

◆ operator*() [2/4]

template<typename T , typename StatusType >
constexpr T & pw::Result< T, StatusType >::operator* ( ) &
inlineconstexprnoexcept

Returns
A reference to the current value. Only checks if a value is present if PW_ASSERT_ENABLE_DEBUG is enabled (via PW_DASSERT).
Precondition
this->ok() == true, otherwise the behavior is undefined.

Use this->ok() to verify that there is a current value within the Result<T, StatusType>. Alternatively, see the value() member function for a similar API that guarantees crashing if there is no current value.

◆ operator*() [3/4]

template<typename T , typename StatusType >
constexpr const T && pw::Result< T, StatusType >::operator* ( ) const &&
inlineconstexprnoexcept

Returns
A reference to the current value. Only checks if a value is present if PW_ASSERT_ENABLE_DEBUG is enabled (via PW_DASSERT).
Precondition
this->ok() == true, otherwise the behavior is undefined.

Use this->ok() to verify that there is a current value within the Result<T, StatusType>. Alternatively, see the value() member function for a similar API that guarantees crashing if there is no current value.

◆ operator*() [4/4]

template<typename T , typename StatusType >
constexpr const T & pw::Result< T, StatusType >::operator* ( ) const &
inlineconstexprnoexcept
Returns
A reference to the current value. Only checks if a value is present if PW_ASSERT_ENABLE_DEBUG is enabled (via PW_DASSERT).
Precondition
this->ok() == true, otherwise the behavior is undefined.

Use this->ok() to verify that there is a current value within the Result<T, StatusType>. Alternatively, see the value() member function for a similar API that guarantees crashing if there is no current value.

◆ operator->() [1/2]

template<typename T , typename StatusType >
constexpr const T * pw::Result< T, StatusType >::operator-> ( ) const
inlineconstexprnoexcept
Returns
A pointer to the current value. Only checks if a value is present if PW_ASSERT_ENABLE_DEBUG is enabled (via PW_DASSERT).
Precondition
this->ok() == true, otherwise the behavior is undefined.

Use this->ok() to verify that there is a current value.

◆ operator->() [2/2]

template<typename T , typename StatusType >
constexpr T * pw::Result< T, StatusType >::operator-> ( )
inlineconstexprnoexcept

Returns
A pointer to the current value. Only checks if a value is present if PW_ASSERT_ENABLE_DEBUG is enabled (via PW_DASSERT).
Precondition
this->ok() == true, otherwise the behavior is undefined.

Use this->ok() to verify that there is a current value.

◆ operator=() [1/6]

template<typename T , typename StatusType >
constexpr Result & pw::Result< T, StatusType >::operator= ( const Result< T, StatusType > &  )
constexprdefault

Result<T, StatusType> is copy assignable if T is copy constructible and copy assignable (and trivially copy assignable if T and StatusType are trivially destructible, copy constructible, and copy assignable).

◆ operator=() [2/6]

template<typename T , typename StatusType >
template<typename U , std::enable_if_t< internal_result::kCanAssignFromResult< T, U, const U &, StatusType >, int > = 0>
constexpr Result & pw::Result< T, StatusType >::operator= ( const Result< U, StatusType > &  other)
inlineconstexprnoexcept

Assigns a Result<T, StatusType> from a Result<U, StatusType>.

Precondition
These overloads only apply if Result<T, StatusType> is constructible and assignable from Result<U, StatusType> and Result<T, StatusType> cannot be directly assigned from Result<U, StatusType>.
If both Result<T, StatusType> and Result<U, StatusType> are OK, assigns U to T directly.
If Result<T, StatusType> is OK and Result<U, StatusType> contains an error code, destroys the value of Result<T, StatusType> and assigns the error status from Result<U, StatusType>.
If Result<T, StatusType> contains an error code and Result<U, StatusType> is OK, directly initializes T from U.
If both Result<T, StatusType> and Result<U, StatusType> contain an error code, assigns the status in Result<U, StatusType> to Result<T, StatusType>.

◆ operator=() [3/6]

template<typename T , typename StatusType >
constexpr Result & pw::Result< T, StatusType >::operator= ( Result< T, StatusType > &&  )
constexprdefault

Result<T, StatusType> is move assignable if T is move constructible and move assignable (and trivially move assignable if T and StatusType are trivially destructible, move constructible, and move assignable).

◆ operator=() [4/6]

template<typename T , typename StatusType >
template<typename U , std::enable_if_t< internal_result::kCanAssignFromStdOptional< T, U, U &&, StatusType >, int > = 0>
constexpr Result & pw::Result< T, StatusType >::operator= ( std::optional< U > &&  other)
inlineconstexprnoexcept

Assigns an Optional<T> from a std::optional<U>.

◆ operator=() [5/6]

template<typename T , typename StatusType >
template<typename U = status_type, std::enable_if_t< internal_result::kCanAssignFromStatus< T, U &&, StatusType >, int > = 0>
constexpr Result & pw::Result< T, StatusType >::operator= ( U &&  v)
inlineconstexpr

Assigns a non-OK status to this Result<T, StatusType>, destroying any currently held value.

Disabled when T is StatusType (in which case assigning a status updates the contained value; use reset() to set an error status).

Precondition
!status_type(std::forward<U>(v)).ok(). This requirement is asserted via PW_ASSERT.

◆ operator=() [6/6]

template<typename T , typename StatusType >
template<typename U = std::remove_cv_t<T>, typename = std::enable_if_t< internal_result::kCanAssignFromValue<T, U&&, StatusType>>>
constexpr Result & pw::Result< T, StatusType >::operator= ( U &&  v)
inlineconstexprnoexcept

Perfect-forwarding value assignment operator.

If *this contains a T value before the call, the contained value is assigned from std::forward<U>(v). Otherwise, it is directly initialized from std::forward<U>(v).

Precondition
std::is_constructible_v<T, U> is true.
std::is_assignable_v<T&, U> is true.
std::is_same_v<Result<T, StatusType>, std::remove_cvref_t<U>> is false.
Assigning U to T is not ambiguous. If U is Result<V, StatusType> and T is constructible and assignable from both Result<V, StatusType> and V, the assignment is considered bug-prone and ambiguous and thus will fail to compile. For example:
Result<bool> s1 = true; // s1.ok() && *s1 == true
Result<bool> s2 = false; // s2.ok() && *s2 == false
s1 = s2; // ambiguous, `s1 = *s2` or `s1 = bool(s2)`?

◆ or_else() [1/2]

template<typename T , typename StatusType >
template<typename Fn , typename U = T, typename S = status_type, std::enable_if_t< std::is_move_constructible_v< U > &&std::is_move_constructible_v< S > &&internal_result::kIsOrElseInvocable< Fn, status_type && >, int > = 0>
constexpr Result< T, StatusType > pw::Result< T, StatusType >::or_else ( Fn &&  function) &&
inlineconstexpr

Returns
This Result<T, StatusType> if it has a value, otherwise invokes the given function with status() (if invocable with status_type) or with zero arguments. The function must return a type convertible to Result<T, StatusType> or void.

◆ or_else() [2/2]

template<typename T , typename StatusType >
template<typename Fn , typename U = T, typename S = status_type, std::enable_if_t< std::is_copy_constructible_v< U > &&std::is_copy_constructible_v< S > &&internal_result::kIsOrElseInvocable< Fn, const status_type & >, int > = 0>
constexpr Result< T, StatusType > pw::Result< T, StatusType >::or_else ( Fn &&  function) const &
inlineconstexpr
Returns
This Result<T, StatusType> if it has a value, otherwise invokes the given function with status() (if invocable with status_type) or with zero arguments. The function must return a type convertible to Result<T, StatusType> or void.

◆ reset() [1/4]

template<typename T , typename StatusType >
template<typename S = StatusType, std::enable_if_t< std::is_same_v< S, HasValue >, int > = 0>
constexpr void pw::Result< T, StatusType >::reset ( )
inlineconstexprnoexcept

Destroys the contained value, if any, and resets an Optional<T> to an empty state (has_value() == false).

◆ reset() [2/4]

template<typename T , typename StatusType >
template<typename status_type::Code kCode>
constexpr void pw::Result< T, StatusType >::reset ( )
inlineconstexprnoexcept

Destroys the contained value, if any, and resets an Optional<T> to an empty state (has_value() == false).

◆ reset() [3/4]

template<typename T , typename StatusType >
template<typename C , typename S = StatusType, std::enable_if_t<!std::is_same_v< S, HasValue > &&std::is_same_v< C, typename S::Code >, int > = 0>
constexpr void pw::Result< T, StatusType >::reset ( C  code)
inlineconstexpr

Destroys the contained value, if any, and resets an Optional<T> to an empty state (has_value() == false).

◆ reset() [4/4]

template<typename T , typename StatusType >
template<typename S = StatusType, std::enable_if_t<!std::is_same_v< S, HasValue >, int > = 0>
constexpr void pw::Result< T, StatusType >::reset ( status_type  error_status)
inlineconstexpr

Destroys the contained value, if any, and sets the status. The status must not be OK. To avoid a runtime check, use the reset<kCode>() function template whenever possible.

◆ status()

template<typename T , typename StatusType >
constexpr status_type pw::Result< T, StatusType >::status ( ) const
inlineconstexprnoexcept
Returns
The current status_type contained within the Result<T, StatusType>. If Result<T, StatusType> contains a T, then this function returns an OK status (ok() == true).

◆ std_optional() [1/2]

template<typename T , typename StatusType >
template<typename S = StatusType, typename U = std::remove_cv_t<T>, std::enable_if_t< std::is_same_v< S, HasValue > &&std::is_constructible_v< U, T && >, int > = 0>
constexpr std::optional< U > pw::Result< T, StatusType >::std_optional ( ) &&
inlineconstexprnoexcept

Converts an Optional<T> (Result<T, HasValue>) to a std::optional<std::remove_cv_t<T>>.

This is a named method rather than a conversion operator because std::optional's forwarding constructor optional(U&&) is an exact match in direct-initialization (e.g. std::optional<bool> s(opt)) and would construct the bool from explicit operator bool(), yielding has_value() instead of the held value.

◆ std_optional() [2/2]

template<typename T , typename StatusType >
template<typename S = StatusType, typename U = std::remove_cv_t<T>, std::enable_if_t< std::is_same_v< S, HasValue > &&std::is_constructible_v< U, const T & >, int > = 0>
constexpr std::optional< U > pw::Result< T, StatusType >::std_optional ( ) const &
inlineconstexprnoexcept

Converts an Optional<T> (Result<T, HasValue>) to a std::optional<std::remove_cv_t<T>>.

This is a named method rather than a conversion operator because std::optional's forwarding constructor optional(U&&) is an exact match in direct-initialization (e.g. std::optional<bool> s(opt)) and would construct the bool from explicit operator bool(), yielding has_value() instead of the held value.

◆ transform() [1/4]

template<typename T , typename StatusType >
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, T & >, int > = 0, typename Ret = internal_result::TransformResultType<StatusType, Fn, T&>>
constexpr Result< Ret, StatusType > pw::Result< T, StatusType >::transform ( Fn &&  function) &
inlineconstexpr
Returns
A Result<U, StatusType> containing the result of invoking function on the held value if *this contains a value. Otherwise, returns a Result<U, StatusType> with the same status as *this.

For Optional<T> (StatusType is HasValue), function must return a non-reference, non-void, non-array object type other than std::in_place_t or std::nullopt_t (matching std::optional::transform).

◆ transform() [2/4]

template<typename T , typename StatusType >
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, T && >, int > = 0, typename Ret = internal_result::TransformResultType<StatusType, Fn, T&&>>
constexpr Result< Ret, StatusType > pw::Result< T, StatusType >::transform ( Fn &&  function) &&
inlineconstexpr

Returns
A Result<U, StatusType> containing the result of invoking function on the held value if *this contains a value. Otherwise, returns a Result<U, StatusType> with the same status as *this.

For Optional<T> (StatusType is HasValue), function must return a non-reference, non-void, non-array object type other than std::in_place_t or std::nullopt_t (matching std::optional::transform).

◆ transform() [3/4]

template<typename T , typename StatusType >
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, const T & >, int > = 0, typename Ret = internal_result::TransformResultType<StatusType, Fn, const T&>>
constexpr Result< Ret, StatusType > pw::Result< T, StatusType >::transform ( Fn &&  function) const &
inlineconstexpr

Returns
A Result<U, StatusType> containing the result of invoking function on the held value if *this contains a value. Otherwise, returns a Result<U, StatusType> with the same status as *this.

For Optional<T> (StatusType is HasValue), function must return a non-reference, non-void, non-array object type other than std::in_place_t or std::nullopt_t (matching std::optional::transform).

◆ transform() [4/4]

template<typename T , typename StatusType >
template<typename Fn , std::enable_if_t< std::is_invocable_v< Fn, const T && >, int > = 0, typename Ret = internal_result::TransformResultType<StatusType, Fn, const T&&>>
constexpr Result< Ret, StatusType > pw::Result< T, StatusType >::transform ( Fn &&  function) const &&
inlineconstexpr

Returns
A Result<U, StatusType> containing the result of invoking function on the held value if *this contains a value. Otherwise, returns a Result<U, StatusType> with the same status as *this.

For Optional<T> (StatusType is HasValue), function must return a non-reference, non-void, non-array object type other than std::in_place_t or std::nullopt_t (matching std::optional::transform).

◆ value() [1/4]

template<typename T , typename StatusType >
constexpr T && pw::Result< T, StatusType >::value ( ) &&
inlineconstexpr

Returns
A reference to the held value if this->ok(). Otherwise, terminates the process via PW_ASSERT.

If you have already checked the status using this->ok(), you probably want to use operator*() or operator->() to access the value instead of value.

For value types that are cheap to copy, prefer simple code:

T value = result.value();

Otherwise, if the value type is expensive to copy, but can be left in the Result<T, StatusType>, simply assign to a reference:

T& value = result.value(); // or `const T&`

Otherwise, if the value type supports an efficient move, it can be used as follows:

T value = std::move(result).value();

The std::move on result instead of on the whole expression enables warnings about possible uses of the result object after the move.

◆ value() [2/4]

template<typename T , typename StatusType >
constexpr T & pw::Result< T, StatusType >::value ( ) &
inlineconstexpr

Returns
A reference to the held value if this->ok(). Otherwise, terminates the process via PW_ASSERT.

If you have already checked the status using this->ok(), you probably want to use operator*() or operator->() to access the value instead of value.

For value types that are cheap to copy, prefer simple code:

T value = result.value();

Otherwise, if the value type is expensive to copy, but can be left in the Result<T, StatusType>, simply assign to a reference:

T& value = result.value(); // or `const T&`

Otherwise, if the value type supports an efficient move, it can be used as follows:

T value = std::move(result).value();

The std::move on result instead of on the whole expression enables warnings about possible uses of the result object after the move.

◆ value() [3/4]

template<typename T , typename StatusType >
constexpr const T && pw::Result< T, StatusType >::value ( ) const &&
inlineconstexpr

Returns
A reference to the held value if this->ok(). Otherwise, terminates the process via PW_ASSERT.

If you have already checked the status using this->ok(), you probably want to use operator*() or operator->() to access the value instead of value.

For value types that are cheap to copy, prefer simple code:

T value = result.value();

Otherwise, if the value type is expensive to copy, but can be left in the Result<T, StatusType>, simply assign to a reference:

T& value = result.value(); // or `const T&`

Otherwise, if the value type supports an efficient move, it can be used as follows:

T value = std::move(result).value();

The std::move on result instead of on the whole expression enables warnings about possible uses of the result object after the move.

◆ value() [4/4]

template<typename T , typename StatusType >
constexpr const T & pw::Result< T, StatusType >::value ( ) const &
inlineconstexpr
Returns
A reference to the held value if this->ok(). Otherwise, terminates the process via PW_ASSERT.

If you have already checked the status using this->ok(), you probably want to use operator*() or operator->() to access the value instead of value.

For value types that are cheap to copy, prefer simple code:

T value = result.value();

Otherwise, if the value type is expensive to copy, but can be left in the Result<T, StatusType>, simply assign to a reference:

T& value = result.value(); // or `const T&`

Otherwise, if the value type supports an efficient move, it can be used as follows:

T value = std::move(result).value();

The std::move on result instead of on the whole expression enables warnings about possible uses of the result object after the move.

◆ value_or() [1/2]

template<typename T , typename StatusType >
template<typename U = std::remove_cv_t<T>>
constexpr std::remove_cv_t< T > pw::Result< T, StatusType >::value_or ( U &&  default_value) &&
inlineconstexprnoexcept

Returns
The current value if this->ok() == true. Otherwise constructs a value using the provided default_value.

Unlike value, this function returns by value, copying the current value if necessary. If the value type supports an efficient move, it can be used as follows:

T value = std::move(result).value_or(def);

Unlike with value, calling std::move() on the result of value_or will still trigger a copy.

◆ value_or() [2/2]

template<typename T , typename StatusType >
template<typename U = std::remove_cv_t<T>>
constexpr std::remove_cv_t< T > pw::Result< T, StatusType >::value_or ( U &&  default_value) const &
inlineconstexprnoexcept
Returns
The current value if this->ok() == true. Otherwise constructs a value using the provided default_value.

Unlike value, this function returns by value, copying the current value if necessary. If the value type supports an efficient move, it can be used as follows:

T value = std::move(result).value_or(def);

Unlike with value, calling std::move() on the result of value_or will still trigger a copy.

Friends And Related Function Documentation

◆ operator!= [1/4]

template<typename T , typename StatusType >
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusComparison< U, status_type >, int > = 0>
constexpr bool operator!= ( const Result< T, StatusType > &  lhs,
status_type  rhs 
)
friend

Compares the status of a Result<T, StatusType> with a status. A Result holding a value compares equal to an OK status.

Disabled when T is StatusType (in which case operator== compares against the held StatusType value).

◆ operator!= [2/4]

template<typename T , typename StatusType >
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusCodeComparison< U, status_type >, int > = 0>
constexpr bool operator!= ( const Result< T, StatusType > &  lhs,
typename status_type::Code  rhs 
)
friend

Compares the status of a Result<T, StatusType> with a status. A Result holding a value compares equal to an OK status.

Disabled when T is StatusType (in which case operator== compares against the held StatusType value).

◆ operator!= [3/4]

template<typename T , typename StatusType >
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusComparison< U, status_type >, int > = 0>
constexpr bool operator!= ( status_type  lhs,
const Result< T, StatusType > &  rhs 
)
friend

Compares the status of a Result<T, StatusType> with a status. A Result holding a value compares equal to an OK status.

Disabled when T is StatusType (in which case operator== compares against the held StatusType value).

◆ operator!= [4/4]

template<typename T , typename StatusType >
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusCodeComparison< U, status_type >, int > = 0>
constexpr bool operator!= ( typename status_type::Code  lhs,
const Result< T, StatusType > &  rhs 
)
friend

Compares the status of a Result<T, StatusType> with a status. A Result holding a value compares equal to an OK status.

Disabled when T is StatusType (in which case operator== compares against the held StatusType value).

◆ operator== [1/4]

template<typename T , typename StatusType >
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusComparison< U, status_type >, int > = 0>
constexpr bool operator== ( const Result< T, StatusType > &  lhs,
status_type  rhs 
)
friend

Compares the status of a Result<T, StatusType> with a status. A Result holding a value compares equal to an OK status.

Disabled when T is StatusType (in which case operator== compares against the held StatusType value).

◆ operator== [2/4]

template<typename T , typename StatusType >
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusCodeComparison< U, status_type >, int > = 0>
constexpr bool operator== ( const Result< T, StatusType > &  lhs,
typename status_type::Code  rhs 
)
friend

Compares the status of a Result<T, StatusType> with a status code.

Disabled when T is StatusType or StatusType::Code (in which case operator== compares against the held value).

◆ operator== [3/4]

template<typename T , typename StatusType >
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusComparison< U, status_type >, int > = 0>
constexpr bool operator== ( status_type  lhs,
const Result< T, StatusType > &  rhs 
)
friend

Compares the status of a Result<T, StatusType> with a status. A Result holding a value compares equal to an OK status.

Disabled when T is StatusType (in which case operator== compares against the held StatusType value).

◆ operator== [4/4]

template<typename T , typename StatusType >
template<typename U = T, std::enable_if_t< internal_result::kEnableStatusCodeComparison< U, status_type >, int > = 0>
constexpr bool operator== ( typename status_type::Code  lhs,
const Result< T, StatusType > &  rhs 
)
friend

Compares the status of a Result<T, StatusType> with a status. A Result holding a value compares equal to an OK status.

Disabled when T is StatusType (in which case operator== compares against the held StatusType value).

◆ swap

template<typename T , typename StatusType >
template<typename U = T, std::enable_if_t< std::is_move_constructible_v< U > &&std::is_swappable_v< U > &&std::is_move_constructible_v< status_type > &&std::is_swappable_v< status_type >, int > = 0>
void swap ( Result< T, StatusType > &  lhs,
Result< T, StatusType > &  rhs 
)
friend

Swaps two Result<T, StatusType> objects via ADL. Only participates in overload resolution if T is move-constructible and swappable.


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