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