3 Forward declares `boost::hana::optional`.
5 @copyright Louis Dionne 2013-2016
6 Distributed under the Boost Software License, Version 1.0.
7 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
10 #ifndef BOOST_HANA_FWD_OPTIONAL_HPP
11 #define BOOST_HANA_FWD_OPTIONAL_HPP
13 #include <boost/hana/config.hpp>
14 #include <boost/hana/detail/operators/adl.hpp>
15 #include <boost/hana/fwd/core/make.hpp>
18 BOOST_HANA_NAMESPACE_BEGIN
19 //! @ingroup group-datatypes
20 //! Optional value whose optional-ness is known at compile-time.
22 //! An `optional` either contains a value (represented as `just(x)`), or
23 //! it is empty (represented as `nothing`). In essence, `hana::optional`
24 //! is pretty much like a `boost::optional` or the upcoming `std::optional`,
25 //! except for the fact that whether a `hana::optional` is empty or not is
26 //! known at compile-time. This can be particularly useful for returning
27 //! from a function that might fail, but whose reason for failing is not
28 //! important. Of course, whether the function will fail has to be known
31 //! This is really an important difference between `hana::optional` and
32 //! `std::optional`. Unlike `std::optional<T>{}` and `std::optional<T>{x}`
33 //! who share the same type (`std::optional<T>`), `hana::just(x)` and
34 //! `hana::nothing` do not share the same type, since the state of the
35 //! optional has to be known at compile-time. Hence, whether a `hana::just`
36 //! or a `hana::nothing` will be returned from a function has to be known
37 //! at compile-time for the return type of that function to be computable
38 //! by the compiler. This makes `hana::optional` well suited for static
39 //! metaprogramming tasks, but very poor for anything dynamic.
42 //! Interoperation with `type`s
43 //! ---------------------------
44 //! When a `just` contains an object of type `T` which is a `type`,
45 //! it has a nested `::%type` alias equivalent to `T::%type`. `nothing`,
46 //! however, never has a nested `::%type` alias. If `t` is a `type`,
47 //! this allows `decltype(just(t))` to be seen as a nullary metafunction
48 //! equivalent to `decltype(t)`. Along with the `sfinae` function,
49 //! this allows `hana::optional` to interact seamlessly with
50 //! SFINAE-friendly metafunctions.
52 //! @include example/optional/sfinae_friendly_metafunctions.cpp
58 //! Two `optional`s are equal if and only if they are both empty or they
59 //! both contain a value and those values are equal.
60 //! @include example/optional/comparable.cpp
63 //! Optional values can be ordered by considering the value they are
64 //! holding, if any. To handle the case of an empty optional value, we
65 //! arbitrarily set `nothing` as being less than any other `just`. Hence,
67 //! just(x) < just(y) if and only if x < y
68 //! nothing < just(anything)
71 //! @include example/optional/orderable.cpp
74 //! An optional value can be seen as a list containing either one element
75 //! (`just(x)`) or no elements at all (`nothing`). As such, mapping
76 //! a function over an optional value is equivalent to applying it to
77 //! its value if there is one, and to `nothing` otherwise:
79 //! transform(just(x), f) == just(f(x))
80 //! transform(nothing, f) == nothing
83 //! @include example/optional/functor.cpp
85 //! 4. `Applicative`\n
86 //! First, a value can be made optional with `lift<optional_tag>`, which
87 //! is equivalent to `just`. Second, one can feed an optional value to an
88 //! optional function with `ap`, which will return `just(f(x))` if there
89 //! is both a function _and_ a value, and `nothing` otherwise:
91 //! ap(just(f), just(x)) == just(f(x))
92 //! ap(nothing, just(x)) == nothing
93 //! ap(just(f), nothing) == nothing
94 //! ap(nothing, nothing) == nothing
97 //! @include example/optional/applicative.cpp
98 //! A more complex example:
99 //! @include example/optional/applicative.complex.cpp
102 //! The `Monad` model makes it easy to compose actions that might fail.
103 //! One can feed an optional value if there is one into a function with
104 //! `chain`, which will return `nothing` if there is no value. Finally,
105 //! optional-optional values can have their redundant level of optionality
106 //! removed with `flatten`. Also note that the `|` operator can be used in
107 //! place of the `chain` function.
109 //! @include example/optional/monad.cpp
112 //! The `MonadPlus` model allows choosing the first valid value out of
113 //! two optional values with `concat`. If both optional values are
114 //! `nothing`s, `concat` will return `nothing`.
116 //! @include example/optional/monad_plus.cpp
119 //! Folding an optional value is equivalent to folding a list containing
120 //! either no elements (for `nothing`) or `x` (for `just(x)`).
122 //! @include example/optional/foldable.cpp
124 //! 8. `Searchable`\n
125 //! Searching an optional value is equivalent to searching a list
126 //! containing `x` for `just(x)` and an empty list for `nothing`.
128 //! @include example/optional/searchable.cpp
129 #ifdef BOOST_HANA_DOXYGEN_INVOKED
130 template <typename ...T>
132 // 5.3.1, Constructors
134 //! Default-construct an `optional`. Only exists if the optional
135 //! contains a value, and if that value is DefaultConstructible.
136 constexpr optional() = default;
138 //! Copy-construct an `optional`.
139 //! An empty optional may only be copy-constructed from another
140 //! empty `optional`, and an `optional` with a value may only be
141 //! copy-constructed from another `optional` with a value.
142 //! Furthermore, this constructor only exists if the value
143 //! held in the `optional` is CopyConstructible.
144 optional(optional const&) = default;
146 //! Move-construct an `optional`.
147 //! An empty optional may only be move-constructed from another
148 //! empty `optional`, and an `optional` with a value may only be
149 //! move-constructed from another `optional` with a value.
150 //! Furthermore, this constructor only exists if the value
151 //! held in the `optional` is MoveConstructible.
152 optional(optional&&) = default;
154 //! Construct an `optional` holding a value of type `T` from another
155 //! object of type `T`. The value is copy-constructed.
156 constexpr optional(T const& t)
160 //! Construct an `optional` holding a value of type `T` from another
161 //! object of type `T`. The value is move-constructed.
162 constexpr optional(T&& t)
163 : value_(static_cast<T&&>(t))
168 //! Copy-assign an `optional`.
169 //! An empty optional may only be copy-assigned from another empty
170 //! `optional`, and an `optional` with a value may only be copy-assigned
171 //! from another `optional` with a value. Furthermore, this assignment
172 //! operator only exists if the value held in the `optional` is
174 constexpr optional& operator=(optional const&) = default;
176 //! Move-assign an `optional`.
177 //! An empty optional may only be move-assigned from another empty
178 //! `optional`, and an `optional` with a value may only be move-assigned
179 //! from another `optional` with a value. Furthermore, this assignment
180 //! operator only exists if the value held in the `optional` is
182 constexpr optional& operator=(optional&&) = default;
186 //! Returns a pointer to the contained value, or a `nullptr` if the
187 //! `optional` is empty.
190 //! @note Overloads of this method are provided for both the `const`
191 //! and the non-`const` cases.
196 //! @include example/optional/value.cpp
197 constexpr T* operator->();
199 //! Extract the content of an `optional`, or fail at compile-time.
201 //! If `*this` contains a value, that value is returned. Otherwise,
202 //! a static assertion is triggered.
205 //! Overloads of this method are provided for the cases where `*this`
206 //! is a reference, a rvalue-reference and their `const` counterparts.
211 //! @include example/optional/value.cpp
212 constexpr T& value();
214 //! Equivalent to `value()`, provided for convenience.
217 //! Overloads of this method are provided for the cases where `*this`
218 //! is a reference, a rvalue-reference and their `const` counterparts.
223 //! @include example/optional/value.cpp
224 constexpr T& operator*();
226 //! Return the contents of an `optional`, with a fallback result.
228 //! If `*this` contains a value, that value is returned. Otherwise,
229 //! the default value provided is returned.
232 //! Overloads of this method are provided for the cases where `*this`
233 //! is a reference, a rvalue-reference and their `const` counterparts.
237 //! The default value to return if `*this` does not contain a value.
242 //! @include example/optional/value_or.cpp
243 template <typename U>
244 constexpr decltype(auto) value_or(U&& default_);
246 //! Equivalent to `hana::chain`.
247 template <typename ...T, typename F>
248 friend constexpr auto operator|(optional<T...>, F);
250 //! Equivalent to `hana::equal`
251 template <typename X, typename Y>
252 friend constexpr auto operator==(X&& x, Y&& y);
254 //! Equivalent to `hana::not_equal`
255 template <typename X, typename Y>
256 friend constexpr auto operator!=(X&& x, Y&& y);
258 //! Equivalent to `hana::less`
259 template <typename X, typename Y>
260 friend constexpr auto operator<(X&& x, Y&& y);
262 //! Equivalent to `hana::greater`
263 template <typename X, typename Y>
264 friend constexpr auto operator>(X&& x, Y&& y);
266 //! Equivalent to `hana::less_equal`
267 template <typename X, typename Y>
268 friend constexpr auto operator<=(X&& x, Y&& y);
270 //! Equivalent to `hana::greater_equal`
271 template <typename X, typename Y>
272 friend constexpr auto operator>=(X&& x, Y&& y);
275 template <typename ...T>
279 //! Tag representing a `hana::optional`.
280 //! @relates hana::optional
281 struct optional_tag { };
283 //! Create an optional value.
284 //! @relates hana::optional
286 //! Specifically, `make<optional_tag>()` is equivalent to `nothing`, and
287 //! `make<optional_tag>(x)` is equivalent to `just(x)`. This is provided
288 //! for consistency with the other `make<...>` functions.
293 //! @include example/optional/make.cpp
294 #ifdef BOOST_HANA_DOXYGEN_INVOKED
296 constexpr auto make<optional_tag> = []([auto&& x]) {
297 return optional<std::decay<decltype(x)>::type>{forwarded(x)};
301 //! Alias to `make<optional_tag>`; provided for convenience.
302 //! @relates hana::optional
307 //! @include example/optional/make.cpp
308 constexpr auto make_optional = make<optional_tag>;
310 //! Create an optional value containing `x`.
311 //! @relates hana::optional
316 //! @include example/optional/just.cpp
317 #ifdef BOOST_HANA_DOXYGEN_INVOKED
318 constexpr auto just = [](auto&& x) {
319 return optional<std::decay<decltype(x)>::type>{forwarded(x)};
323 template <typename T>
324 constexpr auto operator()(T&&) const;
327 constexpr make_just_t just{};
330 //! An empty optional value.
331 //! @relates hana::optional
336 //! @include example/optional/nothing.cpp
337 #ifdef BOOST_HANA_DOXYGEN_INVOKED
338 constexpr optional<> nothing{};
341 struct optional<> : detail::operators::adl<optional<>> {
342 // 5.3.1, Constructors
343 constexpr optional() = default;
344 constexpr optional(optional const&) = default;
345 constexpr optional(optional&&) = default;
348 constexpr optional& operator=(optional const&) = default;
349 constexpr optional& operator=(optional&&) = default;
352 constexpr decltype(nullptr) operator->() const { return nullptr; }
354 template <typename ...dummy>
355 constexpr auto value() const;
357 template <typename ...dummy>
358 constexpr auto operator*() const;
360 template <typename U>
361 constexpr U&& value_or(U&& u) const;
364 constexpr optional<> nothing{};
367 //! Apply a function to the contents of an optional, with a fallback
369 //! @relates hana::optional
371 //! Specifically, `maybe` takes a default value, a function and an
372 //! optional value. If the optional value is `nothing`, the default
373 //! value is returned. Otherwise, the function is applied to the
374 //! content of the `just`.
378 //! A default value returned if `m` is `nothing`.
381 //! A function called as `f(x)` if and only if `m` is an optional value
382 //! of the form `just(x)`. In that case, the result returend by `maybe`
383 //! is the result of `f`.
386 //! An optional value.
391 //! @include example/optional/maybe.cpp
392 #ifdef BOOST_HANA_DOXYGEN_INVOKED
393 constexpr auto maybe = [](auto&& default_, auto&& f, auto&& m) -> decltype(auto) {
394 if (m is a just(x)) {
395 return forwarded(f)(forwarded(x));
397 return forwarded(default_);
402 template <typename Def, typename F, typename T>
403 constexpr decltype(auto) operator()(Def&&, F&& f, optional<T> const& m) const
404 { return static_cast<F&&>(f)(m.value_); }
406 template <typename Def, typename F, typename T>
407 constexpr decltype(auto) operator()(Def&&, F&& f, optional<T>& m) const
408 { return static_cast<F&&>(f)(m.value_); }
410 template <typename Def, typename F, typename T>
411 constexpr decltype(auto) operator()(Def&&, F&& f, optional<T>&& m) const
412 { return static_cast<F&&>(f)(static_cast<optional<T>&&>(m).value_); }
414 template <typename Def, typename F>
415 constexpr Def operator()(Def&& def, F&&, optional<> const&) const
416 { return static_cast<Def&&>(def); }
419 constexpr maybe_t maybe{};
422 //! Calls a function if the call expression is well-formed.
423 //! @relates hana::optional
425 //! Given a function `f`, `sfinae` returns a new function applying `f`
426 //! to its arguments and returning `just` the result if the call is
427 //! well-formed, and `nothing` otherwise. In other words, `sfinae(f)(x...)`
428 //! is `just(f(x...))` if that expression is well-formed, and `nothing`
429 //! otherwise. Note, however, that it is possible for an expression
430 //! `f(x...)` to be well-formed as far as SFINAE is concerned, but
431 //! trying to actually compile `f(x...)` still fails. In this case,
432 //! `sfinae` won't be able to detect it and a hard failure is likely
437 //! The function given to `sfinae` must not return `void`, since
438 //! `just(void)` does not make sense. A compilation error is
439 //! triggered if the function returns void.
444 //! @include example/optional/sfinae.cpp
445 #ifdef BOOST_HANA_DOXYGEN_INVOKED
446 auto sfinae = [](auto&& f) {
447 return [perfect-capture](auto&& ...x) {
448 if (decltype(forwarded(f)(forwarded(x)...)) is well-formed)
449 return just(forwarded(f)(forwarded(x)...));
456 template <typename F>
457 constexpr decltype(auto) operator()(F&& f) const;
460 constexpr sfinae_t sfinae{};
463 //! Return whether an `optional` contains a value.
464 //! @relates hana::optional
466 //! Specifically, returns a compile-time true-valued `Logical` if `m` is
467 //! of the form `just(x)` for some `x`, and a false-valued one otherwise.
472 //! @include example/optional/is_just.cpp
473 #ifdef BOOST_HANA_DOXYGEN_INVOKED
474 constexpr auto is_just = [](auto const& m) {
475 return m is a just(x);
479 template <typename ...T>
480 constexpr auto operator()(optional<T...> const&) const;
483 constexpr is_just_t is_just{};
486 //! Return whether an `optional` is empty.
487 //! @relates hana::optional
489 //! Specifically, returns a compile-time true-valued `Logical` if `m` is
490 //! a `nothing`, and a false-valued one otherwise.
495 //! @include example/optional/is_nothing.cpp
496 #ifdef BOOST_HANA_DOXYGEN_INVOKED
497 constexpr auto is_nothing = [](auto const& m) {
498 return m is a nothing;
501 struct is_nothing_t {
502 template <typename ...T>
503 constexpr auto operator()(optional<T...> const&) const;
506 constexpr is_nothing_t is_nothing{};
508 BOOST_HANA_NAMESPACE_END
510 #endif // !BOOST_HANA_FWD_OPTIONAL_HPP