Core utilities of the library.
|struct||boost::hana::common< T, U, enabler >|
|Metafunction returning the common data type between two data types. More...|
|struct||boost::hana::has_common< T, U, typename >|
|Metafunction returning whether two data types share a common data type. More...|
|Mark a tag-dispatched method implementation as a default implementation. More...|
|struct||boost::hana::is_default< Method, typename >|
|Returns whether a tag-dispatched method implementation is a default implementation. More...|
|struct||boost::hana::tag_of< T, enabler >|
|Metafunction returning the tag associated to |
|struct||boost::hana::is_convertible< From, To, typename >|
|Returns whether there is a Hana-conversion from a data type to another. More...|
|struct||boost::hana::embedding< bool >|
|Marks a conversion between data types as being an embedding. More...|
|struct||boost::hana::is_embedded< From, To, typename >|
|Returns whether a data type can be embedded into another data type. More...|
|struct||boost::hana::when< condition >|
|Enable a partial specialization only if a boolean condition is true. More...|
|template<typename T , typename U >|
|using||boost::hana::common_t = typename common< T, U >::type|
|Alias to |
|template<typename T >|
|using||boost::hana::tag_of_t = typename hana::tag_of< T >::type|
|Alias to |
|using||boost::hana::when_valid = when< true >|
|Variant of |
|template<typename Tag , typename optional_T >|
|constexpr auto||boost::hana::is_a = see-documentation|
|Returns whether the tag of an object matches a given tag. More...|
|template<typename Tag , typename... T>|
|constexpr auto||boost::hana::is_an = is_a<Tag, T...>|
|Equivalent to |
|template<typename Tag >|
|Create an object of the given tag with the given arguments. More...|
|template<typename To >|
|Converts an object from one data type to another. More...|
|using boost::hana::common_t = typedef typename common<T, U>::type|
common<T, U>::type, provided for convenience.
|using boost::hana::tag_of_t = typedef typename hana::tag_of<T>::type|
tag_of<T>::type, provided for convenience.
|using boost::hana::when_valid = typedef when<true>|
when allowing specializations to be enabled only if an expression is well-formed.
when_valid<...> is always equivalent to
when<true>. However, when used inside a partial specialization, SFINAE will cause the partial specialization to be ignored when the expression is ill-formed.
when_validseems to trigger ambiguous partial specializations on GCC.
|constexpr auto boost::hana::is_a = see-documentation|
Returns whether the tag of an object matches a given tag.
Given a tag
Tag and a C++ type
is_a<Tag, T> is a compile-time Logical representing whether the tag of
T is exactly
Tag. In other words, it is equivalent to
For convenience, an alternate syntax is provided for using
is_a<Tag> is a function object returning whether the argument it is passed has the given tag. In other words,
|constexpr auto boost::hana::make|
Create an object of the given tag with the given arguments.
This function serves the same purpose as constructors in usual C++. However, instead of creating an object of a specific C++ type, it creates an object of a specific tag, regardless of the C++ type of that object.
This function is actually a variable template, so
make<T> can be passed around as a function object creating an object of tag
T. Also, it uses tag-dispatching so this is how it should be customized for user-defined tags.
Finally, the default implementation of
make is equivalent to calling the constructor of the given tag with the corresponding arguments. In other words, by default,
Note that the arguments are perfectly forwarded and the form of construction which is used is exactly as documented, i.e.
T(args...). However, if
T(args...) is not a valid expression, a compilation error is triggered. This default behavior is useful because it makes foreign C++ types that have no notion of tag constructible with
make out-of-the-box, since their tag is exactly themselves.
|constexpr auto boost::hana::to|
Converts an object from one data type to another.
to is a natural extension of the
static_cast language construct to data types. Given a destination data type
To and an object
to creates a new object of data type
x. Note, however, that
to is not required to actually create a new object, and may return a reference to the original object (for example when trying to convert an object to its own data type).
As a natural extension to
to provides a default behavior. For the purpose of what follows, let
To be the destination data type and
From be the data type of
x, i.e. the source data type. Then,
to has the following default behavior:
Fromdata types are the same, then the object is forwarded as-is.
Fromis convertible to
xis converted to
to<From>(x)triggers a static assertion.
to is a tag-dispatched function, which means that
to_impl may be specialized in the
boost::hana namespace to customize its behavior for arbitrary data types. Also note that
to is tag-dispatched using both the
To and the
From data types, which means that
to_impl is called as
to_impl<To, From>::apply(x). Also note that some concepts provide conversions to or from their models. For example, any
Foldable may be converted into a
Sequence. This is achieved by specializing
to_impl<To, From> whenever
To is a
From is a
Foldable. When such conversions are provided, they are documented in the source concept, in this case
When an object
x of data type
From can be converted to a data type
to, we say that
x is Hana-convertible to the data type
To. We also say that there is a Hana-conversion from
To. This bit of terminology is useful to avoid mistaking the various kinds of conversions C++ offers.
As you might have seen by now, Hana uses algebraic and category- theoretical structures all around the place to help specify concepts in a rigorous way. These structures always have operations associated to them, which is why they are useful. The notion of embedding captures the idea of injecting a smaller structure into a larger one while preserving the operations of the structure. In other words, an embedding is an injective mapping that is also structure-preserving. Exactly what it means for a structure's operations to be preserved is left to explain by the documentation of each structure. For example, when we talk of a Monoid-embedding from a Monoid
A to a Monoid
B, we simply mean an injective transformation that preserves the identity and the associative operation, as documented in
But what does this have to do with the
to function? Quite simply, the
to function is a mapping between two data types, which will sometimes be some kind of structure, and it is sometimes useful to know whether such a mapping is well-behaved, i.e. lossless and structure preserving. The criterion for this conversion to be well- behaved is exactly that of being an embedding. To specify that a conversion is an embedding, simply use the
embedding type as a base class of the corresponding
to_impl specialization. Obviously, you should make sure the conversion is really an embedding, unless you want to shoot yourself in the foot.
|To||The data type to which |
|x||The object to convert to the given data type.|