folly/Optional.h

   1 /*
   2  * Copyright 2014 Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef FOLLY_OPTIONAL_H_
  18 #define FOLLY_OPTIONAL_H_
  19
  20 /*
  21  * Optional - For conditional initialization of values, like boost::optional,
  22  * but with support for move semantics and emplacement.  Reference type support
  23  * has not been included due to limited use cases and potential confusion with
  24  * semantics of assignment: Assigning to an optional reference could quite
  25  * reasonably copy its value or redirect the reference.
  26  *
  27  * Optional can be useful when a variable might or might not be needed:
  28  *
  29  *  Optional<Logger> maybeLogger = ...;
  30  *  if (maybeLogger) {
  31  *    maybeLogger->log("hello");
  32  *  }
  33  *
  34  * Optional enables a 'null' value for types which do not otherwise have
  35  * nullability, especially useful for parameter passing:
  36  *
  37  * void testIterator(const unique_ptr<Iterator>& it,
  38  *                   initializer_list<int> idsExpected,
  39  *                   Optional<initializer_list<int>> ranksExpected = none) {
  40  *   for (int i = 0; it->next(); ++i) {
  41  *     EXPECT_EQ(it->doc().id(), idsExpected[i]);
  42  *     if (ranksExpected) {
  43  *       EXPECT_EQ(it->doc().rank(), (*ranksExpected)[i]);
  44  *     }
  45  *   }
  46  * }
  47  *
  48  * Optional models OptionalPointee, so calling 'get_pointer(opt)' will return a
  49  * pointer to nullptr if the 'opt' is empty, and a pointer to the value if it is
  50  * not:
  51  *
  52  *  Optional<int> maybeInt = ...;
  53  *  if (int* v = get_pointer(maybeInt)) {
  54  *    cout << *v << endl;
  55  *  }
  56  */
  57 #include <utility>
  58 #include <cassert>
  59 #include <cstddef>
  60 #include <type_traits>
  61
  62 #include <boost/operators.hpp>
  63
  64 #include <folly/Portability.h>
  65
  66 namespace folly {
  67
  68 namespace detail { struct NoneHelper {}; }
  69
  70 typedef int detail::NoneHelper::*None;
  71
  72 const None none = nullptr;
  73
  74 /**
  75  * gcc-4.7 warns about use of uninitialized memory around the use of storage_
  76  * even though this is explicitly initialized at each point.
  77  */
  78 #if defined(__GNUC__) && !defined(__clang__)
  79 # pragma GCC diagnostic push
  80 # pragma GCC diagnostic ignored "-Wuninitialized"
  81 # pragma GCC diagnostic ignored "-Wpragmas"
  82 # pragma GCC diagnostic ignored "-Wmaybe-uninitialized"
  83 #endif // __GNUC__
  84
  85 template<class Value>
  86 class Optional {
  87  public:
  88   static_assert(!std::is_reference<Value>::value,
  89                 "Optional may not be used with reference types");
  90
  91   Optional()
  92     : hasValue_(false) {
  93   }
  94
  95   Optional(const Optional& src)
  96     noexcept(std::is_nothrow_copy_constructible<Value>::value) {
  97
  98     if (src.hasValue()) {
  99       construct(src.value());
 100     } else {
 101       hasValue_ = false;
 102     }
 103   }
 104
 105   Optional(Optional&& src)
 106     noexcept(std::is_nothrow_move_constructible<Value>::value) {
 107
 108     if (src.hasValue()) {
 109       construct(std::move(src.value()));
 110       src.clear();
 111     } else {
 112       hasValue_ = false;
 113     }
 114   }
 115
 116   /* implicit */ Optional(const None&) noexcept
 117     : hasValue_(false) {
 118   }
 119
 120   /* implicit */ Optional(Value&& newValue)
 121     noexcept(std::is_nothrow_move_constructible<Value>::value) {
 122     construct(std::move(newValue));
 123   }
 124
 125   /* implicit */ Optional(const Value& newValue)
 126     noexcept(std::is_nothrow_copy_constructible<Value>::value) {
 127     construct(newValue);
 128   }
 129
 130   ~Optional() noexcept {
 131     clear();
 132   }
 133
 134   void assign(const None&) {
 135     clear();
 136   }
 137
 138   void assign(Optional&& src) {
 139     if (src.hasValue()) {
 140       assign(std::move(src.value()));
 141       src.clear();
 142     } else {
 143       clear();
 144     }
 145   }
 146
 147   void assign(const Optional& src) {
 148     if (src.hasValue()) {
 149       assign(src.value());
 150     } else {
 151       clear();
 152     }
 153   }
 154
 155   void assign(Value&& newValue) {
 156     if (hasValue()) {
 157       value_ = std::move(newValue);
 158     } else {
 159       construct(std::move(newValue));
 160     }
 161   }
 162
 163   void assign(const Value& newValue) {
 164     if (hasValue()) {
 165       value_ = newValue;
 166     } else {
 167       construct(newValue);
 168     }
 169   }
 170
 171   template<class Arg>
 172   Optional& operator=(Arg&& arg) {
 173     assign(std::forward<Arg>(arg));
 174     return *this;
 175   }
 176
 177   Optional& operator=(Optional &&other)
 178     noexcept (std::is_nothrow_move_assignable<Value>::value) {
 179
 180     assign(std::move(other));
 181     return *this;
 182   }
 183
 184   Optional& operator=(const Optional &other)
 185     noexcept (std::is_nothrow_copy_assignable<Value>::value) {
 186
 187     assign(other);
 188     return *this;
 189   }
 190
 191   template<class... Args>
 192   void emplace(Args&&... args) {
 193     clear();
 194     construct(std::forward<Args>(args)...);
 195   }
 196
 197   void clear() {
 198     if (hasValue()) {
 199       hasValue_ = false;
 200       value_.~Value();
 201     }
 202   }
 203
 204   const Value& value() const {
 205     assert(hasValue());
 206     return value_;
 207   }
 208
 209   Value& value() {
 210     assert(hasValue());
 211     return value_;
 212   }
 213
 214   bool hasValue() const { return hasValue_; }
 215
 216   explicit operator bool() const {
 217     return hasValue();
 218   }
 219
 220   const Value& operator*() const { return value(); }
 221         Value& operator*()       { return value(); }
 222
 223   const Value* operator->() const { return &value(); }
 224         Value* operator->()       { return &value(); }
 225
 226  private:
 227   template<class... Args>
 228   void construct(Args&&... args) {
 229     const void* ptr = &value_;
 230     // for supporting const types
 231     new(const_cast<void*>(ptr)) Value(std::forward<Args>(args)...);
 232     hasValue_ = true;
 233   }
 234
 235   // uninitialized
 236   union { Value value_; };
 237   bool hasValue_;
 238 };
 239
 240 #if defined(__GNUC__) && !defined(__clang__)
 241 #pragma GCC diagnostic pop
 242 #endif
 243
 244 template<class T>
 245 const T* get_pointer(const Optional<T>& opt) {
 246   return opt ? &opt.value() : nullptr;
 247 }
 248
 249 template<class T>
 250 T* get_pointer(Optional<T>& opt) {
 251   return opt ? &opt.value() : nullptr;
 252 }
 253
 254 template<class T>
 255 void swap(Optional<T>& a, Optional<T>& b) {
 256   if (a.hasValue() && b.hasValue()) {
 257     // both full
 258     using std::swap;
 259     swap(a.value(), b.value());
 260   } else if (a.hasValue() || b.hasValue()) {
 261     std::swap(a, b); // fall back to default implementation if they're mixed.
 262   }
 263 }
 264
 265 template<class T,
 266          class Opt = Optional<typename std::decay<T>::type>>
 267 Opt make_optional(T&& v) {
 268   return Opt(std::forward<T>(v));
 269 }
 270
 271 template<class V>
 272 bool operator< (const Optional<V>& a, const Optional<V>& b) {
 273   if (a.hasValue() != b.hasValue()) { return a.hasValue() < b.hasValue(); }
 274   if (a.hasValue())                 { return a.value()    < b.value(); }
 275   return false;
 276 }
 277
 278 template<class V>
 279 bool operator==(const Optional<V>& a, const Optional<V>& b) {
 280   if (a.hasValue() != b.hasValue()) { return false; }
 281   if (a.hasValue())                 { return a.value() == b.value(); }
 282   return true;
 283 }
 284
 285 template<class V>
 286 bool operator<=(const Optional<V>& a, const Optional<V>& b) {
 287   return !(b < a);
 288 }
 289
 290 template<class V>
 291 bool operator!=(const Optional<V>& a, const Optional<V>& b) {
 292   return !(b == a);
 293 }
 294
 295 template<class V>
 296 bool operator>=(const Optional<V>& a, const Optional<V>& b) {
 297   return !(a < b);
 298 }
 299
 300 template<class V>
 301 bool operator> (const Optional<V>& a, const Optional<V>& b) {
 302   return b < a;
 303 }
 304
 305 // To supress comparability of Optional<T> with T, despite implicit conversion.
 306 template<class V> bool operator< (const Optional<V>&, const V& other) = delete;
 307 template<class V> bool operator<=(const Optional<V>&, const V& other) = delete;
 308 template<class V> bool operator==(const Optional<V>&, const V& other) = delete;
 309 template<class V> bool operator!=(const Optional<V>&, const V& other) = delete;
 310 template<class V> bool operator>=(const Optional<V>&, const V& other) = delete;
 311 template<class V> bool operator> (const Optional<V>&, const V& other) = delete;
 312 template<class V> bool operator< (const V& other, const Optional<V>&) = delete;
 313 template<class V> bool operator<=(const V& other, const Optional<V>&) = delete;
 314 template<class V> bool operator==(const V& other, const Optional<V>&) = delete;
 315 template<class V> bool operator!=(const V& other, const Optional<V>&) = delete;
 316 template<class V> bool operator>=(const V& other, const Optional<V>&) = delete;
 317 template<class V> bool operator> (const V& other, const Optional<V>&) = delete;
 318
 319 } // namespace folly
 320
 321 #endif//FOLLY_OPTIONAL_H_