mfbt/Maybe.h

   1 /* -*- Mode: C++; tab-width: 2; 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 class for optional values and in-place lazy construction. */
   8
   9 #ifndef mozilla_Maybe_h
  10 #define mozilla_Maybe_h
  11
  12 #include <new>  // for placement new
  13 #include <ostream>
  14 #include <type_traits>
  15 #include <utility>
  16
  17 #include "mozilla/Alignment.h"
  18 #include "mozilla/Assertions.h"
  19 #include "mozilla/Attributes.h"
  20 #include "mozilla/MemoryChecking.h"
  21 #include "mozilla/OperatorNewExtensions.h"
  22 #include "mozilla/Poison.h"
  23
  24 class nsCycleCollectionTraversalCallback;
  25
  26 template <typename T>
  27 inline void CycleCollectionNoteChild(
  28     nsCycleCollectionTraversalCallback& aCallback, T* aChild, const char* aName,
  29     uint32_t aFlags);
  30
  31 namespace mozilla {
  32
  33 struct Nothing {};
  34
  35 inline constexpr bool operator==(const Nothing&, const Nothing&) {
  36   return true;
  37 }
  38
  39 template <class T>
  40 class Maybe;
  41
  42 namespace detail {
  43
  44 // You would think that poisoning Maybe instances could just be a call
  45 // to mozWritePoison.  Unfortunately, using a simple call to
  46 // mozWritePoison generates poor code on MSVC for small structures.  The
  47 // generated code contains (always not-taken) branches and does a bunch
  48 // of setup for `rep stos{l,q}`, even though we know at compile time
  49 // exactly how many words we're poisoning.  Instead, we're going to
  50 // force MSVC to generate the code we want via recursive templates.
  51
  52 // Write the given poisonValue into p at offset*sizeof(uintptr_t).
  53 template <size_t offset>
  54 inline void WritePoisonAtOffset(void* p, const uintptr_t poisonValue) {
  55   memcpy(static_cast<char*>(p) + offset * sizeof(poisonValue), &poisonValue,
  56          sizeof(poisonValue));
  57 }
  58
  59 template <size_t Offset, size_t NOffsets>
  60 struct InlinePoisoner {
  61   static void poison(void* p, const uintptr_t poisonValue) {
  62     WritePoisonAtOffset<Offset>(p, poisonValue);
  63     InlinePoisoner<Offset + 1, NOffsets>::poison(p, poisonValue);
  64   }
  65 };
  66
  67 template <size_t N>
  68 struct InlinePoisoner<N, N> {
  69   static void poison(void*, const uintptr_t) {
  70     // All done!
  71   }
  72 };
  73
  74 // We can't generate inline code for large structures, though, because we'll
  75 // blow out recursive template instantiation limits, and the code would be
  76 // bloated to boot.  So provide a fallback to the out-of-line poisoner.
  77 template <size_t ObjectSize>
  78 struct OutOfLinePoisoner {
  79   static MOZ_NEVER_INLINE void poison(void* p, const uintptr_t) {
  80     mozWritePoison(p, ObjectSize);
  81   }
  82 };
  83
  84 template <typename T>
  85 inline void PoisonObject(T* p) {
  86   const uintptr_t POISON = mozPoisonValue();
  87   std::conditional_t<(sizeof(T) <= 8 * sizeof(POISON)),
  88                      InlinePoisoner<0, sizeof(T) / sizeof(POISON)>,
  89                      OutOfLinePoisoner<sizeof(T)>>::poison(p, POISON);
  90 }
  91
  92 template <typename T>
  93 struct MaybePoisoner {
  94   static const size_t N = sizeof(T);
  95
  96   static void poison(void* aPtr) {
  97 #ifdef MOZ_DIAGNOSTIC_ASSERT_ENABLED
  98     if (N >= sizeof(uintptr_t)) {
  99       PoisonObject(static_cast<std::remove_cv_t<T>*>(aPtr));
 100     }
 101 #endif
 102     MOZ_MAKE_MEM_UNDEFINED(aPtr, N);
 103   }
 104 };
 105
 106 template <typename T>
 107 constexpr bool IsTriviallyDestructibleAndCopyable =
 108     std::is_trivially_destructible_v<T> &&
 109     (std::is_trivially_copy_constructible_v<T> ||
 110      !std::is_copy_constructible_v<T>);
 111
 112 template <typename T,
 113           bool TriviallyDestructibleAndCopyable =
 114               IsTriviallyDestructibleAndCopyable<T>,
 115           bool Copyable = std::is_copy_constructible_v<T>,
 116           bool Movable = std::is_move_constructible_v<T>>
 117 class Maybe_CopyMove_Enabler;
 118
 119 #define MOZ_MAYBE_COPY_OPS()                                                \
 120   Maybe_CopyMove_Enabler(const Maybe_CopyMove_Enabler& aOther) {            \
 121     if (downcast(aOther).isSome()) {                                        \
 122       downcast(*this).emplace(*downcast(aOther));                           \
 123     }                                                                       \
 124   }                                                                         \
 125                                                                             \
 126   Maybe_CopyMove_Enabler& operator=(const Maybe_CopyMove_Enabler& aOther) { \
 127     return downcast(*this).template operator=<T>(downcast(aOther));         \
 128   }
 129
 130 #define MOZ_MAYBE_MOVE_OPS()                                            \
 131   constexpr Maybe_CopyMove_Enabler(Maybe_CopyMove_Enabler&& aOther) {   \
 132     if (downcast(aOther).isSome()) {                                    \
 133       downcast(*this).emplace(std::move(*downcast(aOther)));            \
 134       downcast(aOther).reset();                                         \
 135     }                                                                   \
 136   }                                                                     \
 137                                                                         \
 138   constexpr Maybe_CopyMove_Enabler& operator=(                          \
 139       Maybe_CopyMove_Enabler&& aOther) {                                \
 140     downcast(*this).template operator=<T>(std::move(downcast(aOther))); \
 141                                                                         \
 142     return *this;                                                       \
 143   }
 144
 145 #define MOZ_MAYBE_DOWNCAST()                                          \
 146   static constexpr Maybe<T>& downcast(Maybe_CopyMove_Enabler& aObj) { \
 147     return static_cast<Maybe<T>&>(aObj);                              \
 148   }                                                                   \
 149   static constexpr const Maybe<T>& downcast(                          \
 150       const Maybe_CopyMove_Enabler& aObj) {                           \
 151     return static_cast<const Maybe<T>&>(aObj);                        \
 152   }
 153
 154 template <typename T>
 155 class Maybe_CopyMove_Enabler<T, true, true, true> {
 156  public:
 157   Maybe_CopyMove_Enabler() = default;
 158
 159   Maybe_CopyMove_Enabler(const Maybe_CopyMove_Enabler&) = default;
 160   Maybe_CopyMove_Enabler& operator=(const Maybe_CopyMove_Enabler&) = default;
 161   constexpr Maybe_CopyMove_Enabler(Maybe_CopyMove_Enabler&& aOther) {
 162     downcast(aOther).reset();
 163   }
 164   constexpr Maybe_CopyMove_Enabler& operator=(Maybe_CopyMove_Enabler&& aOther) {
 165     downcast(aOther).reset();
 166     return *this;
 167   }
 168
 169  private:
 170   MOZ_MAYBE_DOWNCAST()
 171 };
 172
 173 template <typename T>
 174 class Maybe_CopyMove_Enabler<T, true, false, true> {
 175  public:
 176   Maybe_CopyMove_Enabler() = default;
 177
 178   Maybe_CopyMove_Enabler(const Maybe_CopyMove_Enabler&) = delete;
 179   Maybe_CopyMove_Enabler& operator=(const Maybe_CopyMove_Enabler&) = delete;
 180   constexpr Maybe_CopyMove_Enabler(Maybe_CopyMove_Enabler&& aOther) {
 181     downcast(aOther).reset();
 182   }
 183   constexpr Maybe_CopyMove_Enabler& operator=(Maybe_CopyMove_Enabler&& aOther) {
 184     downcast(aOther).reset();
 185     return *this;
 186   }
 187
 188  private:
 189   MOZ_MAYBE_DOWNCAST()
 190 };
 191
 192 template <typename T>
 193 class Maybe_CopyMove_Enabler<T, false, true, true> {
 194  public:
 195   Maybe_CopyMove_Enabler() = default;
 196
 197   MOZ_MAYBE_COPY_OPS()
 198   MOZ_MAYBE_MOVE_OPS()
 199
 200  private:
 201   MOZ_MAYBE_DOWNCAST()
 202 };
 203
 204 template <typename T>
 205 class Maybe_CopyMove_Enabler<T, false, false, true> {
 206  public:
 207   Maybe_CopyMove_Enabler() = default;
 208
 209   MOZ_MAYBE_MOVE_OPS()
 210
 211  private:
 212   MOZ_MAYBE_DOWNCAST()
 213 };
 214
 215 template <typename T>
 216 class Maybe_CopyMove_Enabler<T, false, true, false> {
 217  public:
 218   Maybe_CopyMove_Enabler() = default;
 219
 220   MOZ_MAYBE_COPY_OPS()
 221
 222  private:
 223   MOZ_MAYBE_DOWNCAST()
 224 };
 225
 226 template <typename T, bool TriviallyDestructibleAndCopyable>
 227 class Maybe_CopyMove_Enabler<T, TriviallyDestructibleAndCopyable, false,
 228                              false> {
 229  public:
 230   Maybe_CopyMove_Enabler() = default;
 231
 232   Maybe_CopyMove_Enabler(const Maybe_CopyMove_Enabler&) = delete;
 233   Maybe_CopyMove_Enabler& operator=(const Maybe_CopyMove_Enabler&) = delete;
 234   Maybe_CopyMove_Enabler(Maybe_CopyMove_Enabler&&) = delete;
 235   Maybe_CopyMove_Enabler& operator=(Maybe_CopyMove_Enabler&&) = delete;
 236 };
 237
 238 #undef MOZ_MAYBE_COPY_OPS
 239 #undef MOZ_MAYBE_MOVE_OPS
 240 #undef MOZ_MAYBE_DOWNCAST
 241
 242 template <typename T, bool TriviallyDestructibleAndCopyable =
 243                           IsTriviallyDestructibleAndCopyable<T>>
 244 struct MaybeStorage;
 245
 246 template <typename T>
 247 struct MaybeStorage<T, false> {
 248   using NonConstT = std::remove_const_t<T>;
 249
 250   union Union {
 251     Union() {}
 252     constexpr explicit Union(const T& aVal) : val{aVal} {}
 253     template <typename U,
 254               typename = std::enable_if_t<std::is_move_constructible_v<U>>>
 255     constexpr explicit Union(U&& aVal) : val{std::forward<U>(aVal)} {}
 256
 257     ~Union() {}
 258
 259     NonConstT val;
 260     char dummy;
 261   } mStorage;
 262   char mIsSome = false;  // not bool -- guarantees minimal space consumption
 263
 264   MaybeStorage() = default;
 265   explicit MaybeStorage(const T& aVal) : mStorage{aVal}, mIsSome{true} {}
 266   explicit MaybeStorage(T&& aVal) : mStorage{std::move(aVal)}, mIsSome{true} {}
 267
 268   template <typename... Args>
 269   explicit MaybeStorage(std::in_place_t, Args&&... aArgs) : mIsSome{true} {
 270     ::new (KnownNotNull, &mStorage.val) T(std::forward<Args>(aArgs)...);
 271   }
 272
 273   // Copy and move operations are no-ops, since copying is moving is implemented
 274   // by Maybe_CopyMove_Enabler.
 275
 276   MaybeStorage(const MaybeStorage&) {}
 277   MaybeStorage& operator=(const MaybeStorage&) { return *this; }
 278   MaybeStorage(MaybeStorage&&) {}
 279   MaybeStorage& operator=(MaybeStorage&&) { return *this; }
 280
 281   ~MaybeStorage() {
 282     if (mIsSome) {
 283       mStorage.val.T::~T();
 284     }
 285   }
 286 };
 287
 288 template <typename T>
 289 struct MaybeStorage<T, true> {
 290   using NonConstT = std::remove_const_t<T>;
 291
 292   union Union {
 293     constexpr Union() : dummy() {}
 294     constexpr explicit Union(const T& aVal) : val{aVal} {}
 295     constexpr explicit Union(T&& aVal) : val{std::move(aVal)} {}
 296     template <typename... Args>
 297     constexpr explicit Union(std::in_place_t, Args&&... aArgs)
 298         : val{std::forward<Args>(aArgs)...} {}
 299
 300     NonConstT val;
 301     char dummy;
 302   } mStorage;
 303   char mIsSome = false;  // not bool -- guarantees minimal space consumption
 304
 305   constexpr MaybeStorage() = default;
 306   constexpr explicit MaybeStorage(const T& aVal)
 307       : mStorage{aVal}, mIsSome{true} {}
 308   constexpr explicit MaybeStorage(T&& aVal)
 309       : mStorage{std::move(aVal)}, mIsSome{true} {}
 310
 311   template <typename... Args>
 312   constexpr explicit MaybeStorage(std::in_place_t, Args&&... aArgs)
 313       : mStorage{std::in_place, std::forward<Args>(aArgs)...}, mIsSome{true} {}
 314 };
 315
 316 }  // namespace detail
 317
 318 template <typename T, typename U = typename std::remove_cv<
 319                           typename std::remove_reference<T>::type>::type>
 320 constexpr Maybe<U> Some(T&& aValue);
 321
 322 /*
 323  * Maybe is a container class which contains either zero or one elements. It
 324  * serves two roles. It can represent values which are *semantically* optional,
 325  * augmenting a type with an explicit 'Nothing' value. In this role, it provides
 326  * methods that make it easy to work with values that may be missing, along with
 327  * equality and comparison operators so that Maybe values can be stored in
 328  * containers. Maybe values can be constructed conveniently in expressions using
 329  * type inference, as follows:
 330  *
 331  *   void doSomething(Maybe<Foo> aFoo) {
 332  *     if (aFoo)                  // Make sure that aFoo contains a value...
 333  *       aFoo->takeAction();      // and then use |aFoo->| to access it.
 334  *   }                            // |*aFoo| also works!
 335  *
 336  *   doSomething(Nothing());      // Passes a Maybe<Foo> containing no value.
 337  *   doSomething(Some(Foo(100))); // Passes a Maybe<Foo> containing |Foo(100)|.
 338  *
 339  * You'll note that it's important to check whether a Maybe contains a value
 340  * before using it, using conversion to bool, |isSome()|, or |isNothing()|. You
 341  * can avoid these checks, and sometimes write more readable code, using
 342  * |valueOr()|, |ptrOr()|, and |refOr()|, which allow you to retrieve the value
 343  * in the Maybe and provide a default for the 'Nothing' case.  You can also use
 344  * |apply()| to call a function only if the Maybe holds a value, and |map()| to
 345  * transform the value in the Maybe, returning another Maybe with a possibly
 346  * different type.
 347  *
 348  * Maybe's other role is to support lazily constructing objects without using
 349  * dynamic storage. A Maybe directly contains storage for a value, but it's
 350  * empty by default. |emplace()|, as mentioned above, can be used to construct a
 351  * value in Maybe's storage.  The value a Maybe contains can be destroyed by
 352  * calling |reset()|; this will happen automatically if a Maybe is destroyed
 353  * while holding a value.
 354  *
 355  * It's a common idiom in C++ to use a pointer as a 'Maybe' type, with a null
 356  * value meaning 'Nothing' and any other value meaning 'Some'. You can convert
 357  * from such a pointer to a Maybe value using 'ToMaybe()'.
 358  *
 359  * Maybe is inspired by similar types in the standard library of many other
 360  * languages (e.g. Haskell's Maybe and Rust's Option). In the C++ world it's
 361  * very similar to std::optional, which was proposed for C++14 and originated in
 362  * Boost. The most important differences between Maybe and std::optional are:
 363  *
 364  *   - std::optional<T> may be compared with T. We deliberately forbid that.
 365  *   - std::optional has |valueOr()|, equivalent to Maybe's |valueOr()|, but
 366  *     lacks corresponding methods for |refOr()| and |ptrOr()|.
 367  *   - std::optional lacks |map()| and |apply()|, making it less suitable for
 368  *     functional-style code.
 369  *   - std::optional lacks many convenience functions that Maybe has. Most
 370  *     unfortunately, it lacks equivalents of the type-inferred constructor
 371  *     functions |Some()| and |Nothing()|.
 372  */
 373 template <class T>
 374 class MOZ_INHERIT_TYPE_ANNOTATIONS_FROM_TEMPLATE_ARGS Maybe
 375     : private detail::MaybeStorage<T>,
 376       public detail::Maybe_CopyMove_Enabler<T> {
 377   template <typename, bool, bool, bool>
 378   friend class detail::Maybe_CopyMove_Enabler;
 379
 380   template <typename U, typename V>
 381   friend constexpr Maybe<V> Some(U&& aValue);
 382
 383   struct SomeGuard {};
 384
 385   template <typename U>
 386   constexpr Maybe(U&& aValue, SomeGuard)
 387       : detail::MaybeStorage<T>{std::forward<U>(aValue)} {}
 388
 389   using detail::MaybeStorage<T>::mIsSome;
 390   using detail::MaybeStorage<T>::mStorage;
 391
 392   void poisonData() { detail::MaybePoisoner<T>::poison(&mStorage.val); }
 393
 394  public:
 395   using ValueType = T;
 396
 397   MOZ_ALLOW_TEMPORARY constexpr Maybe() = default;
 398
 399   MOZ_ALLOW_TEMPORARY MOZ_IMPLICIT constexpr Maybe(Nothing) : Maybe{} {}
 400
 401   template <typename... Args>
 402   constexpr explicit Maybe(std::in_place_t, Args&&... aArgs)
 403       : detail::MaybeStorage<T>{std::in_place, std::forward<Args>(aArgs)...} {}
 404
 405   /**
 406    * Maybe<T> can be copy-constructed from a Maybe<U> if T is constructible from
 407    * a const U&.
 408    */
 409   template <typename U,
 410             typename = std::enable_if_t<std::is_constructible_v<T, const U&>>>
 411   MOZ_IMPLICIT Maybe(const Maybe<U>& aOther) {
 412     if (aOther.isSome()) {
 413       emplace(*aOther);
 414     }
 415   }
 416
 417   /**
 418    * Maybe<T> can be move-constructed from a Maybe<U> if T is constructible from
 419    * a U&&.
 420    */
 421   template <typename U,
 422             typename = std::enable_if_t<std::is_constructible_v<T, U&&>>>
 423   MOZ_IMPLICIT Maybe(Maybe<U>&& aOther) {
 424     if (aOther.isSome()) {
 425       emplace(std::move(*aOther));
 426       aOther.reset();
 427     }
 428   }
 429
 430   template <typename U,
 431             typename = std::enable_if_t<std::is_constructible_v<T, const U&>>>
 432   Maybe& operator=(const Maybe<U>& aOther) {
 433     if (aOther.isSome()) {
 434       if (mIsSome) {
 435         ref() = aOther.ref();
 436       } else {
 437         emplace(*aOther);
 438       }
 439     } else {
 440       reset();
 441     }
 442     return *this;
 443   }
 444
 445   template <typename U,
 446             typename = std::enable_if_t<std::is_constructible_v<T, U&&>>>
 447   Maybe& operator=(Maybe<U>&& aOther) {
 448     if (aOther.isSome()) {
 449       if (mIsSome) {
 450         ref() = std::move(aOther.ref());
 451       } else {
 452         emplace(std::move(*aOther));
 453       }
 454       aOther.reset();
 455     } else {
 456       reset();
 457     }
 458
 459     return *this;
 460   }
 461
 462   constexpr Maybe& operator=(Nothing) {
 463     reset();
 464     return *this;
 465   }
 466
 467   /* Methods that check whether this Maybe contains a value */
 468   constexpr explicit operator bool() const { return isSome(); }
 469   constexpr bool isSome() const { return mIsSome; }
 470   constexpr bool isNothing() const { return !mIsSome; }
 471
 472   /* Returns the contents of this Maybe<T> by value. Unsafe unless |isSome()|.
 473    */
 474   constexpr T value() const;
 475
 476   /**
 477    * Move the contents of this Maybe<T> out of internal storage and return it
 478    * without calling the destructor. The internal storage is also reset to
 479    * avoid multiple calls. Unsafe unless |isSome()|.
 480    */
 481   T extract() {
 482     MOZ_DIAGNOSTIC_ASSERT(isSome());
 483     T v = std::move(mStorage.val);
 484     reset();
 485     return v;
 486   }
 487
 488   /**
 489    * Returns the value (possibly |Nothing()|) by moving it out of this Maybe<T>
 490    * and leaving |Nothing()| in its place.
 491    */
 492   Maybe<T> take() { return std::exchange(*this, Nothing()); }
 493
 494   /*
 495    * Returns the contents of this Maybe<T> by value. If |isNothing()|, returns
 496    * the default value provided.
 497    */
 498   template <typename V>
 499   constexpr T valueOr(V&& aDefault) const {
 500     if (isSome()) {
 501       return ref();
 502     }
 503     return std::forward<V>(aDefault);
 504   }
 505
 506   /*
 507    * Returns the contents of this Maybe<T> by value. If |isNothing()|, returns
 508    * the value returned from the function or functor provided.
 509    */
 510   template <typename F>
 511   constexpr T valueOrFrom(F&& aFunc) const {
 512     if (isSome()) {
 513       return ref();
 514     }
 515     return aFunc();
 516   }
 517
 518   /* Returns the contents of this Maybe<T> by pointer. Unsafe unless |isSome()|.
 519    */
 520   T* ptr();
 521   constexpr const T* ptr() const;
 522
 523   /*
 524    * Returns the contents of this Maybe<T> by pointer. If |isNothing()|,
 525    * returns the default value provided.
 526    */
 527   T* ptrOr(T* aDefault) {
 528     if (isSome()) {
 529       return ptr();
 530     }
 531     return aDefault;
 532   }
 533
 534   constexpr const T* ptrOr(const T* aDefault) const {
 535     if (isSome()) {
 536       return ptr();
 537     }
 538     return aDefault;
 539   }
 540
 541   /*
 542    * Returns the contents of this Maybe<T> by pointer. If |isNothing()|,
 543    * returns the value returned from the function or functor provided.
 544    */
 545   template <typename F>
 546   T* ptrOrFrom(F&& aFunc) {
 547     if (isSome()) {
 548       return ptr();
 549     }
 550     return aFunc();
 551   }
 552
 553   template <typename F>
 554   const T* ptrOrFrom(F&& aFunc) const {
 555     if (isSome()) {
 556       return ptr();
 557     }
 558     return aFunc();
 559   }
 560
 561   constexpr T* operator->();
 562   constexpr const T* operator->() const;
 563
 564   /* Returns the contents of this Maybe<T> by ref. Unsafe unless |isSome()|. */
 565   constexpr T& ref();
 566   constexpr const T& ref() const;
 567
 568   /*
 569    * Returns the contents of this Maybe<T> by ref. If |isNothing()|, returns
 570    * the default value provided.
 571    */
 572   constexpr T& refOr(T& aDefault) {
 573     if (isSome()) {
 574       return ref();
 575     }
 576     return aDefault;
 577   }
 578
 579   constexpr const T& refOr(const T& aDefault) const {
 580     if (isSome()) {
 581       return ref();
 582     }
 583     return aDefault;
 584   }
 585
 586   /*
 587    * Returns the contents of this Maybe<T> by ref. If |isNothing()|, returns the
 588    * value returned from the function or functor provided.
 589    */
 590   template <typename F>
 591   constexpr T& refOrFrom(F&& aFunc) {
 592     if (isSome()) {
 593       return ref();
 594     }
 595     return aFunc();
 596   }
 597
 598   template <typename F>
 599   constexpr const T& refOrFrom(F&& aFunc) const {
 600     if (isSome()) {
 601       return ref();
 602     }
 603     return aFunc();
 604   }
 605
 606   constexpr T& operator*();
 607   constexpr const T& operator*() const;
 608
 609   /* If |isSome()|, runs the provided function or functor on the contents of
 610    * this Maybe. */
 611   template <typename Func>
 612   constexpr Maybe& apply(Func&& aFunc) {
 613     if (isSome()) {
 614       std::forward<Func>(aFunc)(ref());
 615     }
 616     return *this;
 617   }
 618
 619   template <typename Func>
 620   constexpr const Maybe& apply(Func&& aFunc) const {
 621     if (isSome()) {
 622       std::forward<Func>(aFunc)(ref());
 623     }
 624     return *this;
 625   }
 626
 627   /*
 628    * If |isSome()|, runs the provided function and returns the result wrapped
 629    * in a Maybe. If |isNothing()|, returns an empty Maybe value with the same
 630    * value type as what the provided function would have returned.
 631    */
 632   template <typename Func>
 633   constexpr auto map(Func&& aFunc) {
 634     if (isSome()) {
 635       return Some(std::forward<Func>(aFunc)(ref()));
 636     }
 637     return Maybe<decltype(std::forward<Func>(aFunc)(ref()))>{};
 638   }
 639
 640   template <typename Func>
 641   constexpr auto map(Func&& aFunc) const {
 642     if (isSome()) {
 643       return Some(std::forward<Func>(aFunc)(ref()));
 644     }
 645     return Maybe<decltype(std::forward<Func>(aFunc)(ref()))>{};
 646   }
 647
 648   /* If |isSome()|, empties this Maybe and destroys its contents. */
 649   constexpr void reset() {
 650     if (isSome()) {
 651       if constexpr (!std::is_trivially_destructible_v<T>) {
 652         ref().T::~T();
 653         poisonData();
 654       }
 655       mIsSome = false;
 656     }
 657   }
 658
 659   /*
 660    * Constructs a T value in-place in this empty Maybe<T>'s storage. The
 661    * arguments to |emplace()| are the parameters to T's constructor.
 662    */
 663   template <typename... Args>
 664   constexpr void emplace(Args&&... aArgs);
 665
 666   template <typename U>
 667   constexpr std::enable_if_t<std::is_same_v<T, U> &&
 668                              std::is_copy_constructible_v<U> &&
 669                              !std::is_move_constructible_v<U>>
 670   emplace(U&& aArgs) {
 671     emplace(aArgs);
 672   }
 673
 674   friend std::ostream& operator<<(std::ostream& aStream,
 675                                   const Maybe<T>& aMaybe) {
 676     if (aMaybe) {
 677       aStream << aMaybe.ref();
 678     } else {
 679       aStream << "<Nothing>";
 680     }
 681     return aStream;
 682   }
 683 };
 684
 685 template <typename T>
 686 class Maybe<T&> {
 687  public:
 688   constexpr Maybe() = default;
 689   constexpr MOZ_IMPLICIT Maybe(Nothing) {}
 690
 691   void emplace(T& aRef) { mValue = &aRef; }
 692
 693   /* Methods that check whether this Maybe contains a value */
 694   constexpr explicit operator bool() const { return isSome(); }
 695   constexpr bool isSome() const { return mValue; }
 696   constexpr bool isNothing() const { return !mValue; }
 697
 698   T& ref() const {
 699     MOZ_DIAGNOSTIC_ASSERT(isSome());
 700     return *mValue;
 701   }
 702
 703   T* operator->() const { return &ref(); }
 704   T& operator*() const { return ref(); }
 705
 706   // Deliberately not defining value and ptr accessors, as these may be
 707   // confusing on a reference-typed Maybe.
 708
 709   // XXX Should we define refOr?
 710
 711   void reset() { mValue = nullptr; }
 712
 713   template <typename Func>
 714   Maybe& apply(Func&& aFunc) {
 715     if (isSome()) {
 716       std::forward<Func>(aFunc)(ref());
 717     }
 718     return *this;
 719   }
 720
 721   template <typename Func>
 722   const Maybe& apply(Func&& aFunc) const {
 723     if (isSome()) {
 724       std::forward<Func>(aFunc)(ref());
 725     }
 726     return *this;
 727   }
 728
 729   template <typename Func>
 730   auto map(Func&& aFunc) {
 731     Maybe<decltype(std::forward<Func>(aFunc)(ref()))> val;
 732     if (isSome()) {
 733       val.emplace(std::forward<Func>(aFunc)(ref()));
 734     }
 735     return val;
 736   }
 737
 738   template <typename Func>
 739   auto map(Func&& aFunc) const {
 740     Maybe<decltype(std::forward<Func>(aFunc)(ref()))> val;
 741     if (isSome()) {
 742       val.emplace(std::forward<Func>(aFunc)(ref()));
 743     }
 744     return val;
 745   }
 746
 747   bool refEquals(const Maybe<T&>& aOther) const {
 748     return mValue == aOther.mValue;
 749   }
 750
 751   bool refEquals(const T& aOther) const { return mValue == &aOther; }
 752
 753  private:
 754   T* mValue = nullptr;
 755 };
 756
 757 template <typename T>
 758 constexpr T Maybe<T>::value() const {
 759   MOZ_DIAGNOSTIC_ASSERT(isSome());
 760   return ref();
 761 }
 762
 763 template <typename T>
 764 T* Maybe<T>::ptr() {
 765   MOZ_DIAGNOSTIC_ASSERT(isSome());
 766   return &ref();
 767 }
 768
 769 template <typename T>
 770 constexpr const T* Maybe<T>::ptr() const {
 771   MOZ_DIAGNOSTIC_ASSERT(isSome());
 772   return &ref();
 773 }
 774
 775 template <typename T>
 776 constexpr T* Maybe<T>::operator->() {
 777   MOZ_DIAGNOSTIC_ASSERT(isSome());
 778   return ptr();
 779 }
 780
 781 template <typename T>
 782 constexpr const T* Maybe<T>::operator->() const {
 783   MOZ_DIAGNOSTIC_ASSERT(isSome());
 784   return ptr();
 785 }
 786
 787 template <typename T>
 788 constexpr T& Maybe<T>::ref() {
 789   MOZ_DIAGNOSTIC_ASSERT(isSome());
 790   return mStorage.val;
 791 }
 792
 793 template <typename T>
 794 constexpr const T& Maybe<T>::ref() const {
 795   MOZ_DIAGNOSTIC_ASSERT(isSome());
 796   return mStorage.val;
 797 }
 798
 799 template <typename T>
 800 constexpr T& Maybe<T>::operator*() {
 801   MOZ_DIAGNOSTIC_ASSERT(isSome());
 802   return ref();
 803 }
 804
 805 template <typename T>
 806 constexpr const T& Maybe<T>::operator*() const {
 807   MOZ_DIAGNOSTIC_ASSERT(isSome());
 808   return ref();
 809 }
 810
 811 template <typename T>
 812 template <typename... Args>
 813 constexpr void Maybe<T>::emplace(Args&&... aArgs) {
 814   MOZ_DIAGNOSTIC_ASSERT(!isSome());
 815   ::new (KnownNotNull, &mStorage.val) T(std::forward<Args>(aArgs)...);
 816   mIsSome = true;
 817 }
 818
 819 /*
 820  * Some() creates a Maybe<T> value containing the provided T value. If T has a
 821  * move constructor, it's used to make this as efficient as possible.
 822  *
 823  * Some() selects the type of Maybe it returns by removing any const, volatile,
 824  * or reference qualifiers from the type of the value you pass to it. This gives
 825  * it more intuitive behavior when used in expressions, but it also means that
 826  * if you need to construct a Maybe value that holds a const, volatile, or
 827  * reference value, you need to use emplace() instead.
 828  */
 829 template <typename T, typename U>
 830 constexpr Maybe<U> Some(T&& aValue) {
 831   return {std::forward<T>(aValue), typename Maybe<U>::SomeGuard{}};
 832 }
 833
 834 template <typename T>
 835 constexpr Maybe<T&> SomeRef(T& aValue) {
 836   Maybe<T&> value;
 837   value.emplace(aValue);
 838   return value;
 839 }
 840
 841 template <typename T>
 842 Maybe<std::remove_cv_t<std::remove_reference_t<T>>> ToMaybe(T* aPtr) {
 843   if (aPtr) {
 844     return Some(*aPtr);
 845   }
 846   return Nothing();
 847 }
 848
 849 /*
 850  * Two Maybe<T> values are equal if
 851  * - both are Nothing, or
 852  * - both are Some, and the values they contain are equal.
 853  */
 854 template <typename T>
 855 constexpr bool operator==(const Maybe<T>& aLHS, const Maybe<T>& aRHS) {
 856   static_assert(!std::is_reference_v<T>,
 857                 "operator== is not defined for Maybe<T&>, compare values or "
 858                 "addresses explicitly instead");
 859   if (aLHS.isNothing() != aRHS.isNothing()) {
 860     return false;
 861   }
 862   return aLHS.isNothing() || *aLHS == *aRHS;
 863 }
 864
 865 template <typename T>
 866 constexpr bool operator!=(const Maybe<T>& aLHS, const Maybe<T>& aRHS) {
 867   return !(aLHS == aRHS);
 868 }
 869
 870 /*
 871  * We support comparison to Nothing to allow reasonable expressions like:
 872  *   if (maybeValue == Nothing()) { ... }
 873  */
 874 template <typename T>
 875 constexpr bool operator==(const Maybe<T>& aLHS, const Nothing& aRHS) {
 876   return aLHS.isNothing();
 877 }
 878
 879 template <typename T>
 880 constexpr bool operator!=(const Maybe<T>& aLHS, const Nothing& aRHS) {
 881   return !(aLHS == aRHS);
 882 }
 883
 884 template <typename T>
 885 constexpr bool operator==(const Nothing& aLHS, const Maybe<T>& aRHS) {
 886   return aRHS.isNothing();
 887 }
 888
 889 template <typename T>
 890 constexpr bool operator!=(const Nothing& aLHS, const Maybe<T>& aRHS) {
 891   return !(aLHS == aRHS);
 892 }
 893
 894 /*
 895  * Maybe<T> values are ordered in the same way T values are ordered, except that
 896  * Nothing comes before anything else.
 897  */
 898 template <typename T>
 899 constexpr bool operator<(const Maybe<T>& aLHS, const Maybe<T>& aRHS) {
 900   if (aLHS.isNothing()) {
 901     return aRHS.isSome();
 902   }
 903   if (aRHS.isNothing()) {
 904     return false;
 905   }
 906   return *aLHS < *aRHS;
 907 }
 908
 909 template <typename T>
 910 constexpr bool operator>(const Maybe<T>& aLHS, const Maybe<T>& aRHS) {
 911   return !(aLHS < aRHS || aLHS == aRHS);
 912 }
 913
 914 template <typename T>
 915 constexpr bool operator<=(const Maybe<T>& aLHS, const Maybe<T>& aRHS) {
 916   return aLHS < aRHS || aLHS == aRHS;
 917 }
 918
 919 template <typename T>
 920 constexpr bool operator>=(const Maybe<T>& aLHS, const Maybe<T>& aRHS) {
 921   return !(aLHS < aRHS);
 922 }
 923
 924 template <typename T>
 925 inline void ImplCycleCollectionTraverse(
 926     nsCycleCollectionTraversalCallback& aCallback, mozilla::Maybe<T>& aField,
 927     const char* aName, uint32_t aFlags = 0) {
 928   if (aField) {
 929     ImplCycleCollectionTraverse(aCallback, aField.ref(), aName, aFlags);
 930   }
 931 }
 932
 933 template <typename T>
 934 inline void ImplCycleCollectionUnlink(mozilla::Maybe<T>& aField) {
 935   if (aField) {
 936     ImplCycleCollectionUnlink(aField.ref());
 937   }
 938 }
 939
 940 }  // namespace mozilla
 941
 942 #endif /* mozilla_Maybe_h */