#include "tensorstore/util/result.h"
template <typename T>
class [[nodiscard]] tensorstore::Result;

Result<T> implements a value-or-error concept providing a discriminated union of a usable value, T, or an absl::Status error describing why the value is not present. Result<void> is permitted, which becomes a wrapper for absl::Status, and which enables use of Result<T> in a wide variety of template contexts.

The primary use case for Result<T> is as the return value of a function which may fail.

Initialization with a non-error absl::Status is only allowed for Result<void>, otherwise non-error absl::Status initilization is nonsensical because it does not provide a value.

Conversion from Result<T> to Result<void> is allowed; the status is retained but any value is discarded by such a conversion.

Assignment operators always destroy the existing value and reconstruct the value. This may be surprising, since it is unlike std::optional and many other monadic C++ types.

There are quite a few similar classes extant:

Example:

Result<Foo> result = GetTheStuff();
if (!result) {
   return result.status();
}
result->DoTheStuff();
Template Parameters:
typename T

Contained value type, or void to indicate no contained value. Must not be a reference type or cv-qualified.

Types

using value_type = T;

The type of the contained success value.

using reference_type = T&;

Equal to T&, or void if T is void.

using const_reference_type = const T&;

Equal to const T&, or void if T is void.

using error_type = absl::Status;

Always equal to absl::Status.

Constructors

explicit Result();

Constructs an error Result with a code of absl::StatusCode::kUnknown.

Result(const Result& src);
Result(Result&& src);

Constructs from an existing result.

Result(const absl::Status& status);
Result(absl::Status&& status);

Constructs from a status object.

Result(const Result<U>& rhs);
Result(Result<U>&& rhs);

Constructs from an existing result with a convertible value type.

Result(std::in_place_t, Args&&... args);
Result(std::in_place_t, std::initializer_list<U> il, Args&&... args);

Directly constructs the contained value from the specified arguments.

Result(U&& v);

Constructs the contained value from a convertible value.

Methods

Result& operator=(const Result& src) = default;
Result& operator=(Result&& src) = default;

Assigns from an existing result.

Result& operator=(const absl::Status& status);
Result& operator=(absl::Status&& status);

Assigns from a status object.

Result& operator=(const Result<U>& rhs);
Result& operator=(Result<U>&& rhs);

Assigns from an existing result with a convertible value type.

Result& operator=(U&& v);

Assigns the contained value from a convertible value.

T& emplace(Args&&... args);
T& emplace(std::initializer_list<U> il, Args&&... args);

Reconstructs the contained value in-place with the given forwarded arguments.

void IgnoreResult() const;

Ignores the result. This method signals intent to ignore the result to suppress compiler warnings from [[nodiscard]].

bool ok() const;
bool has_value() const;
explicit operator bool() const noexcept;

Returns true if this represents a success state, false for a failure state.

const T& value() const& noexcept;
T& value() & noexcept;
const T&& value() const&& noexcept;
T&& value() && noexcept;

Checked value accessor.

const absl::Status& status() const& noexcept;
absl::Status status() && noexcept;

Returns the error status.

constexpr const T* operator->() const noexcept;
constexpr T* operator->() noexcept;

Returns a pointer to the contained value.

constexpr const T& operator*() const& noexcept;
constexpr T& operator*() & noexcept;
constexpr const T&& operator*() const&& noexcept;
constexpr T&& operator*() && noexcept;

Returns a reference to the contained value.

FlatResult<std::invoke_result_t<Func&&, T&>>
operator|(Func&& func) const&;
FlatResult<std::invoke_result_t<Func&&, T&&>>
operator|(Func&& func) &&;

“Pipeline” operator for Result.

constexpr T value_or(U&& default_value) const&;
constexpr T value_or(U&& default_value) &&;

Returns the contained value, or default_value if *this is in an error state.

Friend functions

friend bool operator==(const Result<T>& a, const Result<U>& b);
friend bool operator==(const Result<T>& a, const U& b);
friend bool operator==(const U& a, const Result<T>& b);

Compares two results for equality.

friend bool operator!=(const Result<T>& a, const Result<U>& b);
friend bool operator!=(const Result<T>& a, const U& b);
friend bool operator!=(const U& a, const Result<T>& b);

Checks if two Result values are not equal.

TENSORSTORE_ASSIGN_OR_RETURN(decl, ...);

Convenience macro for propagating errors when calling a function that returns a tensorstore::Result.

TENSORSTORE_CHECK_OK_AND_ASSIGN(decl, ...);

Convenience macro for checking errors when calling a function that returns a tensorstore::Result.

Test support

TENSORSTORE_EXPECT_OK(expr);

EXPECT assertion that the argument, when converted to an absl::Status via tensorstore::GetStatus, has a code of absl::StatusCode::kOk.

TENSORSTORE_ASSERT_OK(expr);

Same as TENSORSTORE_EXPECT_OK, but returns in the case of an error.

TENSORSTORE_ASSERT_OK_AND_ASSIGN(decl, expr);

ASSERTs that expr is a tensorstore::Result with a value, and assigns the value to decl.

const absl::Status&
tensorstore::GetStatus(const absl::Status& status);
absl::Status tensorstore::GetStatus(absl::Status&& status);

Overload for the case of a bare absl::Status argument.

Result<void> tensorstore::MakeResult();
Result<typename std::remove_cvref_t<T>>
tensorstore::MakeResult(T&& t);
Result<U> tensorstore::MakeResult(Args&&... args);

Returns a Result<T> with a (possibly-default) value.

Result<void> tensorstore::MakeResult(absl::Status status);
Result<U> tensorstore::MakeResult(absl::Status status);

Returns a Result corresponding to a success or error status.

absl::Status tensorstore::GetStatus(const Result<T>& result);
absl::Status tensorstore::GetStatus(Result<T>&& result);

Returns the error status of Result, or absl::OkStatus() if Result has a value.

T&& tensorstore::UnwrapResult(T&& t);
const T& tensorstore::UnwrapResult(const Result<T>& t);
T& tensorstore::UnwrapResult(Result<T>& t);
T&& tensorstore::UnwrapResult(Result<T>&& t);

UnwrapResult returns the value contained by the Result<T> instance, *t, or the value, t.

FlatResult<
    std::invoke_result_t<Func&&, UnwrapQualifiedResultType<T>...>>
tensorstore::MapResult(Func&& func, T&&... arg);

Tries to call func with Result-wrapped arguments.

auto tensorstore::ChainResult(T&& arg);
auto tensorstore::ChainResult(T&& arg, Func0&& func0, Func&&... func);

Applies a sequence of functions, which may optionally return Result-wrapped values, to an optionally Result-wrapped value.

constexpr bool tensorstore::IsResult<T>;

IsResult evaluates to true if T is an instance of Result.

using tensorstore::UnwrapResultType<T>;

UnwrapResultType<T> maps

using tensorstore::UnwrapQualifiedResultType<T>;

As above, preserving const / volatile / reference qualifiers.

using tensorstore::FlatResult<T>;

FlatResult<T> maps

using tensorstore::FlatMapResultType<MapType, T...> =
    Result<MapType<UnwrapResultType<T>...>>;

Type alias that maps Result<T> to Result<U>, where U = MapType<U>.

using tensorstore::PipelineResultType<T, Func> =
    std::invoke_result_t<Func&&, T>;

Type alias used by initial overloads of the “Pipeline” operator|.