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