2 * Copyright 2015 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.
17 #ifndef FOLLY_OPTIONAL_H_
18 #define FOLLY_OPTIONAL_H_
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.
27 * Optional can be useful when a variable might or might not be needed:
29 * Optional<Logger> maybeLogger = ...;
31 * maybeLogger->log("hello");
34 * Optional enables a 'null' value for types which do not otherwise have
35 * nullability, especially useful for parameter passing:
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]);
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
52 * Optional<int> maybeInt = ...;
53 * if (int* v = get_pointer(maybeInt)) {
59 #include <type_traits>
62 #include <boost/operators.hpp>
64 #include <folly/Portability.h>
68 namespace detail { struct NoneHelper {}; }
70 typedef int detail::NoneHelper::*None;
72 const None none = nullptr;
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.
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"
85 class OptionalEmptyException : public std::runtime_error {
87 OptionalEmptyException()
88 : std::runtime_error("Empty Optional cannot be unwrapped") {}
94 typedef Value value_type;
96 static_assert(!std::is_reference<Value>::value,
97 "Optional may not be used with reference types");
98 static_assert(!std::is_abstract<Value>::value,
99 "Optional may not be used with abstract types");
105 Optional(const Optional& src)
106 noexcept(std::is_nothrow_copy_constructible<Value>::value) {
108 if (src.hasValue()) {
109 construct(src.value());
115 Optional(Optional&& src)
116 noexcept(std::is_nothrow_move_constructible<Value>::value) {
118 if (src.hasValue()) {
119 construct(std::move(src.value()));
126 /* implicit */ Optional(const None&) noexcept
130 /* implicit */ Optional(Value&& newValue)
131 noexcept(std::is_nothrow_move_constructible<Value>::value) {
132 construct(std::move(newValue));
135 /* implicit */ Optional(const Value& newValue)
136 noexcept(std::is_nothrow_copy_constructible<Value>::value) {
140 ~Optional() noexcept {
144 void assign(const None&) {
148 void assign(Optional&& src) {
150 if (src.hasValue()) {
151 assign(std::move(src.value()));
159 void assign(const Optional& src) {
160 if (src.hasValue()) {
167 void assign(Value&& newValue) {
169 value_ = std::move(newValue);
171 construct(std::move(newValue));
175 void assign(const Value& newValue) {
184 Optional& operator=(Arg&& arg) {
185 assign(std::forward<Arg>(arg));
189 Optional& operator=(Optional &&other)
190 noexcept (std::is_nothrow_move_assignable<Value>::value) {
192 assign(std::move(other));
196 Optional& operator=(const Optional &other)
197 noexcept (std::is_nothrow_copy_assignable<Value>::value) {
203 template<class... Args>
204 void emplace(Args&&... args) {
206 construct(std::forward<Args>(args)...);
216 const Value& value() const& {
228 return std::move(value_);
231 const Value* get_pointer() const& { return hasValue_ ? &value_ : nullptr; }
232 Value* get_pointer() & { return hasValue_ ? &value_ : nullptr; }
233 Value* get_pointer() && = delete;
235 bool hasValue() const { return hasValue_; }
237 explicit operator bool() const {
241 const Value& operator*() const& { return value(); }
242 Value& operator*() & { return value(); }
243 Value operator*() && { return std::move(value()); }
245 const Value* operator->() const { return &value(); }
246 Value* operator->() { return &value(); }
248 // Return a copy of the value if set, or a given default if not.
250 Value value_or(U&& dflt) const& {
251 return hasValue_ ? value_ : std::forward<U>(dflt);
255 Value value_or(U&& dflt) && {
256 return hasValue_ ? std::move(value_) : std::forward<U>(dflt);
260 void require_value() const {
262 throw OptionalEmptyException();
266 template<class... Args>
267 void construct(Args&&... args) {
268 const void* ptr = &value_;
269 // for supporting const types
270 new(const_cast<void*>(ptr)) Value(std::forward<Args>(args)...);
275 union { Value value_; };
279 #if defined(__GNUC__) && !defined(__clang__)
280 #pragma GCC diagnostic pop
284 const T* get_pointer(const Optional<T>& opt) {
285 return opt.get_pointer();
289 T* get_pointer(Optional<T>& opt) {
290 return opt.get_pointer();
294 void swap(Optional<T>& a, Optional<T>& b) {
295 if (a.hasValue() && b.hasValue()) {
298 swap(a.value(), b.value());
299 } else if (a.hasValue() || b.hasValue()) {
300 std::swap(a, b); // fall back to default implementation if they're mixed.
305 class Opt = Optional<typename std::decay<T>::type>>
306 Opt make_optional(T&& v) {
307 return Opt(std::forward<T>(v));
310 ///////////////////////////////////////////////////////////////////////////////
314 bool operator==(const Optional<V>& a, const V& b) {
315 return a.hasValue() && a.value() == b;
319 bool operator!=(const Optional<V>& a, const V& b) {
324 bool operator==(const V& a, const Optional<V>& b) {
325 return b.hasValue() && b.value() == a;
329 bool operator!=(const V& a, const Optional<V>& b) {
334 bool operator==(const Optional<V>& a, const Optional<V>& b) {
335 if (a.hasValue() != b.hasValue()) { return false; }
336 if (a.hasValue()) { return a.value() == b.value(); }
341 bool operator!=(const Optional<V>& a, const Optional<V>& b) {
346 bool operator< (const Optional<V>& a, const Optional<V>& b) {
347 if (a.hasValue() != b.hasValue()) { return a.hasValue() < b.hasValue(); }
348 if (a.hasValue()) { return a.value() < b.value(); }
353 bool operator> (const Optional<V>& a, const Optional<V>& b) {
358 bool operator<=(const Optional<V>& a, const Optional<V>& b) {
363 bool operator>=(const Optional<V>& a, const Optional<V>& b) {
367 // Suppress comparability of Optional<T> with T, despite implicit conversion.
368 template<class V> bool operator< (const Optional<V>&, const V& other) = delete;
369 template<class V> bool operator<=(const Optional<V>&, const V& other) = delete;
370 template<class V> bool operator>=(const Optional<V>&, const V& other) = delete;
371 template<class V> bool operator> (const Optional<V>&, const V& other) = delete;
372 template<class V> bool operator< (const V& other, const Optional<V>&) = delete;
373 template<class V> bool operator<=(const V& other, const Optional<V>&) = delete;
374 template<class V> bool operator>=(const V& other, const Optional<V>&) = delete;
375 template<class V> bool operator> (const V& other, const Optional<V>&) = delete;
377 ///////////////////////////////////////////////////////////////////////////////
381 #endif // FOLLY_OPTIONAL_H_