mfbt/Maybe.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 class for optional values and in-place lazy construction. */
   8
   9 #ifndef mozilla_Maybe_h
  10 #define mozilla_Maybe_h
  11
  12 #include "mozilla/Alignment.h"
  13 #include "mozilla/Assertions.h"
  14 #include "mozilla/Attributes.h"
  15 #include "mozilla/Move.h"
  16 #include "mozilla/TypeTraits.h"
  17
  18 #include <new>  // for placement new
  19
  20 namespace mozilla {
  21
  22 struct Nothing { };
  23
  24 /*
  25  * Maybe is a container class which contains either zero or one elements. It
  26  * serves two roles. It can represent values which are *semantically* optional,
  27  * augmenting a type with an explicit 'Nothing' value. In this role, it provides
  28  * methods that make it easy to work with values that may be missing, along with
  29  * equality and comparison operators so that Maybe values can be stored in
  30  * containers. Maybe values can be constructed conveniently in expressions using
  31  * type inference, as follows:
  32  *
  33  *   void doSomething(Maybe<Foo> aFoo) {
  34  *     if (aFoo)                  // Make sure that aFoo contains a value...
  35  *       aFoo->takeAction();      // and then use |aFoo->| to access it.
  36  *   }                            // |*aFoo| also works!
  37  *
  38  *   doSomething(Nothing());      // Passes a Maybe<Foo> containing no value.
  39  *   doSomething(Some(Foo(100))); // Passes a Maybe<Foo> containing |Foo(100)|.
  40  *
  41  * You'll note that it's important to check whether a Maybe contains a value
  42  * before using it, using conversion to bool, |isSome()|, or |isNothing()|. You
  43  * can avoid these checks, and sometimes write more readable code, using
  44  * |valueOr()|, |ptrOr()|, and |refOr()|, which allow you to retrieve the value
  45  * in the Maybe and provide a default for the 'Nothing' case.  You can also use
  46  * |apply()| to call a function only if the Maybe holds a value, and |map()| to
  47  * transform the value in the Maybe, returning another Maybe with a possibly
  48  * different type.
  49  *
  50  * Maybe's other role is to support lazily constructing objects without using
  51  * dynamic storage. A Maybe directly contains storage for a value, but it's
  52  * empty by default. |emplace()|, as mentioned above, can be used to construct a
  53  * value in Maybe's storage.  The value a Maybe contains can be destroyed by
  54  * calling |reset()|; this will happen automatically if a Maybe is destroyed
  55  * while holding a value.
  56  *
  57  * It's a common idiom in C++ to use a pointer as a 'Maybe' type, with a null
  58  * value meaning 'Nothing' and any other value meaning 'Some'. You can convert
  59  * from such a pointer to a Maybe value using 'ToMaybe()'.
  60  *
  61  * Maybe is inspired by similar types in the standard library of many other
  62  * languages (e.g. Haskell's Maybe and Rust's Option). In the C++ world it's
  63  * very similar to std::optional, which was proposed for C++14 and originated in
  64  * Boost. The most important differences between Maybe and std::optional are:
  65  *
  66  *   - std::optional<T> may be compared with T. We deliberately forbid that.
  67  *   - std::optional allows in-place construction without a separate call to
  68  *     |emplace()| by using a dummy |in_place_t| value to tag the appropriate
  69  *     constructor.
  70  *   - std::optional has |valueOr()|, equivalent to Maybe's |valueOr()|, but
  71  *     lacks corresponding methods for |refOr()| and |ptrOr()|.
  72  *   - std::optional lacks |map()| and |apply()|, making it less suitable for
  73  *     functional-style code.
  74  *   - std::optional lacks many convenience functions that Maybe has. Most
  75  *     unfortunately, it lacks equivalents of the type-inferred constructor
  76  *     functions |Some()| and |Nothing()|.
  77  *
  78  * N.B. GCC has missed optimizations with Maybe in the past and may generate
  79  * extra branches/loads/stores. Use with caution on hot paths; it's not known
  80  * whether or not this is still a problem.
  81  */
  82 template<class T>
  83 class Maybe
  84 {
  85   typedef void (Maybe::* ConvertibleToBool)(float*****, double*****);
  86   void nonNull(float*****, double*****) {}
  87
  88   bool mIsSome;
  89   AlignedStorage2<T> mStorage;
  90
  91 public:
  92   typedef T ValueType;
  93
  94   Maybe() : mIsSome(false) { }
  95   ~Maybe() { reset(); }
  96
  97   MOZ_IMPLICIT Maybe(Nothing) : mIsSome(false) { }
  98
  99   Maybe(const Maybe& aOther)
 100     : mIsSome(false)
 101   {
 102     if (aOther.mIsSome) {
 103       emplace(*aOther);
 104     }
 105   }
 106
 107   Maybe(Maybe&& aOther)
 108     : mIsSome(false)
 109   {
 110     if (aOther.mIsSome) {
 111       emplace(Move(*aOther));
 112       aOther.reset();
 113     }
 114   }
 115
 116   Maybe& operator=(const Maybe& aOther)
 117   {
 118     if (&aOther != this) {
 119       if (aOther.mIsSome) {
 120         if (mIsSome) {
 121           // XXX(seth): The correct code for this branch, below, can't be used
 122           // due to a bug in Visual Studio 2010. See bug 1052940.
 123           /*
 124           ref() = aOther.ref();
 125           */
 126           reset();
 127           emplace(*aOther);
 128         } else {
 129           emplace(*aOther);
 130         }
 131       } else {
 132         reset();
 133       }
 134     }
 135     return *this;
 136   }
 137
 138   Maybe& operator=(Maybe&& aOther)
 139   {
 140     MOZ_ASSERT(this != &aOther, "Self-moves are prohibited");
 141
 142     if (aOther.mIsSome) {
 143       if (mIsSome) {
 144         ref() = Move(aOther.ref());
 145       } else {
 146         emplace(Move(*aOther));
 147       }
 148       aOther.reset();
 149     } else {
 150       reset();
 151     }
 152
 153     return *this;
 154   }
 155
 156   /* Methods that check whether this Maybe contains a value */
 157   operator ConvertibleToBool() const { return mIsSome ? &Maybe::nonNull : 0; }
 158   bool isSome() const { return mIsSome; }
 159   bool isNothing() const { return !mIsSome; }
 160
 161   /* Returns the contents of this Maybe<T> by value. Unsafe unless |isSome()|. */
 162   T value() const
 163   {
 164     MOZ_ASSERT(mIsSome);
 165     return ref();
 166   }
 167
 168   /*
 169    * Returns the contents of this Maybe<T> by value. If |isNothing()|, returns
 170    * the default value provided.
 171    */
 172   template<typename V>
 173   T valueOr(V&& aDefault) const
 174   {
 175     if (isSome()) {
 176       return ref();
 177     }
 178     return Forward<V>(aDefault);
 179   }
 180
 181   /*
 182    * Returns the contents of this Maybe<T> by value. If |isNothing()|, returns
 183    * the value returned from the function or functor provided.
 184    */
 185   template<typename F>
 186   T valueOrFrom(F&& aFunc) const
 187   {
 188     if (isSome()) {
 189       return ref();
 190     }
 191     return aFunc();
 192   }
 193
 194   /* Returns the contents of this Maybe<T> by pointer. Unsafe unless |isSome()|. */
 195   T* ptr()
 196   {
 197     MOZ_ASSERT(mIsSome);
 198     return &ref();
 199   }
 200
 201   const T* ptr() const
 202   {
 203     MOZ_ASSERT(mIsSome);
 204     return &ref();
 205   }
 206
 207   /*
 208    * Returns the contents of this Maybe<T> by pointer. If |isNothing()|,
 209    * returns the default value provided.
 210    */
 211   T* ptrOr(T* aDefault)
 212   {
 213     if (isSome()) {
 214       return ptr();
 215     }
 216     return aDefault;
 217   }
 218
 219   const T* ptrOr(const T* aDefault) const
 220   {
 221     if (isSome()) {
 222       return ptr();
 223     }
 224     return aDefault;
 225   }
 226
 227   /*
 228    * Returns the contents of this Maybe<T> by pointer. If |isNothing()|,
 229    * returns the value returned from the function or functor provided.
 230    */
 231   template<typename F>
 232   T* ptrOrFrom(F&& aFunc)
 233   {
 234     if (isSome()) {
 235       return ptr();
 236     }
 237     return aFunc();
 238   }
 239
 240   template<typename F>
 241   const T* ptrOrFrom(F&& aFunc) const
 242   {
 243     if (isSome()) {
 244       return ptr();
 245     }
 246     return aFunc();
 247   }
 248
 249   T* operator->()
 250   {
 251     MOZ_ASSERT(mIsSome);
 252     return ptr();
 253   }
 254
 255   const T* operator->() const
 256   {
 257     MOZ_ASSERT(mIsSome);
 258     return ptr();
 259   }
 260
 261   /* Returns the contents of this Maybe<T> by ref. Unsafe unless |isSome()|. */
 262   T& ref()
 263   {
 264     MOZ_ASSERT(mIsSome);
 265     return *mStorage.addr();
 266   }
 267
 268   const T& ref() const
 269   {
 270     MOZ_ASSERT(mIsSome);
 271     return *mStorage.addr();
 272   }
 273
 274   /*
 275    * Returns the contents of this Maybe<T> by ref. If |isNothing()|, returns
 276    * the default value provided.
 277    */
 278   T& refOr(T& aDefault)
 279   {
 280     if (isSome()) {
 281       return ref();
 282     }
 283     return aDefault;
 284   }
 285
 286   const T& refOr(const T& aDefault) const
 287   {
 288     if (isSome()) {
 289       return ref();
 290     }
 291     return aDefault;
 292   }
 293
 294   /*
 295    * Returns the contents of this Maybe<T> by ref. If |isNothing()|, returns the
 296    * value returned from the function or functor provided.
 297    */
 298   template<typename F>
 299   T& refOrFrom(F&& aFunc)
 300   {
 301     if (isSome()) {
 302       return ref();
 303     }
 304     return aFunc();
 305   }
 306
 307   template<typename F>
 308   const T& refOrFrom(F&& aFunc) const
 309   {
 310     if (isSome()) {
 311       return ref();
 312     }
 313     return aFunc();
 314   }
 315
 316   T& operator*()
 317   {
 318     MOZ_ASSERT(mIsSome);
 319     return ref();
 320   }
 321
 322   const T& operator*() const
 323   {
 324     MOZ_ASSERT(mIsSome);
 325     return ref();
 326   }
 327
 328   /* If |isSome()|, runs the provided function or functor on the contents of
 329    * this Maybe. */
 330   template<typename F>
 331   void apply(F&& aFunc)
 332   {
 333     if (isSome()) {
 334       aFunc(ref());
 335     }
 336   }
 337
 338   template<typename F>
 339   void apply(F&& aFunc) const
 340   {
 341     if (isSome()) {
 342       aFunc(ref());
 343     }
 344   }
 345
 346   /* Variant of |apply()| that takes an additional argument for the function. */
 347   template<typename F, typename A>
 348   void apply(F&& aFunc, A&& aArg)
 349   {
 350     if (isSome()) {
 351       aFunc(ref(), Forward<A>(aArg));
 352     }
 353   }
 354
 355   template<typename F, typename A>
 356   void apply(F&& aFunc, A&& aArg) const
 357   {
 358     if (isSome()) {
 359       aFunc(ref(), Forward<A>(aArg));
 360     }
 361   }
 362
 363   /*
 364    * If |isSome()|, runs the provided function and returns the result wrapped
 365    * in a Maybe. If |isNothing()|, returns an empty Maybe value.
 366    */
 367   template<typename R>
 368   Maybe<R> map(R(*aFunc)(T&))
 369   {
 370     if (isSome()) {
 371       Maybe<R> val;
 372       val.emplace(aFunc(ref()));
 373       return val;
 374     }
 375     return Maybe<R>();
 376   }
 377
 378   template<typename R>
 379   Maybe<R> map(R(*aFunc)(const T&)) const
 380   {
 381     if (isSome()) {
 382       Maybe<R> val;
 383       val.emplace(aFunc(ref()));
 384       return val;
 385     }
 386     return Maybe<R>();
 387   }
 388
 389   /* Variant of |map()| that takes an additional argument for the function. */
 390   template<typename R, typename FA, typename A>
 391   Maybe<R> map(R(*aFunc)(T&, FA), A&& aArg)
 392   {
 393     if (isSome()) {
 394       Maybe<R> val;
 395       val.emplace(aFunc(ref(), Forward<A>(aArg)));
 396       return val;
 397     }
 398     return Maybe<R>();
 399   }
 400
 401   template<typename R, typename FA, typename A>
 402   Maybe<R> map(R(*aFunc)(const T&, FA), A&& aArg) const
 403   {
 404     if (isSome()) {
 405       Maybe<R> val;
 406       val.emplace(aFunc(ref(), Forward<A>(aArg)));
 407       return val;
 408     }
 409     return Maybe<R>();
 410   }
 411
 412   /* If |isSome()|, empties this Maybe and destroys its contents. */
 413   void reset()
 414   {
 415     if (isSome()) {
 416       ref().~T();
 417       mIsSome = false;
 418     }
 419   }
 420
 421   /*
 422    * Constructs a T value in-place in this empty Maybe<T>'s storage. The
 423    * arguments to |emplace()| are the parameters to T's constructor.
 424    *
 425    * WARNING: You can't pass a literal nullptr to these methods without
 426    * hitting GCC 4.4-only (and hence B2G-only) compile errors.
 427    */
 428   void emplace()
 429   {
 430     MOZ_ASSERT(!mIsSome);
 431     ::new (mStorage.addr()) T();
 432     mIsSome = true;
 433   }
 434
 435   template<typename T1>
 436   void emplace(T1&& t1)
 437   {
 438     MOZ_ASSERT(!mIsSome);
 439     ::new (mStorage.addr()) T(Forward<T1>(t1));
 440     mIsSome = true;
 441   }
 442
 443   template<typename T1, typename T2>
 444   void emplace(T1&& t1, T2&& t2)
 445   {
 446     MOZ_ASSERT(!mIsSome);
 447     ::new (mStorage.addr()) T(Forward<T1>(t1), Forward<T2>(t2));
 448     mIsSome = true;
 449   }
 450
 451   template<typename T1, typename T2, typename T3>
 452   void emplace(T1&& t1, T2&& t2, T3&& t3)
 453   {
 454     MOZ_ASSERT(!mIsSome);
 455     ::new (mStorage.addr()) T(Forward<T1>(t1), Forward<T2>(t2), Forward<T3>(t3));
 456     mIsSome = true;
 457   }
 458
 459   template<typename T1, typename T2, typename T3, typename T4>
 460   void emplace(T1&& t1, T2&& t2, T3&& t3, T4&& t4)
 461   {
 462     MOZ_ASSERT(!mIsSome);
 463     ::new (mStorage.addr()) T(Forward<T1>(t1), Forward<T2>(t2), Forward<T3>(t3),
 464                               Forward<T4>(t4));
 465     mIsSome = true;
 466   }
 467
 468   template<typename T1, typename T2, typename T3, typename T4, typename T5>
 469   void emplace(T1&& t1, T2&& t2, T3&& t3, T4&& t4, T5&& t5)
 470   {
 471     MOZ_ASSERT(!mIsSome);
 472     ::new (mStorage.addr()) T(Forward<T1>(t1), Forward<T2>(t2), Forward<T3>(t3),
 473                               Forward<T4>(t4), Forward<T5>(t5));
 474     mIsSome = true;
 475   }
 476
 477   template<typename T1, typename T2, typename T3, typename T4, typename T5,
 478            typename T6>
 479   void emplace(T1&& t1, T2&& t2, T3&& t3, T4&& t4, T5&& t5, T6&& t6)
 480   {
 481     MOZ_ASSERT(!mIsSome);
 482     ::new (mStorage.addr()) T(Forward<T1>(t1), Forward<T2>(t2), Forward<T3>(t3),
 483                               Forward<T4>(t4), Forward<T5>(t5), Forward<T6>(t6));
 484     mIsSome = true;
 485   }
 486
 487   template<typename T1, typename T2, typename T3, typename T4, typename T5,
 488            typename T6, typename T7>
 489   void emplace(T1&& t1, T2&& t2, T3&& t3, T4&& t4, T5&& t5, T6&& t6,
 490                T7&& t7)
 491   {
 492     MOZ_ASSERT(!mIsSome);
 493     ::new (mStorage.addr()) T(Forward<T1>(t1), Forward<T2>(t2), Forward<T3>(t3),
 494                               Forward<T4>(t4), Forward<T5>(t5), Forward<T6>(t6),
 495                               Forward<T7>(t7));
 496     mIsSome = true;
 497   }
 498
 499   template<typename T1, typename T2, typename T3, typename T4, typename T5,
 500            typename T6, typename T7, typename T8>
 501   void emplace(T1&& t1, T2&& t2, T3&& t3, T4&& t4, T5&& t5, T6&& t6,
 502                T7&& t7, T8&& t8)
 503   {
 504     MOZ_ASSERT(!mIsSome);
 505     ::new (mStorage.addr()) T(Forward<T1>(t1), Forward<T2>(t2), Forward<T3>(t3),
 506                               Forward<T4>(t4), Forward<T5>(t5), Forward<T6>(t6),
 507                               Forward<T7>(t7), Forward<T8>(t8));
 508     mIsSome = true;
 509   }
 510
 511   template<typename T1, typename T2, typename T3, typename T4, typename T5,
 512            typename T6, typename T7, typename T8, typename T9>
 513   void emplace(T1&& t1, T2&& t2, T3&& t3, T4&& t4, T5&& t5, T6&& t6,
 514                T7&& t7, T8&& t8, T9&& t9)
 515   {
 516     MOZ_ASSERT(!mIsSome);
 517     ::new (mStorage.addr()) T(Forward<T1>(t1), Forward<T2>(t2), Forward<T3>(t3),
 518                               Forward<T4>(t4), Forward<T5>(t5), Forward<T6>(t6),
 519                               Forward<T7>(t7), Forward<T8>(t8), Forward<T9>(t9));
 520     mIsSome = true;
 521   }
 522
 523   template<typename T1, typename T2, typename T3, typename T4, typename T5,
 524            typename T6, typename T7, typename T8, typename T9, typename T10>
 525   void emplace(T1&& t1, T2&& t2, T3&& t3, T4&& t4, T5&& t5, T6&& t6,
 526                T7&& t7, T8&& t8, T9&& t9, T10&& t10)
 527   {
 528     MOZ_ASSERT(!mIsSome);
 529     ::new (mStorage.addr()) T(Forward<T1>(t1), Forward<T2>(t2), Forward<T3>(t3),
 530                               Forward<T4>(t4), Forward<T5>(t5), Forward<T6>(t6),
 531                               Forward<T7>(t7), Forward<T8>(t8), Forward<T9>(t9),
 532                               Forward<T1>(t10));
 533     mIsSome = true;
 534   }
 535 };
 536
 537 /*
 538  * Some() creates a Maybe<T> value containing the provided T value. If T has a
 539  * move constructor, it's used to make this as efficient as possible.
 540  *
 541  * Some() selects the type of Maybe it returns by removing any const, volatile,
 542  * or reference qualifiers from the type of the value you pass to it. This gives
 543  * it more intuitive behavior when used in expressions, but it also means that
 544  * if you need to construct a Maybe value that holds a const, volatile, or
 545  * reference value, you need to use emplace() instead.
 546  */
 547 template<typename T>
 548 Maybe<typename RemoveCV<typename RemoveReference<T>::Type>::Type>
 549 Some(T&& aValue)
 550 {
 551   typedef typename RemoveCV<typename RemoveReference<T>::Type>::Type U;
 552   Maybe<U> value;
 553   value.emplace(Forward<T>(aValue));
 554   return value;
 555 }
 556
 557 template<typename T>
 558 Maybe<typename RemoveCV<typename RemoveReference<T>::Type>::Type>
 559 ToMaybe(T* aPtr)
 560 {
 561   if (aPtr) {
 562     return Some(*aPtr);
 563   }
 564   return Nothing();
 565 }
 566
 567 /*
 568  * Two Maybe<T> values are equal if
 569  * - both are Nothing, or
 570  * - both are Some, and the values they contain are equal.
 571  */
 572 template<typename T> bool
 573 operator==(const Maybe<T>& aLHS, const Maybe<T>& aRHS)
 574 {
 575   if (aLHS.isNothing() != aRHS.isNothing()) {
 576     return false;
 577   }
 578   return aLHS.isNothing() || *aLHS == *aRHS;
 579 }
 580
 581 template<typename T> bool
 582 operator!=(const Maybe<T>& aLHS, const Maybe<T>& aRHS)
 583 {
 584   return !(aLHS == aRHS);
 585 }
 586
 587 /*
 588  * We support comparison to Nothing to allow reasonable expressions like:
 589  *   if (maybeValue == Nothing()) { ... }
 590  */
 591 template<typename T> bool
 592 operator==(const Maybe<T>& aLHS, const Nothing& aRHS)
 593 {
 594   return aLHS.isNothing();
 595 }
 596
 597 template<typename T> bool
 598 operator!=(const Maybe<T>& aLHS, const Nothing& aRHS)
 599 {
 600   return !(aLHS == aRHS);
 601 }
 602
 603 template<typename T> bool
 604 operator==(const Nothing& aLHS, const Maybe<T>& aRHS)
 605 {
 606   return aRHS.isNothing();
 607 }
 608
 609 template<typename T> bool
 610 operator!=(const Nothing& aLHS, const Maybe<T>& aRHS)
 611 {
 612   return !(aLHS == aRHS);
 613 }
 614
 615 /*
 616  * Maybe<T> values are ordered in the same way T values are ordered, except that
 617  * Nothing comes before anything else.
 618  */
 619 template<typename T> bool
 620 operator<(const Maybe<T>& aLHS, const Maybe<T>& aRHS)
 621 {
 622   if (aLHS.isNothing()) {
 623     return aRHS.isSome();
 624   }
 625   if (aRHS.isNothing()) {
 626     return false;
 627   }
 628   return *aLHS < *aRHS;
 629 }
 630
 631 template<typename T> bool
 632 operator>(const Maybe<T>& aLHS, const Maybe<T>& aRHS)
 633 {
 634   return !(aLHS < aRHS || aLHS == aRHS);
 635 }
 636
 637 template<typename T> bool
 638 operator<=(const Maybe<T>& aLHS, const Maybe<T>& aRHS)
 639 {
 640   return aLHS < aRHS || aLHS == aRHS;
 641 }
 642
 643 template<typename T> bool
 644 operator>=(const Maybe<T>& aLHS, const Maybe<T>& aRHS)
 645 {
 646   return !(aLHS < aRHS);
 647 }
 648
 649 } // namespace mozilla
 650
 651 #endif /* mozilla_Maybe_h */