Optional value whose optional-ness is known at compile-time.
An optional
either contains a value (represented as just(x)
), or it is empty (represented as nothing
). In essence, hana::optional
is pretty much like a boost::optional
or the upcoming std::optional
, except for the fact that whether a hana::optional
is empty or not is known at compile-time. This can be particularly useful for returning from a function that might fail, but whose reason for failing is not important. Of course, whether the function will fail has to be known at compile-time.
This is really an important difference between hana::optional
and std::optional
. Unlike std::optional<T>{}
and std::optional<T>{x}
who share the same type (std::optional<T>
), hana::just(x)
and hana::nothing
do not share the same type, since the state of the optional has to be known at compile-time. Hence, whether a hana::just
or a hana::nothing
will be returned from a function has to be known at compile-time for the return type of that function to be computable by the compiler. This makes hana::optional
well suited for static metaprogramming tasks, but very poor for anything dynamic.
type
s When a just
contains an object of type T
which is a type
, it has a nested ::type
alias equivalent to T::type
. nothing
, however, never has a nested ::type
alias. If t
is a type
, this allows decltype(just(t))
to be seen as a nullary metafunction equivalent to decltype(t)
. Along with the sfinae
function, this allows hana::optional
to interact seamlessly with SFINAE-friendly metafunctions. Example:
Comparable
optional
s are equal if and only if they are both empty or they both contain a value and those values are equal. Orderable
nothing
as being less than any other just
. Hence, Example: Functor
just(x)
) or no elements at all (nothing
). As such, mapping a function over an optional value is equivalent to applying it to its value if there is one, and to nothing
otherwise: Example: Applicative
lift<optional_tag>
, which is equivalent to just
. Second, one can feed an optional value to an optional function with ap
, which will return just(f(x))
if there is both a function and a value, and nothing
otherwise: Monad
Monad
model makes it easy to compose actions that might fail. One can feed an optional value if there is one into a function with chain
, which will return nothing
if there is no value. Finally, optional-optional values can have their redundant level of optionality removed with flatten
. Also note that the |
operator can be used in place of the chain
function. Example: MonadPlus
MonadPlus
model allows choosing the first valid value out of two optional values with concat
. If both optional values are nothing
s, concat
will return nothing
. Example: Foldable
nothing
) or x
(for just(x)
). Example: Searchable
x
for just(x)
and an empty list for nothing
. Example: Synopsis of associated functions | |
template<> | |
constexpr auto | make< optional_tag > |
Create an optional value. More... | |
constexpr auto | make_optional = make<optional_tag> |
Alias to make<optional_tag> ; provided for convenience. More... | |
constexpr auto | just |
Create an optional value containing x . More... | |
constexpr optional | nothing {} |
An empty optional value. More... | |
constexpr auto | maybe |
Apply a function to the contents of an optional, with a fallback result. More... | |
auto | sfinae |
Calls a function if the call expression is well-formed. More... | |
constexpr auto | is_just |
Return whether an optional contains a value. More... | |
constexpr auto | is_nothing |
Return whether an optional is empty. More... | |
Friends | |
template<typename ... T, typename F > | |
constexpr auto | operator| (optional< T... >, F) |
Equivalent to hana::chain . | |
template<typename X , typename Y > | |
constexpr auto | operator== (X &&x, Y &&y) |
Equivalent to hana::equal | |
template<typename X , typename Y > | |
constexpr auto | operator!= (X &&x, Y &&y) |
Equivalent to hana::not_equal | |
template<typename X , typename Y > | |
constexpr auto | operator< (X &&x, Y &&y) |
Equivalent to hana::less | |
template<typename X , typename Y > | |
constexpr auto | operator> (X &&x, Y &&y) |
Equivalent to hana::greater | |
template<typename X , typename Y > | |
constexpr auto | operator<= (X &&x, Y &&y) |
Equivalent to hana::less_equal | |
template<typename X , typename Y > | |
constexpr auto | operator>= (X &&x, Y &&y) |
Equivalent to hana::greater_equal | |
Public Member Functions | |
constexpr | optional ()=default |
Default-construct an optional . Only exists if the optional contains a value, and if that value is DefaultConstructible. | |
optional (optional const &)=default | |
Copy-construct an optional . An empty optional may only be copy-constructed from another empty optional , and an optional with a value may only be copy-constructed from another optional with a value. Furthermore, this constructor only exists if the value held in the optional is CopyConstructible. | |
optional (optional &&)=default | |
Move-construct an optional . An empty optional may only be move-constructed from another empty optional , and an optional with a value may only be move-constructed from another optional with a value. Furthermore, this constructor only exists if the value held in the optional is MoveConstructible. | |
constexpr | optional (T const &t) |
Construct an optional holding a value of type T from another object of type T . The value is copy-constructed. | |
constexpr | optional (T &&t) |
Construct an optional holding a value of type T from another object of type T . The value is move-constructed. | |
constexpr optional & | operator= (optional const &)=default |
Copy-assign an optional . An empty optional may only be copy-assigned from another empty optional , and an optional with a value may only be copy-assigned from another optional with a value. Furthermore, this assignment operator only exists if the value held in the optional is CopyAssignable. | |
constexpr optional & | operator= (optional &&)=default |
Move-assign an optional . An empty optional may only be move-assigned from another empty optional , and an optional with a value may only be move-assigned from another optional with a value. Furthermore, this assignment operator only exists if the value held in the optional is MoveAssignable. | |
constexpr T * | operator-> () |
Returns a pointer to the contained value, or a nullptr if the optional is empty. More... | |
constexpr T & | value () |
Extract the content of an optional , or fail at compile-time. More... | |
constexpr T & | operator * () |
Equivalent to value() , provided for convenience. More... | |
template<typename U > | |
decltype(auto) constexpr | value_or (U &&default_) |
Return the contents of an optional , with a fallback result. More... | |
Create an optional value.
Specifically, make<optional_tag>()
is equivalent to nothing
, and make<optional_tag>(x)
is equivalent to just(x)
. This is provided for consistency with the other make<...>
functions.
|
related |
Alias to make<optional_tag>
; provided for convenience.
|
related |
Create an optional value containing x
.
|
related |
An empty optional value.
|
related |
Apply a function to the contents of an optional, with a fallback result.
Specifically, maybe
takes a default value, a function and an optional value. If the optional value is nothing
, the default value is returned. Otherwise, the function is applied to the content of the just
.
default_ | A default value returned if m is nothing . |
f | A function called as f(x) if and only if m is an optional value of the form just(x) . In that case, the result returend by maybe is the result of f . |
m | An optional value. |
|
related |
Calls a function if the call expression is well-formed.
Given a function f
, sfinae
returns a new function applying f
to its arguments and returning just
the result if the call is well-formed, and nothing
otherwise. In other words, sfinae(f)(x...)
is just(f(x...))
if that expression is well-formed, and nothing
otherwise. Note, however, that it is possible for an expression f(x...)
to be well-formed as far as SFINAE is concerned, but trying to actually compile f(x...)
still fails. In this case, sfinae
won't be able to detect it and a hard failure is likely to happen.
sfinae
must not return void
, since just(void)
does not make sense. A compilation error is triggered if the function returns void.
|
related |
Return whether an optional
contains a value.
Specifically, returns a compile-time true-valued Logical
if m
is of the form just(x)
for some x
, and a false-valued one otherwise.
|
related |
Return whether an optional
is empty.
Specifically, returns a compile-time true-valued Logical
if m
is a nothing
, and a false-valued one otherwise.
constexpr T* boost::hana::optional< T >::operator-> | ( | ) |
Returns a pointer to the contained value, or a nullptr
if the optional
is empty.
const
and the non-const
cases.constexpr T& boost::hana::optional< T >::value | ( | ) |
Extract the content of an optional
, or fail at compile-time.
If *this
contains a value, that value is returned. Otherwise, a static assertion is triggered.
*this
is a reference, a rvalue-reference and their const
counterparts.constexpr T& boost::hana::optional< T >::operator * | ( | ) |
Equivalent to value()
, provided for convenience.
*this
is a reference, a rvalue-reference and their const
counterparts.decltype(auto) constexpr boost::hana::optional< T >::value_or | ( | U && | default_ | ) |
Return the contents of an optional
, with a fallback result.
If *this
contains a value, that value is returned. Otherwise, the default value provided is returned.
*this
is a reference, a rvalue-reference and their const
counterparts.default_ | The default value to return if *this does not contain a value. |