2 * Copyright 2017 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)) {
60 #include <type_traits>
63 #include <folly/Portability.h>
64 #include <folly/Utility.h>
71 // Allow each translation unit to control its own -fexceptions setting.
72 // If exceptions are disabled, std::terminate() will be called instead of
73 // throwing OptionalEmptyException when the condition fails.
74 [[noreturn]] void throw_optional_empty_exception();
77 typedef int detail::NoneHelper::*None;
79 const None none = nullptr;
81 class OptionalEmptyException : public std::runtime_error {
83 OptionalEmptyException()
84 : std::runtime_error("Empty Optional cannot be unwrapped") {}
87 template <class Value>
90 typedef Value value_type;
93 !std::is_reference<Value>::value,
94 "Optional may not be used with reference types");
96 !std::is_abstract<Value>::value,
97 "Optional may not be used with abstract types");
99 Optional() noexcept {}
101 Optional(const Optional& src) noexcept(
102 std::is_nothrow_copy_constructible<Value>::value) {
103 if (src.hasValue()) {
104 construct(src.value());
108 Optional(Optional&& src) noexcept(
109 std::is_nothrow_move_constructible<Value>::value) {
110 if (src.hasValue()) {
111 construct(std::move(src.value()));
116 /* implicit */ Optional(const None&) noexcept {}
118 /* implicit */ Optional(Value&& newValue) noexcept(
119 std::is_nothrow_move_constructible<Value>::value) {
120 construct(std::move(newValue));
123 /* implicit */ Optional(const Value& newValue) noexcept(
124 std::is_nothrow_copy_constructible<Value>::value) {
128 template <typename... Args>
129 explicit Optional(in_place_t, Args&&... args) noexcept(
130 std::is_nothrow_constructible<Value, Args...>::value) {
131 construct(std::forward<Args>(args)...);
134 void assign(const None&) {
138 void assign(Optional&& src) {
140 if (src.hasValue()) {
141 assign(std::move(src.value()));
149 void assign(const Optional& src) {
150 if (src.hasValue()) {
157 void assign(Value&& newValue) {
159 storage_.value = std::move(newValue);
161 construct(std::move(newValue));
165 void assign(const Value& newValue) {
167 storage_.value = newValue;
174 Optional& operator=(Arg&& arg) {
175 assign(std::forward<Arg>(arg));
179 Optional& operator=(Optional&& other) noexcept(
180 std::is_nothrow_move_assignable<Value>::value) {
181 assign(std::move(other));
185 Optional& operator=(const Optional& other) noexcept(
186 std::is_nothrow_copy_assignable<Value>::value) {
191 template <class... Args>
192 void emplace(Args&&... args) {
194 construct(std::forward<Args>(args)...);
201 const Value& value() const & {
203 return storage_.value;
208 return storage_.value;
213 return std::move(storage_.value);
216 const Value&& value() const && {
218 return std::move(storage_.value);
221 const Value* get_pointer() const & {
222 return storage_.hasValue ? &storage_.value : nullptr;
224 Value* get_pointer() & {
225 return storage_.hasValue ? &storage_.value : nullptr;
227 Value* get_pointer() && = delete;
229 bool hasValue() const {
230 return storage_.hasValue;
233 explicit operator bool() const {
237 const Value& operator*() const & {
240 Value& operator*() & {
243 const Value&& operator*() const && {
244 return std::move(value());
246 Value&& operator*() && {
247 return std::move(value());
250 const Value* operator->() const {
253 Value* operator->() {
257 // Return a copy of the value if set, or a given default if not.
259 Value value_or(U&& dflt) const & {
260 if (storage_.hasValue) {
261 return storage_.value;
264 return std::forward<U>(dflt);
268 Value value_or(U&& dflt) && {
269 if (storage_.hasValue) {
270 return std::move(storage_.value);
273 return std::forward<U>(dflt);
277 void require_value() const {
278 if (!storage_.hasValue) {
279 detail::throw_optional_empty_exception();
283 template <class... Args>
284 void construct(Args&&... args) {
285 const void* ptr = &storage_.value;
286 // for supporting const types
287 new (const_cast<void*>(ptr)) Value(std::forward<Args>(args)...);
288 storage_.hasValue = true;
291 struct StorageTriviallyDestructible {
292 // The union trick allows to initialize the Optional's memory,
293 // so that compiler/tools don't complain about uninitialized memory,
294 // without actually calling Value's default constructor.
295 // The rest of the implementation enforces that hasValue/value are
300 bool paddingForHasValue_[1];
305 StorageTriviallyDestructible() : hasValue{false} {}
312 struct StorageNonTriviallyDestructible {
313 // See StorageTriviallyDestructible's union
317 bool paddingForHasValue_[1];
323 // These are both informational warnings, but they trigger rare enough
324 // that we've left them enabled.
325 FOLLY_MSVC_DISABLE_WARNING(4587) // constructor of .value is not called
326 FOLLY_MSVC_DISABLE_WARNING(4588) // destructor of .value is not called
327 StorageNonTriviallyDestructible() : hasValue{false} {}
328 ~StorageNonTriviallyDestructible() {
341 using Storage = typename std::conditional<
342 std::is_trivially_destructible<Value>::value,
343 StorageTriviallyDestructible,
344 StorageNonTriviallyDestructible>::type;
350 const T* get_pointer(const Optional<T>& opt) {
351 return opt.get_pointer();
355 T* get_pointer(Optional<T>& opt) {
356 return opt.get_pointer();
360 void swap(Optional<T>& a, Optional<T>& b) {
361 if (a.hasValue() && b.hasValue()) {
364 swap(a.value(), b.value());
365 } else if (a.hasValue() || b.hasValue()) {
366 std::swap(a, b); // fall back to default implementation if they're mixed.
370 template <class T, class Opt = Optional<typename std::decay<T>::type>>
371 Opt make_optional(T&& v) {
372 return Opt(std::forward<T>(v));
375 ///////////////////////////////////////////////////////////////////////////////
378 template <class U, class V>
379 bool operator==(const Optional<U>& a, const V& b) {
380 return a.hasValue() && a.value() == b;
383 template <class U, class V>
384 bool operator!=(const Optional<U>& a, const V& b) {
388 template <class U, class V>
389 bool operator==(const U& a, const Optional<V>& b) {
390 return b.hasValue() && b.value() == a;
393 template <class U, class V>
394 bool operator!=(const U& a, const Optional<V>& b) {
398 template <class U, class V>
399 bool operator==(const Optional<U>& a, const Optional<V>& b) {
400 if (a.hasValue() != b.hasValue()) {
404 return a.value() == b.value();
409 template <class U, class V>
410 bool operator!=(const Optional<U>& a, const Optional<V>& b) {
414 template <class U, class V>
415 bool operator<(const Optional<U>& a, const Optional<V>& b) {
416 if (a.hasValue() != b.hasValue()) {
417 return a.hasValue() < b.hasValue();
420 return a.value() < b.value();
425 template <class U, class V>
426 bool operator>(const Optional<U>& a, const Optional<V>& b) {
430 template <class U, class V>
431 bool operator<=(const Optional<U>& a, const Optional<V>& b) {
435 template <class U, class V>
436 bool operator>=(const Optional<U>& a, const Optional<V>& b) {
440 // Suppress comparability of Optional<T> with T, despite implicit conversion.
442 bool operator<(const Optional<V>&, const V& other) = delete;
444 bool operator<=(const Optional<V>&, const V& other) = delete;
446 bool operator>=(const Optional<V>&, const V& other) = delete;
448 bool operator>(const Optional<V>&, const V& other) = delete;
450 bool operator<(const V& other, const Optional<V>&) = delete;
452 bool operator<=(const V& other, const Optional<V>&) = delete;
454 bool operator>=(const V& other, const Optional<V>&) = delete;
456 bool operator>(const V& other, const Optional<V>&) = delete;
458 ///////////////////////////////////////////////////////////////////////////////
462 // Allow usage of Optional<T> in std::unordered_map and std::unordered_set
463 FOLLY_NAMESPACE_STD_BEGIN
465 struct hash<folly::Optional<T>> {
466 size_t operator()(folly::Optional<T> const& obj) const {
467 if (!obj.hasValue()) {
470 return hash<typename remove_const<T>::type>()(*obj);
473 FOLLY_NAMESPACE_STD_END