result.h

// Copyright 2022 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
//
// -----------------------------------------------------------------------------
// File: result.h
// -----------------------------------------------------------------------------
//
// An `Result<T>` represents a union of an `pw::Status` object and an object of
// type `T`. The `Result<T>` will either contain an object of type `T`
// (indicating a successful operation), or an error (of type `Status`)
// explaining why such a value is not present.
//
// In general, check the success of an operation returning a `Result<T>` like
// you would an `pw::Status` by using the `ok()` member function.
//
// Example:
//
//   Result<Foo> result = Calculation();
//   if (result.ok()) {
//     result->DoSomethingCool();
//   } else {
//     PW_LOG_ERROR("Calculation failed: %s",  result.status().str());
//   }
#pragma once
 
#include <exception>
#include <functional>
#include <initializer_list>
#include <new>
#include <string>
#include <type_traits>
#include <utility>
 
#include "pw_containers/internal/optional_data.h"
#include "pw_preprocessor/compiler.h"
#include "pw_result/internal/result_internal.h"
#include "pw_status/status.h"
 
namespace pw {
 
 
// Returned Result objects may not be ignored.
template <typename T>
class [[nodiscard]] Result;
 
template <typename T>
class Result
    : private containers::internal::OptionalData<T, pw_Status, PW_STATUS_OK>,
      private containers::internal::CopyCtorBase<T>,
      private containers::internal::MoveCtorBase<T>,
      private containers::internal::CopyAssignBase<T>,
      private containers::internal::MoveAssignBase<T> {
  template <typename U>
  friend class Result;
 
  using Base = containers::internal::OptionalData<T, pw_Status, PW_STATUS_OK>;
 
 public:
  typedef T value_type;
 
  // Constructors
 
  explicit constexpr Result();
 
  constexpr Result(const Result&) = default;
  constexpr Result& operator=(const Result&) = default;
 
  constexpr Result(Result&&) = default;
  constexpr Result& operator=(Result&&) = default;
 
  // Converting Constructors
 
  template <
      typename U,
      std::enable_if_t<
          std::conjunction<
              std::negation<std::is_same<T, U>>,
              std::is_constructible<T, const U&>,
              std::is_convertible<const U&, T>,
              std::negation<internal_result::
                                IsConstructibleOrConvertibleFromResult<T, U>>>::
              value,
          int> = 0>
  constexpr Result(const Result<U>& other)  // NOLINT
      : Base(static_cast<const typename Result<U>::Base&>(other)) {}
  template <
      typename U,
      std::enable_if_t<
          std::conjunction<
              std::negation<std::is_same<T, U>>,
              std::is_constructible<T, const U&>,
              std::negation<std::is_convertible<const U&, T>>,
              std::negation<internal_result::
                                IsConstructibleOrConvertibleFromResult<T, U>>>::
              value,
          int> = 0>
  explicit constexpr Result(const Result<U>& other)
      : Base(static_cast<const typename Result<U>::Base&>(other)) {}
 
  template <
      typename U,
      std::enable_if_t<
          std::conjunction<
              std::negation<std::is_same<T, U>>,
              std::is_constructible<T, U&&>,
              std::is_convertible<U&&, T>,
              std::negation<internal_result::
                                IsConstructibleOrConvertibleFromResult<T, U>>>::
              value,
          int> = 0>
  constexpr Result(Result<U>&& other)  // NOLINT
      : Base(static_cast<typename Result<U>::Base&&>(other)) {}
  template <
      typename U,
      std::enable_if_t<
          std::conjunction<
              std::negation<std::is_same<T, U>>,
              std::is_constructible<T, U&&>,
              std::negation<std::is_convertible<U&&, T>>,
              std::negation<internal_result::
                                IsConstructibleOrConvertibleFromResult<T, U>>>::
              value,
          int> = 0>
  explicit constexpr Result(Result<U>&& other)
      : Base(static_cast<typename Result<U>::Base&&>(other)) {}
 
  // Converting Assignment Operators
 
  template <typename U,
            std::enable_if_t<
                std::conjunction<
                    std::negation<std::is_same<T, U>>,
                    std::is_constructible<T, const U&>,
                    std::is_assignable<T, const U&>,
                    std::negation<
                        internal_result::
                            IsConstructibleOrConvertibleOrAssignableFromResult<
                                T,
                                U>>>::value,
                int> = 0>
  constexpr Result& operator=(const Result<U>& other) {
    this->Assign(other);
    return *this;
  }
  template <typename U,
            std::enable_if_t<
                std::conjunction<
                    std::negation<std::is_same<T, U>>,
                    std::is_constructible<T, U&&>,
                    std::is_assignable<T, U&&>,
                    std::negation<
                        internal_result::
                            IsConstructibleOrConvertibleOrAssignableFromResult<
                                T,
                                U>>>::value,
                int> = 0>
  constexpr Result& operator=(Result<U>&& other) {
    this->Assign(std::move(other));
    return *this;
  }
 
  template <
      typename U = Status,
      std::enable_if_t<
          std::conjunction<
              std::is_convertible<U&&, Status>,
              std::is_constructible<Status, U&&>,
              std::negation<std::is_same<std::decay_t<U>, Result<T>>>,
              std::negation<std::is_same<std::decay_t<U>, T>>,
              std::negation<std::is_same<std::decay_t<U>, std::in_place_t>>,
              std::negation<internal_result::
                                HasConversionOperatorToResult<T, U&&>>>::value,
          int> = 0>
  constexpr Result(U&& v)
      : Base(static_cast<Status>(std::forward<U>(v)).code()) {}
 
  template <
      typename U = Status,
      std::enable_if_t<
          std::conjunction<
              std::negation<std::is_convertible<U&&, Status>>,
              std::is_constructible<Status, U&&>,
              std::negation<std::is_same<std::decay_t<U>, Result<T>>>,
              std::negation<std::is_same<std::decay_t<U>, T>>,
              std::negation<std::is_same<std::decay_t<U>, std::in_place_t>>,
              std::negation<internal_result::
                                HasConversionOperatorToResult<T, U&&>>>::value,
          int> = 0>
  constexpr explicit Result(U&& v)
      : Base(static_cast<Status>(std::forward<U>(v)).code()) {}
 
  template <
      typename U = Status,
      std::enable_if_t<
          std::conjunction<
              std::is_convertible<U&&, Status>,
              std::is_constructible<Status, U&&>,
              std::negation<std::is_same<std::decay_t<U>, Result<T>>>,
              std::negation<std::is_same<std::decay_t<U>, T>>,
              std::negation<std::is_same<std::decay_t<U>, std::in_place_t>>,
              std::negation<internal_result::
                                HasConversionOperatorToResult<T, U&&>>>::value,
          int> = 0>
  constexpr Result& operator=(U&& v) {
    this->AssignState(static_cast<Status>(std::forward<U>(v)).code());
    return *this;
  }
 
  template <
      typename U = T,
      typename = typename std::enable_if<std::conjunction<
          std::is_constructible<T, U&&>,
          std::is_assignable<T&, U&&>,
          std::disjunction<
              std::is_same<std::remove_cv_t<std::remove_reference_t<U>>, T>,
              std::conjunction<
                  std::negation<std::is_convertible<U&&, Status>>,
                  std::negation<
                      internal_result::HasConversionOperatorToResult<T, U&&>>>>,
          internal_result::IsForwardingAssignmentValid<T, U&&>>::value>::type>
  constexpr Result& operator=(U&& v) {
    this->Assign(std::forward<U>(v));
    return *this;
  }
 
  template <typename... Args>
  explicit constexpr Result(std::in_place_t, Args&&... args);
  template <typename U, typename... Args>
  explicit constexpr Result(std::in_place_t,
                            std::initializer_list<U> ilist,
                            Args&&... args);
 
  template <
      typename U = T,
      std::enable_if_t<
          std::conjunction<
              internal_result::IsDirectInitializationValid<T, U&&>,
              std::is_constructible<T, U&&>,
              std::is_convertible<U&&, T>,
              std::disjunction<
                  std::is_same<std::remove_cv_t<std::remove_reference_t<U>>, T>,
                  std::conjunction<
                      std::negation<std::is_convertible<U&&, Status>>,
                      std::negation<
                          internal_result::
                              HasConversionOperatorToResult<T, U&&>>>>>::value,
          int> = 0>
  constexpr Result(U&& u)  // NOLINT
      : Result(std::in_place, std::forward<U>(u)) {}
 
  template <
      typename U = T,
      std::enable_if_t<
          std::conjunction<
              internal_result::IsDirectInitializationValid<T, U&&>,
              std::disjunction<
                  std::is_same<std::remove_cv_t<std::remove_reference_t<U>>, T>,
                  std::conjunction<
                      std::negation<std::is_constructible<Status, U&&>>,
                      std::negation<
                          internal_result::
                              HasConversionOperatorToResult<T, U&&>>>>,
              std::is_constructible<T, U&&>,
              std::negation<std::is_convertible<U&&, T>>>::value,
          int> = 0>
  explicit constexpr Result(U&& u)  // NOLINT
      : Result(std::in_place, std::forward<U>(u)) {}
 
  [[nodiscard]] constexpr bool ok() const {
    return this->state_ == OkStatus().code();
  }
 
  constexpr Status status() const;
 
  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& PW_ATTRIBUTE_LIFETIME_BOUND;
  constexpr T& operator*() & PW_ATTRIBUTE_LIFETIME_BOUND;
  constexpr const T&& operator*() const&& PW_ATTRIBUTE_LIFETIME_BOUND;
  constexpr T&& operator*() && PW_ATTRIBUTE_LIFETIME_BOUND;
 
  constexpr const T* operator->() const PW_ATTRIBUTE_LIFETIME_BOUND;
  constexpr T* operator->() PW_ATTRIBUTE_LIFETIME_BOUND;
 
  template <typename U>
  constexpr T value_or(U&& default_value) const&;
  template <typename U>
  constexpr T value_or(U&& default_value) &&;
 
  constexpr void IgnoreError() const;
 
  template <typename... Args>
  T& emplace(Args&&... args) {
    if (ok()) {
      this->Clear();
      this->MakeValue(std::forward<Args>(args)...);
    } else {
      this->MakeValue(std::forward<Args>(args)...);
      this->state_ = OkStatus().code();
    }
    return this->data_;
  }
 
  template <
      typename U,
      typename... Args,
      std::enable_if_t<
          std::is_constructible<T, std::initializer_list<U>&, Args&&...>::value,
          int> = 0>
  T& emplace(std::initializer_list<U> ilist, Args&&... args) {
    if (ok()) {
      this->Clear();
      this->MakeValue(ilist, std::forward<Args>(args)...);
    } else {
      this->MakeValue(ilist, std::forward<Args>(args)...);
      this->state_ = OkStatus().code();
    }
    return this->data_;
  }
 
  template <typename Fn,
            typename Ret = internal_result::InvokeResultType<Fn, T&>,
            std::enable_if_t<std::is_copy_constructible_v<Ret>, int> = 0>
  constexpr Ret and_then(Fn&& function) & {
    static_assert(internal_result::IsResult<Ret>,
                  "Fn must return a pw::Result");
    return ok() ? std::invoke(std::forward<Fn>(function), value())
                : Ret(status());
  }
 
  template <typename Fn,
            typename Ret = internal_result::InvokeResultType<Fn, T&&>,
            std::enable_if_t<std::is_move_constructible_v<Ret>, int> = 0>
  constexpr auto and_then(Fn&& function) && {
    static_assert(internal_result::IsResult<Ret>,
                  "Fn must return a pw::Result");
    return ok() ? std::invoke(std::forward<Fn>(function), std::move(value()))
                : Ret(status());
  }
 
  template <typename Fn,
            typename Ret = internal_result::InvokeResultType<Fn, const T&>,
            std::enable_if_t<std::is_copy_constructible_v<Ret>, int> = 0>
  constexpr auto and_then(Fn&& function) const& {
    static_assert(internal_result::IsResult<Ret>,
                  "Fn must return a pw::Result");
    return ok() ? std::invoke(std::forward<Fn>(function), value())
                : Ret(status());
  }
 
  template <typename Fn,
            typename Ret = internal_result::InvokeResultType<Fn, const T&&>,
            std::enable_if_t<std::is_move_constructible_v<Ret>, int> = 0>
  constexpr auto and_then(Fn&& function) const&& {
    static_assert(internal_result::IsResult<Ret>,
                  "Fn must return a pw::Result");
    return ok() ? std::invoke(std::forward<Fn>(function), std::move(value()))
                : Ret(status());
  }
 
  template <typename Fn,
            typename Ret = internal_result::InvokeResultType<Fn, const Status&>,
            std::enable_if_t<!std::is_void_v<Ret>, int> = 0>
  constexpr Result<T> or_else(Fn&& function) const& {
    static_assert(std::is_convertible_v<Ret, Result<T>>,
                  "Fn must be convertible to a pw::Result");
    return ok() ? *this : std::invoke(std::forward<Fn>(function), status());
  }
 
  template <typename Fn,
            typename Ret = internal_result::InvokeResultType<Fn, const Status&>,
            std::enable_if_t<std::is_void_v<Ret>, int> = 0>
  constexpr Result<T> or_else(Fn&& function) const& {
    if (ok()) {
      return *this;
    }
    std::invoke(std::forward<Fn>(function), status());
    return *this;
  }
 
  template <typename Fn,
            typename Ret = internal_result::InvokeResultType<Fn, Status&&>,
            std::enable_if_t<!std::is_void_v<Ret>, int> = 0>
  constexpr Result<T> or_else(Fn&& function) && {
    static_assert(std::is_convertible_v<Ret, Result<T>>,
                  "Fn must be convertible to a pw::Result");
    return ok() ? std::move(*this)
                : std::invoke(std::forward<Fn>(function), std::move(status()));
  }
 
  template <typename Fn,
            typename Ret = internal_result::InvokeResultType<Fn, Status&&>,
            std::enable_if_t<std::is_void_v<Ret>, int> = 0>
  constexpr Result<T> or_else(Fn&& function) && {
    if (ok()) {
      return *this;
    }
    std::invoke(std::forward<Fn>(function), status());
    return std::move(*this);
  }
 
  template <typename Fn,
            typename Ret = internal_result::InvokeResultType<Fn, T&>,
            std::enable_if_t<std::is_copy_constructible_v<Ret>, int> = 0>
  constexpr Result<Ret> transform(Fn&& function) & {
    if (!ok()) {
      return status();
    }
    return std::invoke(std::forward<Fn>(function), value());
  }
 
  template <typename Fn,
            typename Ret = internal_result::InvokeResultType<Fn, T&&>,
            std::enable_if_t<std::is_move_constructible_v<Ret>, int> = 0>
  constexpr Result<Ret> transform(Fn&& function) && {
    if (!ok()) {
      return std::move(status());
    }
    return std::invoke(std::forward<Fn>(function), std::move(value()));
  }
 
  template <typename Fn,
            typename Ret = internal_result::InvokeResultType<Fn, T&>,
            std::enable_if_t<std::is_copy_constructible_v<Ret>, int> = 0>
  constexpr Result<Ret> transform(Fn&& function) const& {
    if (!ok()) {
      return status();
    }
    return std::invoke(std::forward<Fn>(function), value());
  }
 
  template <typename Fn,
            typename Ret = internal_result::InvokeResultType<Fn, T&&>,
            std::enable_if_t<std::is_move_constructible_v<Ret>, int> = 0>
  constexpr Result<Ret> transform(Fn&& function) const&& {
    if (!ok()) {
      return std::move(status());
    }
    return std::invoke(std::forward<Fn>(function), std::move(value()));
  }
 
 private:
  using Base::Assign;
  template <typename U>
  constexpr void Assign(const Result<U>& other);
  template <typename U>
  constexpr void Assign(Result<U>&& other);
};
 
template <typename T>
Result(T value) -> Result<T>;
 
template <typename T>
constexpr bool operator==(const Result<T>& lhs, const Result<T>& rhs) {
  if (lhs.ok() && rhs.ok()) {
    return *lhs == *rhs;
  }
  return lhs.status() == rhs.status();
}
 
template <typename T>
constexpr bool operator!=(const Result<T>& lhs, const Result<T>& rhs) {
  return !(lhs == rhs);
}
 
 
//------------------------------------------------------------------------------
// Implementation details for Result<T>
//------------------------------------------------------------------------------
 
template <typename T>
constexpr Result<T>::Result() : Base(Status::Unknown().code()) {}
 
template <typename T>
template <typename U>
constexpr inline void Result<T>::Assign(const Result<U>& other) {
  if (other.ok()) {
    this->Assign(*other);
  } else {
    this->AssignState(other.status().code());
  }
}
 
template <typename T>
template <typename U>
constexpr inline void Result<T>::Assign(Result<U>&& other) {
  if (other.ok()) {
    this->Assign(*std::move(other));
  } else {
    this->AssignState(std::move(other).status().code());
  }
}
template <typename T>
template <typename... Args>
constexpr Result<T>::Result(std::in_place_t, Args&&... args)
    : Base(std::in_place, std::forward<Args>(args)...) {}
 
template <typename T>
template <typename U, typename... Args>
constexpr Result<T>::Result(std::in_place_t,
                            std::initializer_list<U> ilist,
                            Args&&... args)
    : Base(std::in_place, ilist, std::forward<Args>(args)...) {}
 
template <typename T>
constexpr Status Result<T>::status() const {
  return this->state_;
}
 
template <typename T>
constexpr const T& Result<T>::value() const& {
  PW_ASSERT(ok());
  return this->data_;
}
 
template <typename T>
constexpr T& Result<T>::value() & {
  PW_ASSERT(ok());
  return this->data_;
}
 
template <typename T>
constexpr const T&& Result<T>::value() const&& {
  PW_ASSERT(ok());
  return std::move(this->data_);
}
 
template <typename T>
constexpr T&& Result<T>::value() && {
  PW_ASSERT(ok());
  return std::move(this->data_);
}
 
template <typename T>
constexpr const T& Result<T>::operator*() const& {
  PW_ASSERT(ok());
  return this->data_;
}
 
template <typename T>
constexpr T& Result<T>::operator*() & {
  PW_ASSERT(ok());
  return this->data_;
}
 
template <typename T>
constexpr const T&& Result<T>::operator*() const&& {
  PW_ASSERT(ok());
  return std::move(this->data_);
}
 
template <typename T>
constexpr T&& Result<T>::operator*() && {
  PW_ASSERT(ok());
  return std::move(this->data_);
}
 
template <typename T>
constexpr const T* Result<T>::operator->() const {
  PW_ASSERT(ok());
  return &this->data_;
}
 
template <typename T>
constexpr T* Result<T>::operator->() {
  PW_ASSERT(ok());
  return &this->data_;
}
 
template <typename T>
template <typename U>
constexpr T Result<T>::value_or(U&& default_value) const& {
  if (ok()) {
    return this->data_;
  }
  return std::forward<U>(default_value);
}
 
template <typename T>
template <typename U>
constexpr T Result<T>::value_or(U&& default_value) && {
  if (ok()) {
    return std::move(this->data_);
  }
  return std::forward<U>(default_value);
}
 
template <typename T>
constexpr void Result<T>::IgnoreError() const {
  // no-op
}
 
namespace internal {
 
template <typename T>
constexpr Status ConvertToStatus(const Result<T>& result) {
  return result.status();
}
 
template <typename T>
constexpr T&& ConvertToValue(Result<T>& result) {
  return std::move(result).value();
}
 
}  // namespace internal
}  // namespace pw