Result.h

浏览该文件的文档.

#pragma once
 
#include "common/Assert.h"
#include "common/Status.h"
 
#include <exception>
#include <functional>
#include <optional>
#include <string>
#include <string_view>
#include <type_traits>
#include <utility>
#include <vector>
 
namespace eve {
namespace detail {
 
class ResultObservation {
public:
    ResultObservation() noexcept = default;
 
    ResultObservation(const ResultObservation&)            = delete;
    ResultObservation& operator=(const ResultObservation&) = delete;
 
    struct InactiveTag {};
    explicit ResultObservation(InactiveTag) noexcept {
        mustObserve_ = false;
    }
 
#if !defined(ZEROERR_NO_ASSERT)
    ~ResultObservation() noexcept(false) {
        const bool observationSatisfied = !mustObserve_ || observed_;
        EV_ASSERT(observationSatisfied, "Result destroyed without checking; inspect it or call ignore() explicitly");
    }
#else
    ~ResultObservation() noexcept = default;
#endif
 
protected:
    void observe() const noexcept {
#if !defined(ZEROERR_NO_ASSERT)
        observed_ = true;
#endif
    }
 
    void assertCanBeOverwritten() const {
#if !defined(ZEROERR_NO_ASSERT)
        const bool observationSatisfied = !mustObserve_ || observed_;
        EV_ASSERT(observationSatisfied, "move assignment would overwrite an unchecked Result");
#endif
    }
 
    void adoptObservationFrom(ResultObservation& other) noexcept {
#if !defined(ZEROERR_NO_ASSERT)
        observed_          = other.observed_;
        mustObserve_       = other.mustObserve_;
        other.mustObserve_ = false;
#else
        (void)other;
#endif
    }
 
    void disarmObservation() noexcept {
#if !defined(ZEROERR_NO_ASSERT)
        mustObserve_ = false;
#endif
    }
 
    void requireObservation() noexcept {
#if !defined(ZEROERR_NO_ASSERT)
        observed_    = false;
        mustObserve_ = true;
#endif
    }
 
private:
    // Do not condition these fields on ZEROERR_NO_ASSERT. Public Result<T>
    // values cross static/shared-library boundaries whose assertion policy may
    // intentionally differ from the consumer (notably Release unit tests).
    mutable bool observed_    = false;
    bool         mustObserve_ = true;
};
 
template <class T>
using ResultReturn = std::invoke_result_t<T>;
 
template <class From, class To>
concept ResultConstConversion =
    std::is_same_v<To, const From> ||
    (std::is_pointer_v<From> && std::is_same_v<To, const std::remove_pointer_t<From>*>);
 
template <class T, class U>
void moveAssignOptional(std::optional<T>& destination, std::optional<U>&& source) {
    destination.reset();
    if (source.has_value()) destination.emplace(std::move(*source));
}
 
}  // namespace detail
 
template <class T>
class [[nodiscard("Result must be checked or explicitly ignored")]] Result : private detail::ResultObservation {
    static_assert(!std::is_reference_v<T>, "Result<T> cannot hold a reference; use a handle or value");
    static_assert(!std::is_void_v<T>, "Result<void> has a dedicated specialization");
 
    template <class U>
    friend class Result;
 
public:
    static Result success(T value) { return Result(Status::success(), std::optional<T>(std::move(value))); }
 
    static Result success(T value, Status status) {
        EV_ASSERT(status.isSuccess(), "Result::success requires a successful Status");
        return Result(std::move(status), std::optional<T>(std::move(value)));
    }
 
    static Result failure(Status status) {
        EV_ASSERT(status.isFailure(), "Result::failure requires a failure Status");
        return Result(std::move(status), std::nullopt);
    }
 
    static Result failure(Diagnostic diagnostic) { return failure(Status::failure(std::move(diagnostic))); }
 
    Result(const Result&)            = delete;
    Result& operator=(const Result&) = delete;
 
    Result(Result&& other)
        : detail::ResultObservation(detail::ResultObservation::InactiveTag{}),
          status_(std::move(other.status_)),
          value_(std::move(other.value_)) {
        adoptObservationFrom(other);
    }
 
    Result& operator=(Result&& other) {
        if (this == &other) return *this;
        assertCanBeOverwritten();
        status_ = std::move(other.status_);
        detail::moveAssignOptional(value_, std::move(other.value_));
        adoptObservationFrom(other);
        return *this;
    }
 
    template <class U>
        requires detail::ResultConstConversion<U, T>
    Result(Result<U>&& other)
        : detail::ResultObservation(detail::ResultObservation::InactiveTag{}),
          status_(std::move(other.status_)),
          value_(std::optional<T>(std::move(other.value_))) {
        adoptObservationFrom(other);
    }
 
    template <class U>
        requires detail::ResultConstConversion<U, T>
    Result& operator=(Result<U>&& other) {
        assertCanBeOverwritten();
        status_ = std::move(other.status_);
        detail::moveAssignOptional(value_, std::move(other.value_));
        adoptObservationFrom(other);
        return *this;
    }
 
    bool ok() const noexcept {
        observe();
        return status_.isSuccess() && value_.has_value();
    }
 
    bool hasValue() const noexcept {
        observe();
        return status_.isSuccess() && value_.has_value();
    }
 
    const Status& status() const noexcept {
        observe();
        return status_;
    }
 
    StatusCode code() const noexcept {
        observe();
        return status_.code();
    }
 
    const std::vector<Diagnostic>& diagnostics() const noexcept {
        observe();
        return status_.diagnostics();
    }
 
    const Diagnostic* error() const noexcept {
        observe();
        return status_.primaryDiagnostic();
    }
 
    explicit operator bool() const noexcept { return ok(); }
 
    const T& value() const& {
        observe();
        const bool hasSuccessfulValue = status_.isSuccess() && value_.has_value();
        EV_ASSERT(hasSuccessfulValue, "Result::value requires a successful Result with a value");
        return value_.value();
    }
 
    T& value() & {
        observe();
        const bool hasSuccessfulValue = status_.isSuccess() && value_.has_value();
        EV_ASSERT(hasSuccessfulValue, "Result::value requires a successful Result with a value");
        return value_.value();
    }
 
    T&& value() && {
        observe();
        const bool hasSuccessfulValue = status_.isSuccess() && value_.has_value();
        EV_ASSERT(hasSuccessfulValue, "Result::value requires a successful Result with a value");
        return std::move(value_.value());
    }
 
    T takeValue() && {
        observe();
        const bool hasSuccessfulValue = status_.isSuccess() && value_.has_value();
        EV_ASSERT(hasSuccessfulValue, "Result::takeValue requires a successful Result with a value");
        T result = std::move(value_.value());
        value_.reset();
        return result;
    }
 
    T valueOr(T fallback) && {
        observe();
        if (status_.isSuccess() && value_.has_value()) return std::move(value_.value());
        return fallback;
    }
 
    template <class Function>
    auto andThen(Function&& function) && -> std::invoke_result_t<Function, T&&> {
        observe();
        using Return = std::invoke_result_t<Function, T&&>;
        if (!status_.isSuccess() || !value_.has_value()) return Return::failure(status_);
        return std::invoke(std::forward<Function>(function), std::move(value_.value()));
    }
 
    template <class Function>
    Result orElse(Function&& function) && {
        observe();
        if (status_.isSuccess() && value_.has_value()) return std::move(*this);
        return std::invoke(std::forward<Function>(function), status_);
    }
 
    void ignore(std::string_view reason = {}) const noexcept {
        (void)reason;
        observe();
    }
 
    T expect(std::string_view message) && {
        observe();
        if (!status_.isSuccess() || !value_.has_value()) {
            const std::string context(message);
            const std::string detail = status_.describe();
            EV_ASSERT(false, "%s: %s", context.c_str(), detail.c_str());
            std::terminate();
        }
        return std::move(value_.value());
    }
 
private:
    Result(Status status, std::optional<T> value) : status_(std::move(status)), value_(std::move(value)) {}
 
    Status           status_;
    std::optional<T> value_;
};
 
template <>
class [[nodiscard("Result must be checked or explicitly ignored")]] Result<void> : private detail::ResultObservation {
public:
    static Result success() { return Result(Status::success()); }
 
    static Result success(Status status) {
        EV_ASSERT(status.isSuccess(), "Result::success requires a successful Status");
        return Result(std::move(status));
    }
 
    static Result failure(Status status) {
        EV_ASSERT(status.isFailure(), "Result::failure requires a failure Status");
        return Result(std::move(status));
    }
 
    static Result failure(Diagnostic diagnostic) { return failure(Status::failure(std::move(diagnostic))); }
 
    Result(const Result&)            = delete;
    Result& operator=(const Result&) = delete;
 
    Result(Result&& other)
        : detail::ResultObservation(detail::ResultObservation::InactiveTag{}), status_(std::move(other.status_)) {
        adoptObservationFrom(other);
    }
 
    Result& operator=(Result&& other) {
        if (this == &other) return *this;
        assertCanBeOverwritten();
        status_ = std::move(other.status_);
        adoptObservationFrom(other);
        return *this;
    }
 
    bool ok() const noexcept {
        observe();
        return status_.isSuccess();
    }
 
    const Status& status() const noexcept {
        observe();
        return status_;
    }
 
    StatusCode code() const noexcept {
        observe();
        return status_.code();
    }
 
    const std::vector<Diagnostic>& diagnostics() const noexcept {
        observe();
        return status_.diagnostics();
    }
 
    const Diagnostic* error() const noexcept {
        observe();
        return status_.primaryDiagnostic();
    }
 
    explicit operator bool() const noexcept { return ok(); }
 
    void value() const {
        observe();
        EV_ASSERT(status_.isSuccess(), "Result<void>::value requires a successful Result");
    }
 
    void ignore(std::string_view reason = {}) const noexcept {
        (void)reason;
        observe();
    }
 
    void expect(std::string_view message) const {
        observe();
        if (!status_.isSuccess()) {
            const std::string context(message);
            const std::string detail = status_.describe();
            EV_ASSERT(false, "%s: %s", context.c_str(), detail.c_str());
            std::terminate();
        }
    }
 
private:
    explicit Result(Status status) : status_(std::move(status)) {}
 
    Status status_;
};
 
template <typename... Results>
[[nodiscard]] bool everyResultValid(const Results&... results) noexcept {
    static_assert(sizeof...(Results) > 0, "everyResultValid requires at least one Result");
    return (results.ok() & ...);
}
 
}  // namespace eve