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