2 * Copyright 2016 Facebook, Inc.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
20 * Optional - For conditional initialization of values, like boost::optional,
21 * but with support for move semantics and emplacement. Reference type support
22 * has not been included due to limited use cases and potential confusion with
23 * semantics of assignment: Assigning to an optional reference could quite
24 * reasonably copy its value or redirect the reference.
26 * Optional can be useful when a variable might or might not be needed:
28 * Optional<Logger> maybeLogger = ...;
30 * maybeLogger->log("hello");
33 * Optional enables a 'null' value for types which do not otherwise have
34 * nullability, especially useful for parameter passing:
36 * void testIterator(const unique_ptr<Iterator>& it,
37 * initializer_list<int> idsExpected,
38 * Optional<initializer_list<int>> ranksExpected = none) {
39 * for (int i = 0; it->next(); ++i) {
40 * EXPECT_EQ(it->doc().id(), idsExpected[i]);
41 * if (ranksExpected) {
42 * EXPECT_EQ(it->doc().rank(), (*ranksExpected)[i]);
47 * Optional models OptionalPointee, so calling 'get_pointer(opt)' will return a
48 * pointer to nullptr if the 'opt' is empty, and a pointer to the value if it is
51 * Optional<int> maybeInt = ...;
52 * if (int* v = get_pointer(maybeInt)) {
58 #include <type_traits>
63 namespace detail { struct NoneHelper {}; }
65 typedef int detail::NoneHelper::*None;
67 const None none = nullptr;
70 * gcc-4.7 warns about use of uninitialized memory around the use of storage_
71 * even though this is explicitly initialized at each point.
73 #if defined(__GNUC__) && !defined(__clang__)
74 # pragma GCC diagnostic push
75 # pragma GCC diagnostic ignored "-Wuninitialized"
76 # pragma GCC diagnostic ignored "-Wpragmas"
77 # pragma GCC diagnostic ignored "-Wmaybe-uninitialized"
80 class OptionalEmptyException : public std::runtime_error {
82 OptionalEmptyException()
83 : std::runtime_error("Empty Optional cannot be unwrapped") {}
89 typedef Value value_type;
91 static_assert(!std::is_reference<Value>::value,
92 "Optional may not be used with reference types");
93 static_assert(!std::is_abstract<Value>::value,
94 "Optional may not be used with abstract types");
99 Optional(const Optional& src)
100 noexcept(std::is_nothrow_copy_constructible<Value>::value) {
102 if (src.hasValue()) {
103 construct(src.value());
107 Optional(Optional&& src)
108 noexcept(std::is_nothrow_move_constructible<Value>::value) {
110 if (src.hasValue()) {
111 construct(std::move(src.value()));
116 /* implicit */ Optional(const None&) noexcept {
119 /* implicit */ Optional(Value&& newValue)
120 noexcept(std::is_nothrow_move_constructible<Value>::value) {
121 construct(std::move(newValue));
124 /* implicit */ Optional(const Value& newValue)
125 noexcept(std::is_nothrow_copy_constructible<Value>::value) {
129 void assign(const None&) {
133 void assign(Optional&& src) {
135 if (src.hasValue()) {
136 assign(std::move(src.value()));
144 void assign(const Optional& src) {
145 if (src.hasValue()) {
152 void assign(Value&& newValue) {
154 storage_.value = std::move(newValue);
156 construct(std::move(newValue));
160 void assign(const Value& newValue) {
162 storage_.value = newValue;
169 Optional& operator=(Arg&& arg) {
170 assign(std::forward<Arg>(arg));
174 Optional& operator=(Optional &&other)
175 noexcept (std::is_nothrow_move_assignable<Value>::value) {
177 assign(std::move(other));
181 Optional& operator=(const Optional &other)
182 noexcept (std::is_nothrow_copy_assignable<Value>::value) {
188 template<class... Args>
189 void emplace(Args&&... args) {
191 construct(std::forward<Args>(args)...);
198 const Value& value() const& {
200 return storage_.value;
205 return storage_.value;
210 return std::move(storage_.value);
213 const Value* get_pointer() const& {
214 return storage_.hasValue ? &storage_.value : nullptr;
216 Value* get_pointer() & {
217 return storage_.hasValue ? &storage_.value : nullptr;
219 Value* get_pointer() && = delete;
221 bool hasValue() const { return storage_.hasValue; }
223 explicit operator bool() const {
227 const Value& operator*() const& { return value(); }
228 Value& operator*() & { return value(); }
229 Value operator*() && { return std::move(value()); }
231 const Value* operator->() const { return &value(); }
232 Value* operator->() { return &value(); }
234 // Return a copy of the value if set, or a given default if not.
236 Value value_or(U&& dflt) const& {
237 if (storage_.hasValue) {
238 return storage_.value;
241 return std::forward<U>(dflt);
245 Value value_or(U&& dflt) && {
246 if (storage_.hasValue) {
247 return std::move(storage_.value);
250 return std::forward<U>(dflt);
254 void require_value() const {
255 if (!storage_.hasValue) {
256 throw OptionalEmptyException();
260 template<class... Args>
261 void construct(Args&&... args) {
262 const void* ptr = &storage_.value;
263 // for supporting const types
264 new(const_cast<void*>(ptr)) Value(std::forward<Args>(args)...);
265 storage_.hasValue = true;
268 struct StorageTriviallyDestructible {
270 union { Value value; };
273 StorageTriviallyDestructible() : hasValue{false} {}
280 struct StorageNonTriviallyDestructible {
282 union { Value value; };
285 StorageNonTriviallyDestructible() : hasValue{false} {}
287 ~StorageNonTriviallyDestructible() {
300 typename std::conditional<std::is_trivially_destructible<Value>::value,
301 StorageTriviallyDestructible,
302 StorageNonTriviallyDestructible>::type;
307 #if defined(__GNUC__) && !defined(__clang__)
308 #pragma GCC diagnostic pop
312 const T* get_pointer(const Optional<T>& opt) {
313 return opt.get_pointer();
317 T* get_pointer(Optional<T>& opt) {
318 return opt.get_pointer();
322 void swap(Optional<T>& a, Optional<T>& b) {
323 if (a.hasValue() && b.hasValue()) {
326 swap(a.value(), b.value());
327 } else if (a.hasValue() || b.hasValue()) {
328 std::swap(a, b); // fall back to default implementation if they're mixed.
333 class Opt = Optional<typename std::decay<T>::type>>
334 Opt make_optional(T&& v) {
335 return Opt(std::forward<T>(v));
338 ///////////////////////////////////////////////////////////////////////////////
342 bool operator==(const Optional<V>& a, const V& b) {
343 return a.hasValue() && a.value() == b;
347 bool operator!=(const Optional<V>& a, const V& b) {
352 bool operator==(const V& a, const Optional<V>& b) {
353 return b.hasValue() && b.value() == a;
357 bool operator!=(const V& a, const Optional<V>& b) {
362 bool operator==(const Optional<V>& a, const Optional<V>& b) {
363 if (a.hasValue() != b.hasValue()) { return false; }
364 if (a.hasValue()) { return a.value() == b.value(); }
369 bool operator!=(const Optional<V>& a, const Optional<V>& b) {
374 bool operator< (const Optional<V>& a, const Optional<V>& b) {
375 if (a.hasValue() != b.hasValue()) { return a.hasValue() < b.hasValue(); }
376 if (a.hasValue()) { return a.value() < b.value(); }
381 bool operator> (const Optional<V>& a, const Optional<V>& b) {
386 bool operator<=(const Optional<V>& a, const Optional<V>& b) {
391 bool operator>=(const Optional<V>& a, const Optional<V>& b) {
395 // Suppress comparability of Optional<T> with T, despite implicit conversion.
396 template<class V> bool operator< (const Optional<V>&, const V& other) = delete;
397 template<class V> bool operator<=(const Optional<V>&, const V& other) = delete;
398 template<class V> bool operator>=(const Optional<V>&, const V& other) = delete;
399 template<class V> bool operator> (const Optional<V>&, const V& other) = delete;
400 template<class V> bool operator< (const V& other, const Optional<V>&) = delete;
401 template<class V> bool operator<=(const V& other, const Optional<V>&) = delete;
402 template<class V> bool operator>=(const V& other, const Optional<V>&) = delete;
403 template<class V> bool operator> (const V& other, const Optional<V>&) = delete;
405 ///////////////////////////////////////////////////////////////////////////////