 |
Boost.Hana
1.5.0
Your standard library for metaprogramming
|
|
|
Boost.Hana
1.5.0
Your standard library for metaprogramming
|
|
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.
types 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:
Comparableoptionals are equal if and only if they are both empty or they both contain a value and those values are equal. Orderablenothing as being less than any other just. Hence, Example: Functorjust(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: Applicativelift<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: MonadMonad 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: MonadPlusMonadPlus model allows choosing the first valid value out of two optional values with concat. If both optional values are nothings, concat will return nothing. Example: Foldablenothing) or x (for just(x)). Example: Searchablex 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. |