mfbt/Result.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: set ts=8 sts=2 et sw=2 tw=80:
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /* A type suitable for returning either a value or an error from a function. */
   8
   9 #ifndef mozilla_Result_h
  10 #define mozilla_Result_h
  11
  12 #include <algorithm>
  13 #include <cstdint>
  14 #include <cstring>
  15 #include <type_traits>
  16 #include "mozilla/Assertions.h"
  17 #include "mozilla/Attributes.h"
  18 #include "mozilla/CompactPair.h"
  19 #include "mozilla/MaybeStorageBase.h"
  20
  21 namespace mozilla {
  22
  23 /**
  24  * Empty struct, indicating success for operations that have no return value.
  25  * For example, if you declare another empty struct `struct OutOfMemory {};`,
  26  * then `Result<Ok, OutOfMemory>` represents either success or OOM.
  27  */
  28 struct Ok {};
  29
  30 template <typename E>
  31 class GenericErrorResult;
  32 template <typename V, typename E>
  33 class Result;
  34
  35 namespace detail {
  36
  37 enum class PackingStrategy {
  38   Variant,
  39   NullIsOk,
  40   LowBitTagIsError,
  41   PackedVariant,
  42 };
  43
  44 template <typename T>
  45 struct UnusedZero;
  46
  47 template <typename V, typename E, PackingStrategy Strategy>
  48 class ResultImplementation;
  49
  50 template <typename V>
  51 struct EmptyWrapper : V {
  52   constexpr EmptyWrapper() = default;
  53   explicit constexpr EmptyWrapper(const V&) {}
  54   explicit constexpr EmptyWrapper(std::in_place_t) {}
  55
  56   constexpr V* addr() { return this; }
  57   constexpr const V* addr() const { return this; }
  58 };
  59
  60 // The purpose of AlignedStorageOrEmpty is to make an empty class look like
  61 // std::aligned_storage_t for the purposes of the PackingStrategy::NullIsOk
  62 // specializations of ResultImplementation below. We can't use
  63 // std::aligned_storage_t itself with an empty class, since it would no longer
  64 // be empty.
  65 template <typename V>
  66 using AlignedStorageOrEmpty =
  67     std::conditional_t<std::is_empty_v<V>, EmptyWrapper<V>,
  68                        MaybeStorageBase<V>>;
  69
  70 template <typename V, typename E>
  71 class ResultImplementationNullIsOkBase {
  72  protected:
  73   using ErrorStorageType = typename UnusedZero<E>::StorageType;
  74
  75   static constexpr auto kNullValue = UnusedZero<E>::nullValue;
  76
  77   static_assert(std::is_trivially_copyable_v<ErrorStorageType>);
  78
  79   // XXX This can't be statically asserted in general, if ErrorStorageType is
  80   // not a basic type. With C++20 bit_cast, we could probably re-add such as
  81   // assertion. static_assert(kNullValue == decltype(kNullValue)(0));
  82
  83   CompactPair<AlignedStorageOrEmpty<V>, ErrorStorageType> mValue;
  84
  85  public:
  86   explicit constexpr ResultImplementationNullIsOkBase(const V& aSuccessValue)
  87       : mValue(aSuccessValue, kNullValue) {}
  88   explicit constexpr ResultImplementationNullIsOkBase(V&& aSuccessValue)
  89       : mValue(std::move(aSuccessValue), kNullValue) {}
  90   template <typename... Args>
  91   explicit constexpr ResultImplementationNullIsOkBase(std::in_place_t,
  92                                                       Args&&... aArgs)
  93       : mValue(std::piecewise_construct,
  94                std::tuple(std::in_place, std::forward<Args>(aArgs)...),
  95                std::tuple(kNullValue)) {}
  96   explicit constexpr ResultImplementationNullIsOkBase(E aErrorValue)
  97       : mValue(std::piecewise_construct, std::tuple<>(),
  98                std::tuple(UnusedZero<E>::Store(std::move(aErrorValue)))) {
  99     MOZ_ASSERT(mValue.second() != kNullValue);
 100   }
 101
 102   constexpr ResultImplementationNullIsOkBase(
 103       ResultImplementationNullIsOkBase&& aOther)
 104       : mValue(std::piecewise_construct, std::tuple<>(),
 105                std::tuple(aOther.mValue.second())) {
 106     if constexpr (!std::is_empty_v<V>) {
 107       if (isOk()) {
 108         new (mValue.first().addr()) V(std::move(*aOther.mValue.first().addr()));
 109       }
 110     }
 111   }
 112   ResultImplementationNullIsOkBase& operator=(
 113       ResultImplementationNullIsOkBase&& aOther) {
 114     if constexpr (!std::is_empty_v<V>) {
 115       if (isOk()) {
 116         mValue.first().addr()->~V();
 117       }
 118     }
 119     mValue.second() = std::move(aOther.mValue.second());
 120     if constexpr (!std::is_empty_v<V>) {
 121       if (isOk()) {
 122         new (mValue.first().addr()) V(std::move(*aOther.mValue.first().addr()));
 123       }
 124     }
 125     return *this;
 126   }
 127
 128   constexpr bool isOk() const { return mValue.second() == kNullValue; }
 129
 130   constexpr const V& inspect() const { return *mValue.first().addr(); }
 131   constexpr V unwrap() { return std::move(*mValue.first().addr()); }
 132
 133   constexpr decltype(auto) inspectErr() const {
 134     return UnusedZero<E>::Inspect(mValue.second());
 135   }
 136   constexpr E unwrapErr() { return UnusedZero<E>::Unwrap(mValue.second()); }
 137 };
 138
 139 template <typename V, typename E,
 140           bool IsVTriviallyDestructible = std::is_trivially_destructible_v<V>>
 141 class ResultImplementationNullIsOk;
 142
 143 template <typename V, typename E>
 144 class ResultImplementationNullIsOk<V, E, true>
 145     : public ResultImplementationNullIsOkBase<V, E> {
 146  public:
 147   using ResultImplementationNullIsOkBase<V,
 148                                          E>::ResultImplementationNullIsOkBase;
 149 };
 150
 151 template <typename V, typename E>
 152 class ResultImplementationNullIsOk<V, E, false>
 153     : public ResultImplementationNullIsOkBase<V, E> {
 154  public:
 155   using ResultImplementationNullIsOkBase<V,
 156                                          E>::ResultImplementationNullIsOkBase;
 157
 158   ResultImplementationNullIsOk(ResultImplementationNullIsOk&&) = default;
 159   ResultImplementationNullIsOk& operator=(ResultImplementationNullIsOk&&) =
 160       default;
 161
 162   ~ResultImplementationNullIsOk() {
 163     if (this->isOk()) {
 164       this->mValue.first().addr()->~V();
 165     }
 166   }
 167 };
 168
 169 /**
 170  * Specialization for when the success type is default-constructible and the
 171  * error type is a value type which can never have the value 0 (as determined by
 172  * UnusedZero<>).
 173  */
 174 template <typename V, typename E>
 175 class ResultImplementation<V, E, PackingStrategy::NullIsOk>
 176     : public ResultImplementationNullIsOk<V, E> {
 177  public:
 178   using ResultImplementationNullIsOk<V, E>::ResultImplementationNullIsOk;
 179 };
 180
 181 template <size_t S>
 182 using UnsignedIntType = std::conditional_t<
 183     S == 1, std::uint8_t,
 184     std::conditional_t<
 185         S == 2, std::uint16_t,
 186         std::conditional_t<S == 3 || S == 4, std::uint32_t,
 187                            std::conditional_t<S <= 8, std::uint64_t, void>>>>;
 188
 189 /**
 190  * Specialization for when alignment permits using the least significant bit
 191  * as a tag bit.
 192  */
 193 template <typename V, typename E>
 194 class ResultImplementation<V, E, PackingStrategy::LowBitTagIsError> {
 195   static_assert(std::is_trivially_copyable_v<V> &&
 196                 std::is_trivially_destructible_v<V>);
 197   static_assert(std::is_trivially_copyable_v<E> &&
 198                 std::is_trivially_destructible_v<E>);
 199
 200   static constexpr size_t kRequiredSize = std::max(sizeof(V), sizeof(E));
 201
 202   using StorageType = UnsignedIntType<kRequiredSize>;
 203
 204 #if defined(__clang__)
 205   alignas(std::max(alignof(V), alignof(E))) StorageType mBits;
 206 #else
 207   // Some gcc versions choke on using std::max with alignas, see
 208   // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=94929 (and this seems to have
 209   // regressed in some gcc 9.x version before being fixed again) Keeping the
 210   // code above since we would eventually drop this when we no longer support
 211   // gcc versions with the bug.
 212   alignas(alignof(V) > alignof(E) ? alignof(V) : alignof(E)) StorageType mBits;
 213 #endif
 214
 215  public:
 216   explicit constexpr ResultImplementation(V aValue) : mBits(0) {
 217     if constexpr (!std::is_empty_v<V>) {
 218       std::memcpy(&mBits, &aValue, sizeof(V));
 219       MOZ_ASSERT((mBits & 1) == 0);
 220     } else {
 221       (void)aValue;
 222     }
 223   }
 224   explicit constexpr ResultImplementation(E aErrorValue) : mBits(1) {
 225     if constexpr (!std::is_empty_v<E>) {
 226       std::memcpy(&mBits, &aErrorValue, sizeof(E));
 227       MOZ_ASSERT((mBits & 1) == 0);
 228       mBits |= 1;
 229     } else {
 230       (void)aErrorValue;
 231     }
 232   }
 233
 234   constexpr bool isOk() const { return (mBits & 1) == 0; }
 235
 236   constexpr V inspect() const {
 237     V res;
 238     std::memcpy(&res, &mBits, sizeof(V));
 239     return res;
 240   }
 241   constexpr V unwrap() { return inspect(); }
 242
 243   constexpr E inspectErr() const {
 244     const auto bits = mBits ^ 1;
 245     E res;
 246     std::memcpy(&res, &bits, sizeof(E));
 247     return res;
 248   }
 249   constexpr E unwrapErr() { return inspectErr(); }
 250 };
 251
 252 // Return true if any of the struct can fit in a word.
 253 template <typename V, typename E>
 254 struct IsPackableVariant {
 255   struct VEbool {
 256     V v;
 257     E e;
 258     bool ok;
 259   };
 260   struct EVbool {
 261     E e;
 262     V v;
 263     bool ok;
 264   };
 265
 266   using Impl =
 267       std::conditional_t<sizeof(VEbool) <= sizeof(EVbool), VEbool, EVbool>;
 268
 269   static const bool value = sizeof(Impl) <= sizeof(uintptr_t);
 270 };
 271
 272 /**
 273  * Specialization for when both type are not using all the bytes, in order to
 274  * use one byte as a tag.
 275  */
 276 template <typename V, typename E>
 277 class ResultImplementation<V, E, PackingStrategy::PackedVariant> {
 278   using Impl = typename IsPackableVariant<V, E>::Impl;
 279   Impl data;
 280
 281  public:
 282   explicit constexpr ResultImplementation(V aValue) {
 283     data.v = std::move(aValue);
 284     data.ok = true;
 285   }
 286   explicit constexpr ResultImplementation(E aErrorValue) {
 287     data.e = std::move(aErrorValue);
 288     data.ok = false;
 289   }
 290
 291   constexpr bool isOk() const { return data.ok; }
 292
 293   constexpr const V& inspect() const { return data.v; }
 294   constexpr V unwrap() { return std::move(data.v); }
 295
 296   constexpr const E& inspectErr() const { return data.e; }
 297   constexpr E unwrapErr() { return std::move(data.e); }
 298 };
 299
 300 // To use nullptr as a special value, we need the counter part to exclude zero
 301 // from its range of valid representations.
 302 //
 303 // By default assume that zero can be represented.
 304 template <typename T>
 305 struct UnusedZero {
 306   static const bool value = false;
 307 };
 308
 309 // This template can be used as a helper for specializing UnusedZero for scoped
 310 // enum types which never use 0 as an error value, e.g.
 311 //
 312 // namespace mozilla::detail {
 313 //
 314 // template <>
 315 // struct UnusedZero<MyEnumType> : UnusedZeroEnum<MyEnumType> {};
 316 //
 317 // }  // namespace mozilla::detail
 318 //
 319 template <typename T>
 320 struct UnusedZeroEnum {
 321   using StorageType = std::underlying_type_t<T>;
 322
 323   static constexpr bool value = true;
 324   static constexpr StorageType nullValue = 0;
 325
 326   static constexpr T Inspect(const StorageType& aValue) {
 327     return static_cast<T>(aValue);
 328   }
 329   static constexpr T Unwrap(StorageType aValue) {
 330     return static_cast<T>(aValue);
 331   }
 332   static constexpr StorageType Store(T aValue) {
 333     return static_cast<StorageType>(aValue);
 334   }
 335 };
 336
 337 // A bit of help figuring out which of the above specializations to use.
 338 //
 339 // We begin by safely assuming types don't have a spare bit, unless they are
 340 // empty.
 341 template <typename T>
 342 struct HasFreeLSB {
 343   static const bool value = std::is_empty_v<T>;
 344 };
 345
 346 // As an incomplete type, void* does not have a spare bit.
 347 template <>
 348 struct HasFreeLSB<void*> {
 349   static const bool value = false;
 350 };
 351
 352 // The lowest bit of a properly-aligned pointer is always zero if the pointee
 353 // type is greater than byte-aligned. That bit is free to use if it's masked
 354 // out of such pointers before they're dereferenced.
 355 template <typename T>
 356 struct HasFreeLSB<T*> {
 357   static const bool value = (alignof(T) & 1) == 0;
 358 };
 359
 360 // Select one of the previous result implementation based on the properties of
 361 // the V and E types.
 362 template <typename V, typename E>
 363 struct SelectResultImpl {
 364   static const PackingStrategy value =
 365       (HasFreeLSB<V>::value && HasFreeLSB<E>::value)
 366           ? PackingStrategy::LowBitTagIsError
 367       : (UnusedZero<E>::value && sizeof(E) <= sizeof(uintptr_t))
 368           ? PackingStrategy::NullIsOk
 369       : (std::is_default_constructible_v<V> &&
 370          std::is_default_constructible_v<E> && IsPackableVariant<V, E>::value)
 371           ? PackingStrategy::PackedVariant
 372           : PackingStrategy::Variant;
 373
 374   using Type = ResultImplementation<V, E, value>;
 375 };
 376
 377 template <typename T>
 378 struct IsResult : std::false_type {};
 379
 380 template <typename V, typename E>
 381 struct IsResult<Result<V, E>> : std::true_type {};
 382
 383 }  // namespace detail
 384
 385 template <typename V, typename E>
 386 constexpr auto ToResult(Result<V, E>&& aValue)
 387     -> decltype(std::forward<Result<V, E>>(aValue)) {
 388   return std::forward<Result<V, E>>(aValue);
 389 }
 390
 391 /**
 392  * Result<V, E> represents the outcome of an operation that can either succeed
 393  * or fail. It contains either a success value of type V or an error value of
 394  * type E.
 395  *
 396  * All Result methods are const, so results are basically immutable.
 397  * This is just like Variant<V, E> but with a slightly different API, and the
 398  * following cases are optimized so Result can be stored more efficiently:
 399  *
 400  * - If both the success and error types do not use their least significant bit,
 401  * are trivially copyable and destructible, Result<V, E> is guaranteed to be as
 402  * large as the larger type. This is determined via the HasFreeLSB trait. By
 403  * default, empty classes (in particular Ok) and aligned pointer types are
 404  * assumed to have a free LSB, but you can specialize this trait for other
 405  * types. If the success type is empty, the representation is guaranteed to be
 406  * all zero bits on success. Do not change this representation! There is JIT
 407  * code that depends on it. (Implementation note: The lowest bit is used as a
 408  * tag bit: 0 to indicate the Result's bits are a success value, 1 to indicate
 409  * the Result's bits (with the 1 masked out) encode an error value)
 410  *
 411  * - Else, if the error type can't have a all-zero bits representation and is
 412  * not larger than a pointer, a CompactPair is used to represent this rather
 413  * than a Variant. This has shown to be better optimizable, and the template
 414  * code is much simpler than that of Variant, so it should also compile faster.
 415  * Whether an error type can't be all-zero bits, is determined via the
 416  * UnusedZero trait. MFBT doesn't declare any public type UnusedZero, but
 417  * nsresult is declared UnusedZero in XPCOM.
 418  *
 419  * The purpose of Result is to reduce the screwups caused by using `false` or
 420  * `nullptr` to indicate errors.
 421  * What screwups? See <https://bugzilla.mozilla.org/show_bug.cgi?id=912928> for
 422  * a partial list.
 423  *
 424  * Result<const V, E> or Result<V, const E> are not meaningful. The success or
 425  * error values in a Result instance are non-modifiable in-place anyway. This
 426  * guarantee must also be maintained when evolving Result. They can be
 427  * unwrap()ped, but this loses const qualification. However, Result<const V, E>
 428  * or Result<V, const E> may be misleading and prevent movability. Just use
 429  * Result<V, E>. (Result<const V*, E> may make sense though, just Result<const
 430  * V* const, E> is not possible.)
 431  */
 432 template <typename V, typename E>
 433 class MOZ_MUST_USE_TYPE Result final {
 434   // See class comment on Result<const V, E> and Result<V, const E>.
 435   static_assert(!std::is_const_v<V>);
 436   static_assert(!std::is_const_v<E>);
 437   static_assert(!std::is_reference_v<V>);
 438   static_assert(!std::is_reference_v<E>);
 439
 440   using Impl = typename detail::SelectResultImpl<V, E>::Type;
 441
 442   Impl mImpl;
 443
 444  public:
 445   using ok_type = V;
 446   using err_type = E;
 447
 448   /** Create a success result. */
 449   MOZ_IMPLICIT constexpr Result(V&& aValue) : mImpl(std::forward<V>(aValue)) {
 450     MOZ_ASSERT(isOk());
 451   }
 452
 453   /** Create a success result. */
 454   MOZ_IMPLICIT constexpr Result(const V& aValue) : mImpl(aValue) {
 455     MOZ_ASSERT(isOk());
 456   }
 457
 458   /** Create a success result in-place. */
 459   template <typename... Args>
 460   explicit constexpr Result(std::in_place_t, Args&&... aArgs)
 461       : mImpl(std::in_place, std::forward<Args>(aArgs)...) {
 462     MOZ_ASSERT(isOk());
 463   }
 464
 465   /** Create an error result. */
 466   explicit constexpr Result(E aErrorValue) : mImpl(std::move(aErrorValue)) {
 467     MOZ_ASSERT(isErr());
 468   }
 469
 470   /**
 471    * Create a (success/error) result from another (success/error) result with a
 472    * different but convertible error type. */
 473   template <typename E2,
 474             typename = std::enable_if_t<std::is_convertible_v<E2, E>>>
 475   MOZ_IMPLICIT constexpr Result(Result<V, E2>&& aOther)
 476       : mImpl(aOther.isOk() ? Impl{aOther.unwrap()}
 477                             : Impl{aOther.unwrapErr()}) {}
 478
 479   /**
 480    * Implementation detail of MOZ_TRY().
 481    * Create an error result from another error result.
 482    */
 483   template <typename E2>
 484   MOZ_IMPLICIT constexpr Result(GenericErrorResult<E2>&& aErrorResult)
 485       : mImpl(std::move(aErrorResult.mErrorValue)) {
 486     static_assert(std::is_convertible_v<E2, E>, "E2 must be convertible to E");
 487     MOZ_ASSERT(isErr());
 488   }
 489
 490   /**
 491    * Implementation detail of MOZ_TRY().
 492    * Create an error result from another error result.
 493    */
 494   template <typename E2>
 495   MOZ_IMPLICIT constexpr Result(const GenericErrorResult<E2>& aErrorResult)
 496       : mImpl(aErrorResult.mErrorValue) {
 497     static_assert(std::is_convertible_v<E2, E>, "E2 must be convertible to E");
 498     MOZ_ASSERT(isErr());
 499   }
 500
 501   Result(const Result&) = delete;
 502   Result(Result&&) = default;
 503   Result& operator=(const Result&) = delete;
 504   Result& operator=(Result&&) = default;
 505
 506   /** True if this Result is a success result. */
 507   constexpr bool isOk() const { return mImpl.isOk(); }
 508
 509   /** True if this Result is an error result. */
 510   constexpr bool isErr() const { return !mImpl.isOk(); }
 511
 512   /** Take the success value from this Result, which must be a success result.
 513    */
 514   constexpr V unwrap() {
 515     MOZ_ASSERT(isOk());
 516     return mImpl.unwrap();
 517   }
 518
 519   /**
 520    * Take the success value from this Result, which must be a success result.
 521    * If it is an error result, then return the aValue.
 522    */
 523   constexpr V unwrapOr(V aValue) {
 524     return MOZ_LIKELY(isOk()) ? mImpl.unwrap() : std::move(aValue);
 525   }
 526
 527   /** Take the error value from this Result, which must be an error result. */
 528   constexpr E unwrapErr() {
 529     MOZ_ASSERT(isErr());
 530     return mImpl.unwrapErr();
 531   }
 532
 533   /** See the success value from this Result, which must be a success result. */
 534   constexpr decltype(auto) inspect() const {
 535     static_assert(!std::is_reference_v<
 536                       std::invoke_result_t<decltype(&Impl::inspect), Impl>> ||
 537                   std::is_const_v<std::remove_reference_t<
 538                       std::invoke_result_t<decltype(&Impl::inspect), Impl>>>);
 539     MOZ_ASSERT(isOk());
 540     return mImpl.inspect();
 541   }
 542
 543   /** See the error value from this Result, which must be an error result. */
 544   constexpr decltype(auto) inspectErr() const {
 545     static_assert(
 546         !std::is_reference_v<
 547             std::invoke_result_t<decltype(&Impl::inspectErr), Impl>> ||
 548         std::is_const_v<std::remove_reference_t<
 549             std::invoke_result_t<decltype(&Impl::inspectErr), Impl>>>);
 550     MOZ_ASSERT(isErr());
 551     return mImpl.inspectErr();
 552   }
 553
 554   /** Propagate the error value from this Result, which must be an error result.
 555    *
 556    * This can be used to propagate an error from a function call to the caller
 557    * with a different value type, but the same error type:
 558    *
 559    *    Result<T1, E> Func1() {
 560    *       Result<T2, E> res = Func2();
 561    *       if (res.isErr()) { return res.propagateErr(); }
 562    *    }
 563    */
 564   constexpr GenericErrorResult<E> propagateErr() {
 565     MOZ_ASSERT(isErr());
 566     return GenericErrorResult<E>{mImpl.unwrapErr()};
 567   }
 568
 569   /**
 570    * Map a function V -> V2 over this result's success variant. If this result
 571    * is an error, do not invoke the function and propagate the error.
 572    *
 573    * Mapping over success values invokes the function to produce a new success
 574    * value:
 575    *
 576    *     // Map Result<int, E> to another Result<int, E>
 577    *     Result<int, E> res(5);
 578    *     Result<int, E> res2 = res.map([](int x) { return x * x; });
 579    *     MOZ_ASSERT(res.isOk());
 580    *     MOZ_ASSERT(res2.unwrap() == 25);
 581    *
 582    *     // Map Result<const char*, E> to Result<size_t, E>
 583    *     Result<const char*, E> res("hello, map!");
 584    *     Result<size_t, E> res2 = res.map(strlen);
 585    *     MOZ_ASSERT(res.isOk());
 586    *     MOZ_ASSERT(res2.unwrap() == 11);
 587    *
 588    * Mapping over an error does not invoke the function and propagates the
 589    * error:
 590    *
 591    *     Result<V, int> res(5);
 592    *     MOZ_ASSERT(res.isErr());
 593    *     Result<V2, int> res2 = res.map([](V v) { ... });
 594    *     MOZ_ASSERT(res2.isErr());
 595    *     MOZ_ASSERT(res2.unwrapErr() == 5);
 596    */
 597   template <typename F>
 598   constexpr auto map(F f) -> Result<std::result_of_t<F(V)>, E> {
 599     using RetResult = Result<std::result_of_t<F(V)>, E>;
 600     return MOZ_LIKELY(isOk()) ? RetResult(f(unwrap())) : RetResult(unwrapErr());
 601   }
 602
 603   /**
 604    * Map a function E -> E2 over this result's error variant. If this result is
 605    * a success, do not invoke the function and move the success over.
 606    *
 607    * Mapping over error values invokes the function to produce a new error
 608    * value:
 609    *
 610    *     // Map Result<V, int> to another Result<V, int>
 611    *     Result<V, int> res(5);
 612    *     Result<V, int> res2 = res.mapErr([](int x) { return x * x; });
 613    *     MOZ_ASSERT(res2.isErr());
 614    *     MOZ_ASSERT(res2.unwrapErr() == 25);
 615    *
 616    *     // Map Result<V, const char*> to Result<V, size_t>
 617    *     Result<V, const char*> res("hello, mapErr!");
 618    *     Result<V, size_t> res2 = res.mapErr(strlen);
 619    *     MOZ_ASSERT(res2.isErr());
 620    *     MOZ_ASSERT(res2.unwrapErr() == 14);
 621    *
 622    * Mapping over a success does not invoke the function and moves the success:
 623    *
 624    *     Result<int, E> res(5);
 625    *     MOZ_ASSERT(res.isOk());
 626    *     Result<int, E2> res2 = res.mapErr([](E e) { ... });
 627    *     MOZ_ASSERT(res2.isOk());
 628    *     MOZ_ASSERT(res2.unwrap() == 5);
 629    */
 630   template <typename F>
 631   constexpr auto mapErr(F f) {
 632     using RetResult = Result<V, std::result_of_t<F(E)>>;
 633     return MOZ_UNLIKELY(isErr()) ? RetResult(f(unwrapErr()))
 634                                  : RetResult(unwrap());
 635   }
 636
 637   /**
 638    * Map a function E -> Result<V, E2> over this result's error variant. If
 639    * this result is a success, do not invoke the function and move the success
 640    * over.
 641    *
 642    * `orElse`ing over error values invokes the function to produce a new
 643    * result:
 644    *
 645    *     // `orElse` Result<V, int> error variant to another Result<V, int>
 646    *     // error variant or Result<V, int> success variant
 647    *     auto orElse = [](int x) -> Result<V, int> {
 648    *       if (x != 6) {
 649    *         return Err(x * x);
 650    *       }
 651    *       return V(...);
 652    *     };
 653    *
 654    *     Result<V, int> res(5);
 655    *     auto res2 = res.orElse(orElse);
 656    *     MOZ_ASSERT(res2.isErr());
 657    *     MOZ_ASSERT(res2.unwrapErr() == 25);
 658    *
 659    *     Result<V, int> res3(6);
 660    *     auto res4 = res3.orElse(orElse);
 661    *     MOZ_ASSERT(res4.isOk());
 662    *     MOZ_ASSERT(res4.unwrap() == ...);
 663    *
 664    *     // `orElse` Result<V, const char*> error variant to Result<V, size_t>
 665    *     // error variant or Result<V, size_t> success variant
 666    *     auto orElse = [](const char* s) -> Result<V, size_t> {
 667    *       if (strcmp(s, "foo")) {
 668    *         return Err(strlen(s));
 669    *       }
 670    *       return V(...);
 671    *     };
 672    *
 673    *     Result<V, const char*> res("hello, orElse!");
 674    *     auto res2 = res.orElse(orElse);
 675    *     MOZ_ASSERT(res2.isErr());
 676    *     MOZ_ASSERT(res2.unwrapErr() == 14);
 677    *
 678    *     Result<V, const char*> res3("foo");
 679    *     auto res4 = ress.orElse(orElse);
 680    *     MOZ_ASSERT(res4.isOk());
 681    *     MOZ_ASSERT(res4.unwrap() == ...);
 682    *
 683    * `orElse`ing over a success does not invoke the function and moves the
 684    * success:
 685    *
 686    *     Result<int, E> res(5);
 687    *     MOZ_ASSERT(res.isOk());
 688    *     Result<int, E2> res2 = res.orElse([](E e) { ... });
 689    *     MOZ_ASSERT(res2.isOk());
 690    *     MOZ_ASSERT(res2.unwrap() == 5);
 691    */
 692   template <typename F>
 693   auto orElse(F f) -> Result<V, typename std::result_of_t<F(E)>::err_type> {
 694     return MOZ_UNLIKELY(isErr()) ? f(unwrapErr()) : unwrap();
 695   }
 696
 697   /**
 698    * Given a function V -> Result<V2, E>, apply it to this result's success
 699    * value and return its result. If this result is an error value, it is
 700    * propagated.
 701    *
 702    * This is sometimes called "flatMap" or ">>=" in other contexts.
 703    *
 704    * `andThen`ing over success values invokes the function to produce a new
 705    * result:
 706    *
 707    *     Result<const char*, Error> res("hello, andThen!");
 708    *     Result<HtmlFreeString, Error> res2 = res.andThen([](const char* s) {
 709    *       return containsHtmlTag(s)
 710    *         ? Result<HtmlFreeString, Error>(Error("Invalid: contains HTML"))
 711    *         : Result<HtmlFreeString, Error>(HtmlFreeString(s));
 712    *       }
 713    *     });
 714    *     MOZ_ASSERT(res2.isOk());
 715    *     MOZ_ASSERT(res2.unwrap() == HtmlFreeString("hello, andThen!");
 716    *
 717    * `andThen`ing over error results does not invoke the function, and just
 718    * propagates the error result:
 719    *
 720    *     Result<int, const char*> res("some error");
 721    *     auto res2 = res.andThen([](int x) { ... });
 722    *     MOZ_ASSERT(res2.isErr());
 723    *     MOZ_ASSERT(res.unwrapErr() == res2.unwrapErr());
 724    */
 725   template <typename F, typename = std::enable_if_t<detail::IsResult<
 726                             std::invoke_result_t<F, V&&>>::value>>
 727   constexpr auto andThen(F f) -> std::invoke_result_t<F, V&&> {
 728     return MOZ_LIKELY(isOk()) ? f(unwrap()) : propagateErr();
 729   }
 730 };
 731
 732 /**
 733  * A type that auto-converts to an error Result. This is like a Result without
 734  * a success type. It's the best return type for functions that always return
 735  * an error--functions designed to build and populate error objects. It's also
 736  * useful in error-handling macros; see MOZ_TRY for an example.
 737  */
 738 template <typename E>
 739 class MOZ_MUST_USE_TYPE GenericErrorResult {
 740   E mErrorValue;
 741
 742   template <typename V, typename E2>
 743   friend class Result;
 744
 745  public:
 746   explicit constexpr GenericErrorResult(const E& aErrorValue)
 747       : mErrorValue(aErrorValue) {}
 748
 749   explicit constexpr GenericErrorResult(E&& aErrorValue)
 750       : mErrorValue(std::move(aErrorValue)) {}
 751 };
 752
 753 template <typename E>
 754 inline constexpr auto Err(E&& aErrorValue) {
 755   return GenericErrorResult<std::decay_t<E>>(std::forward<E>(aErrorValue));
 756 }
 757
 758 }  // namespace mozilla
 759
 760 /**
 761  * MOZ_TRY(expr) is the C++ equivalent of Rust's `try!(expr);`. First, it
 762  * evaluates expr, which must produce a Result value. On success, it
 763  * discards the result altogether. On error, it immediately returns an error
 764  * Result from the enclosing function.
 765  */
 766 #define MOZ_TRY(expr)                                   \
 767   do {                                                  \
 768     auto mozTryTempResult_ = ::mozilla::ToResult(expr); \
 769     if (MOZ_UNLIKELY(mozTryTempResult_.isErr())) {      \
 770       return mozTryTempResult_.propagateErr();          \
 771     }                                                   \
 772   } while (0)
 773
 774 /**
 775  * MOZ_TRY_VAR(target, expr) is the C++ equivalent of Rust's `target =
 776  * try!(expr);`. First, it evaluates expr, which must produce a Result value. On
 777  * success, the result's success value is assigned to target. On error,
 778  * immediately returns the error result. |target| must be an lvalue.
 779  */
 780 #define MOZ_TRY_VAR(target, expr)                     \
 781   do {                                                \
 782     auto mozTryVarTempResult_ = (expr);               \
 783     if (MOZ_UNLIKELY(mozTryVarTempResult_.isErr())) { \
 784       return mozTryVarTempResult_.propagateErr();     \
 785     }                                                 \
 786     (target) = mozTryVarTempResult_.unwrap();         \
 787   } while (0)
 788
 789 #endif  // mozilla_Result_h