 |
Boost.Hana
1.6.0
Your standard library for metaprogramming
|
|
|
Boost.Hana
1.6.0
Your standard library for metaprogramming
|
|
Hana is a header-only library for C++ metaprogramming suited for computations on both types and values. The functionality it provides is a superset of what is provided by the well established Boost.MPL and Boost.Fusion libraries. By leveraging C++11/14 implementation techniques and idioms, Hana boasts faster compilation times and runtime performance on par or better than previous metaprogramming libraries, while noticeably increasing the level of expressiveness in the process. Hana is easy to extend in a ad-hoc manner and it provides out-of-the-box inter-operation with Boost.Fusion, Boost.MPL and the standard library.
Hana is a header-only library without external dependencies (not even the rest of Boost). Hence, using Hana in your own project is very easy. Basically, just download the project and add the include/ directory to your compiler's header search path and you are done. However, if you want to cleanly install Hana, you have a couple of options:
/usr/local for Unix, C:/Program Files for Windows). If you want to install Hana in a custom location, you can use If you just want to contribute to Hana, you can see how to best setup your environment for development in the README.
HanaConfig.cmake file for use with CMake and a hana.pc file for use with pkg-config.If you use CMake, depending on Hana has never been so easy. When installed, Hana creates a HanaConfig.cmake file that exports the hana interface library target with all the required settings. All you need is to install Hana (through Homebrew or manually), use find_package(Hana), and then link your own targets against the hana target. Here is a minimal example of doing this:
If you have installed Hana in a non-standard place, you might need to play with CMAKE_PREFIX_PATH. For example, this can happen if you "manually" install Hana locally to another project. In this case, you'll need to tell CMake where to find the HanaConfig.cmake file by using
where INSTALLATION_PREFIX_FOR_HANA is the path to the place where Hana was installed.
The library relies on a C++14 compiler and standard library, but nothing else is required. However, we only guarantee support for the compilers listed below, which are tested on an ongoing basis:
| Compiler/Toolchain | Status |
|---|---|
| Clang >= 3.9.1 | Fully working; tested on each push to GitHub |
| Xcode >= 9.1 | Fully working; tested on each push to GitHub |
| GCC >= 6.0.0 | Fully working; tested on each push to GitHub |
| VS2017 >= Update 7 | Fully working; tested on each push to GitHub |
More specifically, Hana requires a compiler/standard library supporting the following C++14 features (non-exhaustively):
constexpr<type_traits> headerUsing a compiler not listed above may work, but support for such compilers is not guaranteed. More information for specific platforms is available on the wiki.
If you have a problem, please review the FAQ and the wiki. Searching the issues for your problem is also a good idea. If that doesn't help, feel free to chat with us in Gitter, or open a new issue. StackOverflow with the boost-hana tag is the preferred place to ask questions on usage. If you are encountering what you think is a bug, please open an issue.
When Boost.MPL first appeared, it provided C++ programmers with a huge relief by abstracting tons of template hackery behind a workable interface. This breakthrough greatly contributed to making C++ template metaprogramming more mainstream, and today the discipline is deeply rooted in many serious projects. Recently, C++11 and C++14 brought many major changes to the language, some of which make metaprogramming much easier, while others drastically widen the design space for libraries. A natural question then arises: is it still desirable to have abstractions for metaprogramming, and if so, which ones? After investigating different options like the MPL11, the answer eventually came by itself in the form of a library; Hana. The key insight to Hana is that the manipulation of types and values are nothing but two sides of the same coin. By unifying both concepts, metaprogramming becomes easier and new exciting possibilities open before us.
But to really understand what is Hana all about, it is essential to understand the different types of computations in C++. We will focus our attention on four different kinds of computations, even though a finer grained separation would be possible. First, we have runtime computations, which are the usual computations we use in C++. In that world, we have runtime containers, runtime functions and runtime algorithms:
The usual toolbox for programming within this quadrant is the C++ standard library, which provides reusable algorithms and containers operating at runtime. Since C++11, a second kind of computation is possible: constexpr computations. There, we have constexpr containers, constexpr functions and constexpr algorithms:
std::array's operator== would have to be marked constexpr, which is not the case (even in C++14).Basically, a constexpr computation is different from a runtime computation in that it is simple enough to be evaluated (interpreted, really) by the compiler. In general, any function that does not perform anything too unfriendly to the compiler's evaluator (like throwing or allocating memory) can be marked constexpr without any further change. This makes constexpr computations very similar to runtime computations, except constexpr computations are more restricted and they gain the ability to be evaluated at compile-time. Unfortunately, there is no commonly used toolbox for constexpr-programming, i.e. there is no widely adopted "standard library" for constexpr programming. However, the Sprout library may be worth checking out for those with some interest in constexpr computations.
The third kind of computations are heterogeneous computations. Heterogeneous computations differ from normal computations in that instead of having containers holding homogeneous objects (all objects having the same type), the containers may hold objects with different types. Furthermore, functions in this quadrant of computation are heterogeneous functions, which is a complicated way of talking about template functions. Similarly, we have heterogeneous algorithms that manipulate heterogeneous containers and functions:
If manipulating heterogeneous containers seems overly weird to you, just think of it as glorified std::tuple manipulation. In a C++03 world, the go-to library for doing this kind of computation is Boost.Fusion, which provides several data structures and algorithms to manipulate heterogeneous collections of data. The fourth and last quadrant of computation that we'll be considering here is the quadrant of type-level computations. In this quadrant, we have type-level containers, type-level functions (usually called metafunctions) and type-level algorithms. Here, everything operates on types: containers hold types and metafunctions take types as arguments and return types as results.
The realm of type-level computations has been explored quite extensively, and the de-facto solution for type-level computations in C++03 is a library named Boost.MPL, which provides type-level containers and algorithms. For low-level type transformations, the metafunctions provided by the <type_traits> standard header can also be used since C++11.
So all is good, but what is this library actually about? Now that we have set the table by clarifying the kinds of computations available to us in C++, the answer might strike you as very simple. The purpose of Hana is to merge the 3rd and the 4th quadrants of computation. More specifically, Hana is a (long-winded) constructive proof that heterogeneous computations are strictly more powerful than type-level computations, and that we can therefore express any type-level computation by an equivalent heterogeneous computation. This construction is done in two steps. First, Hana is a fully featured library of heterogeneous algorithms and containers, a bit like a modernized Boost.Fusion. Secondly, Hana provides a way of translating any type-level computation into its equivalent heterogeneous computation and back, which allows the full machinery of heterogeneous computations to be reused for type-level computations without any code duplication. Of course, the biggest advantage of this unification is seen by the user, as you will witness by yourself.
The goal of this section is to introduce the main concepts of the library from a very high level and at a fairly rapid pace; don't worry if you don't understand everything that's about to be thrown at you. However, this tutorial assumes the reader is already at least familiar with basic metaprogramming and the C++14 standard. First, let's include the library:
Unless specified otherwise, the documentation assumes the above lines to be present before examples and code snippets. Also note that finer grained headers are provided and will be explained in the Header organization section. For the purpose of the quickstart, let's now include some additional headers and define some lovely animal types that we'll need below:
If you are reading this documentation, chances are you already know std::tuple and std::make_tuple. Hana provides its own tuple and make_tuple:
This creates a tuple, which is like an array, except that it can hold elements with different types. Containers that can hold elements with different types such as this are called heterogeneous containers. While the standard library provides very few operations to manipulate std::tuples, Hana provides several operations and algorithms to manipulate its own tuples:
1_c is a C++14 user-defined literal creating a compile-time number. These user-defined literals are contained in the boost::hana::literals namespace, hence the using directive.Notice how we pass a C++14 generic lambda to transform; this is required because the lambda will first be called with a Fish, then a Cat, and finally a Dog, which all have different types. Hana provides most of the algorithms provided by the C++ standard library, except they work on tuples and related heterogeneous containers instead of std::vector & friends. In addition to working with heterogeneous values, Hana makes it possible to perform type-level computations with a natural syntax, all at compile-time and with no overhead whatsoever. This compiles and does just what you would expect:
type_c<...> is not a type! It is a C++14 variable template yielding an object representing a type for Hana. This is explained in the section on type computations.In addition to heterogeneous and compile-time sequences, Hana provides several features to make your metaprogramming nightmares a thing of the past. For example, one can check for the existence of a struct member with one easy line instead of relying on clunky SFINAE hacks:
Writing a serialization library? Stop crying, we've got you covered. Reflection can be added to user-defined types very easily. This allows iterating over the members of a user-defined type, querying members with a programmatic interface and much more, without any runtime overhead:
That's cool, but I can already hear you complaining about incomprehensible error messages. However, it turns out Hana was built for humans, not professional template metaprogrammers, and this shows. Let's intentionally screw up and see what kind of mess is thrown at us. First, the mistake:
Now, the punishment:
Not that bad, right? However, since small examples are very good to show off without actually doing something useful, let's examine a real world example.
In this section our goal will be to implement a kind of switch statement able to process boost::anys. Given a boost::any, the goal is to dispatch to the function associated to the dynamic type of the any:
s suffix on string literals to create std::strings without syntactic overhead. This is a standard-defined C++14 user-defined literal.Since the any holds a char, the second function is called with the char inside it. If the any had held an int instead, the first function would have been called with the int inside it. When the dynamic type of the any does not match any of the covered cases, the default_ function is called instead. Finally, the result of the switch is the result of calling the function associated to the any's dynamic type. The type of that result is inferred to be the common type of the result of all the provided functions:
We'll now look at how this utility can be implemented using Hana. The first step is to associate each type to a function. To do so, we represent each case_ as a hana::pair whose first element is a type and whose second element is a function. Furthermore, we (arbitrarily) decide to represent the default_ case as a hana::pair mapping a dummy type to a function:
To provide the interface we showed above, switch_ will have to return a function taking the cases. In other words, switch_(a) must be a function taking any number of cases (which are hana::pairs), and performing the logic to dispatch a to the right function. This can easily be achieved by having switch_ return a C++14 generic lambda:
However, since parameter packs are not very flexible, we'll put the cases into a tuple so we can manipulate them:
Notice how the auto keyword is used when defining cases; it is often easier to let the compiler deduce the type of the tuple and use make_tuple instead of working out the types manually. The next step is to separate the default case from the rest of the cases. This is where things start to get interesting. To do so, we use Hana's find_if algorithm, which works a bit like std::find_if:
find_if takes a tuple and a predicate, and returns the first element of the tuple which satisfies the predicate. The result is returned as a hana::optional, which is very similar to a std::optional, except whether that optional value is empty or not is known at compile-time. If the predicate is not satisfied for any element of the tuple, find_if returns nothing (an empty value). Otherwise, it returns just(x) (a non-empty value), where x is the first element satisfying the predicate. Unlike predicates used in STL algorithms, the predicate used here must be generic because the tuple's elements are heterogeneous. Furthermore, that predicate must return what Hana calls an IntegralConstant, which means that the predicate's result must be known at compile-time. These details are explained in the section on cross-phase algorithms. Inside the predicate, we simply compare the type of the case's first element to type_c<default_t>. If you recall that we were using hana::pairs to encode cases, this simply means that we're finding the default case among all of the provided cases. But what if no default case was provided? We should fail at compile-time, of course!
Notice how we can use static_assert on the result of the comparison with nothing, even though default_ is a non-constexpr object? Boldly, Hana makes sure that no information that's known at compile-time is lost to the runtime, which is clearly the case of the presence of a default_ case. The next step is to gather the set of non-default cases. To achieve this, we use the filter algorithm, which keeps only the elements of the sequence satisfying the predicate:
The next step is to find the first case matching the dynamic type of the any, and then call the function associated to that case. The simplest way to do this is to use classic recursion with variadic parameter packs. Of course, we could probably intertwine Hana algorithms in a convoluted way to achieve this, but sometimes the best way to do something is to write it from scratch using basic techniques. To do so, we'll call an implementation function with the contents of the rest tuple by using the unpack function:
unpack takes a tuple and a function, and calls the function with the content of the tuple as arguments. The result of unpack is the result of calling that function. In our case, the function is a generic lambda which in turn calls the process function. Our reason for using unpack here was to turn the rest tuple into a parameter pack of arguments, which are easier to process recursively than tuples. Before we move on to the process function, it is worthwhile to explain what second(*default_) is all about. As we explained earlier, default_ is an optional value. Like std::optional, this optional value overloads the dereference operator (and the arrow operator) to allow accessing the value inside the optional. If the optional is empty (nothing), a compile-time error is triggered. Since we know default_ is not empty (we checked that just above), what we're doing is simply pass the function associated to the default case to the process function. We're now ready for the final step, which is the implementation of the process function:
There are two overloads of this function: an overload for when there is at least one case to process, and the base case overload for when there's only the default case. As we would expect, the base case simply calls the default function and returns that result. The other overload is slightly more interesting. First, we retrieve the type associated to that case and store it in T. This decltype(...)::type dance might seem convoluted, but it is actually quite simple. Roughly speaking, this takes a type represented as an object (a type<T>) and pulls it back down to the type level (a T). The details are explained in the section on type-level computations. Then, we compare whether the dynamic type of the any matches this case, and if so we call the function associated to this case with the any casted to the proper type. Otherwise, we simply call process recursively with the rest of the cases. Pretty simple, wasn't it? Here's the final solution:
That's it for the quick start! This example only introduced a couple of useful algorithms (find_if, filter, unpack) and heterogeneous containers (tuple, optional), but rest assured that there is much more. The next sections of the tutorial gradually introduce general concepts pertaining to Hana in a friendly way, but you may use the following cheatsheet for quick reference if you want to start coding right away. This cheatsheet contains the most frequently used algorithms and containers, along with a short description of what each of them does.
constexpr function objects| container | description |
|---|---|
tuple | General purpose index-based heterogeneous sequence with a fixed length. Use this as a std::vector for heterogeneous objects. |
optional | Represents an optional value, i.e. a value that can be empty. This is a bit like std::optional, except that the emptiness is known at compile-time. |
map | Unordered associative array mapping (unique) compile-time entities to arbitrary objects. This is like std::unordered_map for heterogeneous objects. |
set | Unordered container holding unique keys that must be compile-time entities. This is like std::unordered_set for heterogeneous objects. |
range | Represents an interval of compile-time numbers. This is like std::integer_sequence, but better. |
pair | Container holding two heterogeneous objects. Like std::pair, but compresses the storage of empty types. |
string | Compile-time string. |
type | Container representing a C++ type. This is the root of the unification between types and values, and is of interest for MPL-style computations (type-level computations). |
integral_constant | Represents a compile-time number. This is very similar to std::integral_constant, except that hana::integral_constant also defines operators and more syntactic sugar. |
lazy | Encapsulates a lazy value or computation. |
basic_tuple | Stripped-down version of hana::tuple. Not standards conforming, but more compile-time efficient. |
| function | description |
|---|---|
adjust(sequence, value, f) | Apply a function to each element of a sequence that compares equal to some value and return the result. |
adjust_if(sequence, predicate, f) | Apply a function to each element of a sequence satisfying some predicate and return the result. |
{all,any,none}(sequence) | Returns whether all/any/none of the elements of a sequence are true-valued. |
{all,any,none}_of(sequence, predicate) | Returns whether all/any/none of the elements of the sequence satisfy some predicate. |
append(sequence, value) | Append an element to a sequence. |
at(sequence, index) | Returns the n-th element of a sequence. The index must be an IntegralConstant. |
back(sequence) | Returns the last element of a non-empty sequence. |
concat(sequence1, sequence2) | Concatenate two sequences. |
contains(sequence, value) | Returns whether a sequence contains the given object. |
count(sequence, value) | Returns the number of elements that compare equal to the given value. |
count_if(sequence, predicate) | Returns the number of elements that satisfy the predicate. |
drop_front(sequence[, n]) | Drop the first n elements from a sequence, or the whole sequence if length(sequence) <= n. n must be an IntegralConstant. When not provided, n defaults to 1. |
drop_front_exactly(sequence[, n]) | Drop the first n elements from a sequence. n must be an IntegralConstant and the sequence must have at least n elements. When not provided, n defaults to 1. |
drop_back(sequence[, n]) | Drop the last n elements from a sequence, or the whole sequence if length(sequence) <= n. n must be an IntegralConstant. When not provided, n defaults to 1. |
drop_while(sequence, predicate) | Drops elements from a sequence while a predicate is satisfied. The predicate must return an IntegralConstant. |
fill(sequence, value) | Replace all the elements of a sequence with some value. |
filter(sequence, predicate) | Remove all the elements that do not satisfy a predicate. The predicate must return an IntegralConstant. |
find(sequence, value) | Find the first element of a sequence which compares equal to some value and return just it, or return nothing. See hana::optional. |
find_if(sequence, predicate) | Find the first element of a sequence satisfying the predicate and return just it, or return nothing. See hana::optional. |
flatten(sequence) | Flatten a sequence of sequences, a bit like std::tuple_cat. |
fold_left(sequence[, state], f) | Accumulates the elements of a sequence from the left, optionally with a provided initial state. |
fold_right(sequence[, state], f) | Accumulates the elements of a sequence from the right, optionally with a provided initial state. |
fold(sequence[, state], f) | Equivalent to fold_left; provided for consistency with Boost.MPL and Boost.Fusion. |
for_each(sequence, f) | Call a function on each element of a sequence. Returns void. |
front(sequence) | Returns the first element of a non-empty sequence. |
group(sequence[, predicate]) | Group adjacent elements of a sequence which all satisfy (or all do not satisfy) some predicate. The predicate defaults to equality, in which case the elements must be Comparable. |
index_if(sequence, predicate) | Find the index of the first element in a sequence satisfying the predicate and return just it, or return nothing. See hana::optional. |
insert(sequence, index, element) | Insert an element at a given index. The index must be an IntegralConstant. |
insert_range(sequence, index, elements) | Insert a sequence of elements at a given index. The index must be an IntegralConstant. |
is_empty(sequence) | Returns whether a sequence is empty as an IntegralConstant. |
length(sequence) | Returns the length of a sequence as an IntegralConstant. |
lexicographical_compare(sequence1, sequence2[, predicate]) | Performs a lexicographical comparison of two sequences, optionally with a custom predicate, by default with hana::less. |
maximum(sequence[, predicate]) | Returns the greatest element of a sequence, optionally according to a predicate. The elements must be Orderable if no predicate is provided. |
minimum(sequence[, predicate]) | Returns the smallest element of a sequence, optionally according to a predicate. The elements must be Orderable if no predicate is provided. |
partition(sequence, predicate) | Partition a sequence into a pair of elements that satisfy some predicate, and elements that do not satisfy it. |
prepend(sequence, value) | Prepend an element to a sequence. |
remove(sequence, value) | Remove all the elements that are equal to a given value. |
remove_at(sequence, index) | Remove the element at the given index. The index must be an IntegralConstant. |
remove_if(sequence, predicate) | Remove all the elements that satisfy a predicate. The predicate must return an IntegralConstant. |
remove_range(sequence, from, to) | Remove the elements at indices in the given [from, to) half-open interval. The indices must be IntegralConstants. |
replace(sequence, oldval, newval) | Replace the elements of a sequence that compare equal to some value by some other value. |
replace_if(sequence, predicate, newval) | Replace the elements of a sequence that satisfy some predicate by some value. |
reverse(sequence) | Reverse the order of the elements in a sequence. |
reverse_fold(sequence[, state], f) | Equivalent to fold_right; provided for consistency with Boost.MPL and Boost.Fusion. |
size(sequence) | Equivalent to length; provided for consistency with the C++ standard library. |
slice(sequence, indices) | Returns a new sequence containing the elements at the given indices of the original sequence. |
slice_c<from, to>(sequence) | Returns a new sequence containing the elements at indices contained in [from, to) of the original sequence. |
sort(sequence[, predicate]) | Sort (stably) the elements of a sequence, optionally according to a predicate. The elements must be Orderable if no predicate is provided. |
take_back(sequence, number) | Take the last n elements of a sequence, or the whole sequence if length(sequence) <= n. n must be an IntegralConstant. |
take_front(sequence, number) | Take the first n elements of a sequence, or the whole sequence if length(sequence) <= n. n must be an IntegralConstant. |
take_while(sequence, predicate) | Take elements of a sequence while some predicate is satisfied, and return that. |
transform(sequence, f) | Apply a function to each element of a sequence and return the result. |
unique(sequence[, predicate]) | Removes all consecutive duplicates from a sequence. The predicate defaults to equality, in which case the elements must be Comparable. |
unpack(sequence, f) | Calls a function with the contents of a sequence. Equivalent to f(x1, ..., xN). |
zip(s1, ..., sN) | Zip N sequences into a sequence of tuples. All the sequences must have the same length. |
zip_shortest(s1, ..., sN) | Zip N sequences into a sequence of tuples. The resulting sequence has the length of the shortest input sequence. |
zip_with(f, s1, ..., sN) | Zip N sequences with a N-ary function. All the sequences must have the same length. |
zip_shortest_with(f, s1, ..., sN) | Zip N sequences with a N-ary function. The resulting sequence has the length of the shortest input sequence. |
In the rest of this tutorial, you will come across code snippets where different kinds of assertions like BOOST_HANA_RUNTIME_CHECK and BOOST_HANA_CONSTANT_CHECK are used. Like any sensible assert macro, they basically check that the condition they are given is satisfied. However, in the context of heterogeneous programming, some informations are known at compile-time, while others are known only at runtime. The exact type of assertion that's used in a context tells you whether the condition that's asserted upon can be known at compile-time or if it must be computed at runtime, which is a very precious piece of information. Here are the different kinds of assertions used in the tutorial, with a small description of their particularities. For more details, you should check the reference on assertions.
| assertion | description |
|---|---|
BOOST_HANA_RUNTIME_CHECK | Assertion on a condition that is not known until runtime. This assertion provides the weakest form of guarantee. |
BOOST_HANA_CONSTEXPR_CHECK | Assertion on a condition that would be constexpr if lambdas were allowed inside constant expressions. In other words, the only reason for it not being a static_assert is the language limitation that lambdas can't appear in constant expressions, which might be lifted in C++17. |
static_assert | Assertion on a constexpr condition. This is stronger than BOOST_HANA_CONSTEXPR_CHECK in that it requires the condition to be a constant expression, and it hence assures that the algorithms used in the expression are constexpr-friendly. |
BOOST_HANA_CONSTANT_CHECK | Assertion on a boolean IntegralConstant. This assertion provides the strongest form of guarantee, because an IntegralConstant can be converted to a constexpr value even if it is not constexpr itself. |
This section introduces the important notion of IntegralConstant and the philosophy behind Hana's metaprogramming paradigm. Let's start with a rather odd question. What is an integral_constant?
std::integral_constant.One valid answer is that integral_constant represents a type-level encoding of a number, or more generally any object of an integral type. For illustration, we could define a successor function on numbers in that representation very easily by using a template alias:
This is the way integral_constants are usually thought of; as type-level entities that can be used for template metaprogramming. Another way to see an integral_constant is as a runtime object representing a constexpr value of an integral type:
Here, while one is not marked as constexpr, the abstract value it holds (a constexpr 1) is still available at compile-time, because that value is encoded in the type of one. Indeed, even if one is not constexpr, we can use decltype to retrieve the compile-time value it represents:
But why on earth would we want to consider integral_constants as objects instead of type-level entities? To see why, consider how we could now implement the same successor function as before:
Did you notice anything new? The difference is that instead of implementing succ at the type-level with a template alias, we're now implementing it at the value-level with a template function. Furthermore, we can now perform compile-time arithmetic using the same syntax as that of normal C++. This way of seeing compile-time entities as objects instead of types is the key to Hana's expressive power.
The MPL defines arithmetic operators that can be used to do compile-time computations with integral_constants. A typical example of such an operation is plus, which is implemented roughly as:
By viewing integral_constants as objects instead of types, the translation from a metafunction to a function is very straightforward:
It is very important to emphasize the fact that this operator does not return a normal integer. Instead, it returns a value-initialized object whose type contains the result of the addition. The only useful information contained in that object is actually in its type, and we're creating an object because it allows us to use this nice value-level syntax. It turns out that we can make this syntax even better by using a C++14 variable template to simplify the creation of an integral_constant:
Now we're talking about a visible gain in expressiveness over the initial type-level approach, aren't we? But there's more; we can also use C++14 user defined literals to make this process even simpler:
Hana provides its own integral_constants, which define arithmetic operators just like we showed above. Hana also provides variable templates to easily create different kinds of integral_constants: int_c, long_c, bool_c, etc... This allows you to omit the trailing {} braces otherwise required to value-initialize these objects. Of course, the _c suffix is also provided; it is part of the hana::literals namespace, and you must import it into your namespace before using it:
This way, you may do compile-time arithmetic without having to struggle with awkward type-level idiosyncrasies, and your coworkers will now be able to understand what's going on.
To illustrate how good it gets, let's implement a function computing a 2-D euclidean distance at compile-time. As a reminder, the euclidean distance of two points in the 2-D plane is given by
\[ \mathrm{distance}\left((x_1, y_1), (x_2, y_2)\right) := \sqrt{(x_1 - x_2)^2 + (y_1 - y_2)^2} \]
First, here's how it looks like with a type-level approach (using the MPL):
Yeah... Now, let's implement it with the value-level approach presented above:
This version looks arguably cleaner. However, this is not all. Notice how the distance function looks exactly as the one you would have written for computing the euclidean distance on dynamic values? Indeed, because we're using the same syntax for dynamic and compile-time arithmetic, generic functions written for one will work for both!
Without changing any code, we can use our distance function on runtime values and everything just works. Now that's DRY.
Once we have compile-time arithmetic, the next thing that might come to mind is compile-time branching. When metaprogramming, it is often useful to have one piece of code be compiled if some condition is true, and a different one otherwise. If you have heard of static_if, this should sound very familiar, and indeed it is exactly what we are talking about. Otherwise, if you don't know why we might want to branch at compile-time, consider the following code (adapted from N4461):
This code creates a std::unique_ptr using the correct form of syntax for the constructor. To achieve this, it uses SFINAE and requires two different overloads. Now, anyone sane seeing this for the first time would ask why it is not possible to simply write:
The reason is that the compiler is required to compile both branches of the if statement, regardless of the condition (even though it is known at compile-time). But when T is not constructible from Args..., the second branch will fail to compile, which will cause a hard compilation error. What we need really is a way to tell the compiler not to compile the second branch when the condition is true, and the first branch when the condition is false.
To emulate this, Hana provides an if_ function that works a bit like a normal if statement, except except it takes a condition that can be an IntegralConstant and returns the one of two values (which may have different types) chosen by the condition. If the condition is true, the first value is returned, and otherwise the second value is returned. A somewhat vain example is the following:
hana::true_c and hana::false_c are just boolean IntegralConstants representing a compile-time true value and a compile-time false value, respectively.Here, one_two_three is equal to 123, and hello is equal to "hello". In other words, if_ is a little bit like the ternary conditional operator ? :, except that both sides of the : can have different types:
Ok, so this is neat, but how can it actually help us write complete branches that are lazily instantiated by the compiler? The answer is to represent both branches of the if statement we'd like to write as generic lambdas, and to use hana::if_ to return the branch that we'd like to execute. Here's how we could rewrite make_unique:
Here, the first value given to hana::if_ is a generic lambda representing the branch we want to execute if the condition is true, and the second value is the branch we want to execute otherwise. hana::if_ simply returns the branch chosen by the condition, and we call that branch (which is a generic lambda) immediately with std::forward<Args>(args).... Hence, the proper generic lambda ends up being called, with x... being args..., and we return the result of that call.
The reason why this approach works is because the body of each branch can only be instantiated when the types of all x... are known. Indeed, since the branch is a generic lambda, the type of the argument is not known until the lambda is called, and the compiler must wait for the types of x... to be known before type-checking the lambda's body. Since the erroneous lambda is never called when the condition is not satisfied (hana::if_ takes care of that), the body of the lambda that would fail is never type-checked and no compilation error happens.
if_ are lambdas. As such, they really are different functions from the make_unique function. The variables appearing inside those branches have to be either captured by the lambdas or passed to them as arguments, and so they are affected by the way they are captured or passed (by value, by reference, etc..).Since this pattern of expressing branches as lambdas and then calling them is very common, Hana provides a eval_if function whose purpose is to make compile-time branching easier. eval_if comes from the fact that in a lambda, one can either receive input data as arguments or capture it from the context. However, for the purpose of emulating a language level if statement, implicitly capturing variables from the enclosing scope is usually more natural. Hence, what we would prefer writing is
Here, we're capturing the args... variables from the enclosing scope, which prevents us from having to introduce the new x... variables and passing them as arguments to the branches. However, this has two problems. First, this will not achieve the right result, since hana::if_ will end up returning a lambda instead of returning the result of calling that lambda. To fix this, we can use hana::eval_if instead of hana::if_:
Here, we capture the enclosing args... by reference using [&], and we do not need to receive any arguments. Also, hana::eval_if assumes that its arguments are branches that can be called, and it will take care of calling the branch that is selected by the condition. However, this will still cause a compilation failure, because the bodies of the lambdas are not dependent anymore, and semantic analysis will be done for both branches even though only one would end up being used. The solution to this problem is to make the bodies of the lambdas artificially dependent on something, to prevent the compiler from being able to perform semantic analysis before the lambda is actually used. To make this possible, hana::eval_if will call the selected branch with an identity function (a function that returns its argument unchanged), if the branch accepts such an argument:
Here, the bodies of the branches take an additional argument called _ by convention. This argument will be provided by hana::eval_if to the branch that was selected. Then, we use _ as a function on the variables that we want to make dependent within the body of each branch. What happens is that _ will always be a function that returns its argument unchanged. However, the compiler can't possibly know it before the lambda has actually been called, so it can't know the type of _(args). This prevents the compiler from being able to perform semantic analysis, and no compilation error happens. Plus, since _(x) is guaranteed to be equivalent to x, we know that we're not actually changing the semantics of the branches by using this trick.
While using this trick may seem cumbersome, it can be very useful when dealing with many variables inside a branch. Furthermore, it is not required to wrap all variables with _; only variables that are involved in an expression whose type-checking has to be delayed must be wrapped, but the other ones are not required. There are still a few things to know about compile-time branching in Hana, but you can dig deeper by looking at the reference for hana::eval_if, hana::if_ and hana::lazy.
Why should we limit ourselves to arithmetic operations and branching? When you start considering IntegralConstants as objects, it becomes sensible to augment their interface with more functions that are generally useful. For example, Hana's IntegralConstants define a times member function that can be used to invoke a function a certain number of times, which is especially useful for loop unrolling:
In the above code, the 10 calls to f are expanded at compile-time. In other words, this is equivalent to writing
Another nice use of IntegralConstants is to define good-looking operators for indexing heterogeneous sequences. Whereas std::tuple must be accessed with std::get, hana::tuple can be accessed using the familiar operator[] used for standard library containers:
How this works is very simple. Basically, hana::tuple defines an operator[] taking an IntegralConstant instead of a normal integer, in a way similar to
This is the end of the section on IntegralConstants. This section introduced the feel behind Hana's new way of metaprogramming; if you liked what you've seen so far, the rest of this tutorial should feel just like home.
At this point, if you are interested in doing type-level computations as with the MPL, you might be wondering how is Hana going to help you. Do not despair. Hana provides a way to perform type-level computations with a great deal of expressiveness by representing types as values, just like we represented compile-time numbers as values. This is a completely new way of approaching metaprogramming, and you should try to set your old MPL habits aside for a bit if you want to become proficient with Hana.
However, please be aware that modern C++ features like auto-deduced return type remove the need for type computations in many cases. Hence, before even considering to do a type computation, you should ask yourself whether there's a simpler way to achieve what you're trying to achieve. In most cases, the answer will be yes. However, when the answer is no, Hana will provide you with nuclear-strength facilities to do what needs to be done.
The key behind Hana's approach to type-level computations is essentially the same as the approach to compile-time arithmetic. Basically, the idea is to represent compile-time entities as objects by wrapping them into some kind of container. For IntegralConstants, the compile-time entities were constant expressions of an integral type and the wrapper we used was integral_constant. In this section, the compile-time entities will be types and the wrapper we'll be using is called type. Just like we did for IntegralConstants, let's start by defining a dummy template that could be used to represent a type:
basic_type here because we're only building a naive version of the actual functionality provided by Hana.While this may seem completely useless, it is actually enough to start writing metafunctions that look like functions. Indeed, consider the following alternate implementations of std::add_pointer and std::is_pointer:
We've just written metafunctions that look like functions, just like we wrote compile-time arithmetic metafunctions as heterogeneous C++ operators in the previous section. Here's how we can use them:
Notice how we can now use a normal function call syntax to perform type-level computations? This is analogous to how using values for compile-time numbers allowed us to use normal C++ operators to perform compile-time computations. Like we did for integral_constant, we can also go one step further and use C++14 variable templates to provide syntactic sugar for creating types:
hana::type_c variable template is implemented because of some subtleties; things were dumbed down here for the sake of the explanation. Please check the reference for hana::type to know exactly what you can expect from a hana::type_c<...>.But what does that buy us? Well, since a type_c<...> is just an object, we can store it in a heterogeneous sequence like a tuple, we can move it around and pass it to (or return it from) functions, and we can do basically anything else that requires an object:
make_tuple(type_c<T>...) can be annoying when there are several types. For this reason, Hana provides the tuple_t<T...> variable template, which is syntactic sugar for make_tuple(type_c<T>...).Also, notice that since the above tuple is really just a normal heterogeneous sequence, we can apply heterogeneous algorithms on that sequence just like we could on a tuple of ints, for example. Furthermore, since we're just manipulating objects, we can now use the full language instead of just the small subset available at the type-level. For example, consider the task of removing all the types that are not a reference or a pointer from a sequence of types. With the MPL, we would have to use a placeholder expression to express the predicate, which is clunky:
Now, since we're manipulating objects, we can use the full language and use a generic lambda instead, which leads to much more readable code:
Since Hana handles all heterogeneous containers uniformly, this approach of representing types as values also has the benefit that a single library is now needed for both heterogeneous computations and type level computations. Indeed, whereas we would normally need two different libraries to perform almost identical tasks, we now need a single library. Again, consider the task of filtering a sequence with a predicate. With MPL and Fusion, this is what we must do:
With Hana, a single library is required. Notice how we use the same filter algorithm and the same container, and only tweak the predicate so it can operate on values:
But that is not all. Indeed, having a unified syntax for type-level and value-level computations allows us to achieve greater consistency in the interface of heterogeneous containers. For example, consider the simple task of creating a heterogeneous map associating types to values, and then accessing an element of it. With Fusion, what's happening is far from obvious to the untrained eye:
However, with a unified syntax for types and values, the same thing becomes much clearer:
While Hana's way takes more lines of codes, it is also arguably more readable and closer to how someone would expect to initialize a map.
So far, we can represent types as values and perform type-level computations on those objects using the usual C++ syntax. This is nice, but it is not very useful because we have no way to get back a normal C++ type from an object representation. For example, how could we declare a variable whose type is the result of a type computation?
Right now, there is no easy way to do it. To make this easier to achieve, we enrich the interface of the basic_type container that we defined above. Instead of being an empty struct, we now define it as
basic_type a metafunction in the MPL sense.This way, we can use decltype to easily access the actual C++ type represented by a type_c<...> object:
In general, doing type-level metaprogramming with Hana is a three step process:
hana::type_c<...>decltype(...)::typeNow, you must be thinking that this is incredibly cumbersome. In reality, it is very manageable for several reasons. First, this wrapping and unwrapping only needs to happen at some very thin boundaries.
Furthermore, since you get the advantage of working with objects (without having to wrap/unwrap) inside the computation, the cost of wrapping and unwrapping is amortized on the whole computation. Hence, for complex type computations, the syntactic noise of this three step process quickly becomes negligible in light of the expressiveness gain of working with values inside that computation. Also, using values instead of types means that we can avoid typing typename and template all around the place, which accounted for a lot of syntactic noise in classic metaprogramming.
Another point is that the three full steps are not always required. Indeed, sometimes one just needs to do a type-level computation and query something about the result, without necessarily fetching the result as a normal C++ type:
In this case, we were able to skip the third step because we did not need to access the actual type represented by result. In other cases, the first step can be avoided, like when using tuple_t, which has no more syntactic noise than any other pure type-level approach:
For skeptical readers, let's consider the task of finding the smallest type in a sequence of types. This is a very good example of a short type-only computation, which is where we would expect the new paradigm to suffer the most. As you will see, things stay manageable even for small computations. First, let's implement it with the MPL:
The result is quite readable (for anyone familiar with the MPL). Let's now implement the same thing using Hana:
As you can witness, the syntactic noise of the 3-step process is almost completely hidden by the rest of the computation.
The first type-level computation that we introduced in the form of a function looked like:
While it looks more complicated, we could also write it as:
However, this implementation emphasizes the fact that we're really emulating an existing metafunction and simply representing it as a function. In other words, we're lifting a metafunction (std::add_pointer) to the world of values by creating our own add_pointer function. It turns out that this lifting process is a generic one. Indeed, given any metafunction, we could write almost the same thing:
This mechanical transformation is easy to abstract into a generic lifter that can handle any MPL Metafunction as follows:
More generally, we'll want to allow metafunctions with any number of arguments, which brings us to the following less naive implementation:
Hana provides a similar generic metafunction lifter called hana::metafunction. One small improvement is that hana::metafunction<F> is a function object instead of an overloaded function, so one can pass it to higher-order algorithms. It is also a model of the slightly more powerful concept of Metafunction, but this can safely be ignored for now. The process we explored in this section does not only apply to metafunctions; it also applies to templates. Indeed, we could define:
Hana provides a generic lifter for templates named hana::template_, and it also provides a generic lifter for MPL MetafunctionClasses named hana::metafunction_class. This gives us a way to uniformly represent "legacy" type-level computations as functions, so that any code written using a classic type-level metaprogramming library can almost trivially be used with Hana. For example, say you have a large chunk of MPL-based code and you'd like to interface with Hana. The process of doing so is no harder than wrapping your metafunctions with the lifter provided by Hana:
However, note that not all type-level computations can be lifted as-is with the tools provided by Hana. For example, std::extent can't be lifted because it requires non-type template parameters. Since there is no way to deal with non-type template parameters uniformly in C++, one must resort to using a hand-written function object specific to that type-level computation:
std::integral_constants (<boost/hana/ext/std/integral_constant.hpp>) when using type traits from <type_traits> directly.In practice, however, this should not be a problem since the vast majority of type-level computations can be lifted easily. Finally, since metafunctions provided by the <type_traits> header are used so frequently, Hana provides a lifted version for every one of them. Those lifted traits are in the hana::traits namespace, and they live in the <boost/hana/traits.hpp> header:
This is the end of the section on type computations. While this new paradigm for type level programming might be difficult to grok at first, it will make more sense as you use it more and more. You will also come to appreciate how it blurs the line between types and values, opening new exciting possibilities and simplifying many tasks.
Static introspection, as we will discuss it here, is the ability of a program to examine the type of an object at compile-time. In other words, it is a programmatic interface to interact with types at compile-time. For example, have you ever wanted to check whether some unknown type has a member named foo? Or perhaps at some point you have needed to iterate on the members of a struct?
If you have written a bit of templates in your life, chances are very high that you came across the first problem of checking for a member. Also, anyone having tried to implement object serialization or even just pretty printing has come across the second problem. In most dynamic languages like Python, Ruby or JavaScript, these problems are completely solved and introspection is used every day by programmers to make a lot of tasks simpler. However, as a C++ programmer, we do not have language support for those things, which makes several tasks much harder than they should be. While language support would likely be needed to properly tackle this problem, Hana makes some common introspection patterns much more accessible.
Given an object of an unknown type, it is sometimes desirable to check whether this object has a member (or member function) with some name. This can be used to perform sophisticated flavors of overloading. For example, consider the problem of calling a toString method on objects that support it, but providing another default implementation for objects that do not support it:
How could we implement a check for the validity of obj.toString() as above in a generic fashion (so it can be reused in other functions, for example)? Normally, we would be stuck writing some kind of SFINAE-based detection:
This works, but the intent is not very clear and most people without a deep knowledge of template metaprogramming would think this is black magic. Then, we could implement optionalToString as
if statement will be compiled. If obj does not have a toString method, the compilation of the if branch will fail. We will address this issue in a moment.Instead of the above SFINAE trick, Hana provides a is_valid function that can be combined with C++14 generic lambdas to obtain a much cleaner implementation of the same thing:
This leaves us with a function object has_toString which returns whether the given expression is valid on the argument we pass to it. The result is returned as an IntegralConstant, so constexpr-ness is not an issue here because the result of the function is represented as a type anyway. Now, in addition to being less verbose (that's a one liner!), the intent is much clearer. Other benefits are the fact that has_toString can be passed to higher order algorithms and it can also be defined at function scope, so there is no need to pollute the namespace scope with implementation details. Here is how we would now write optionalToString:
Much cleaner, right? However, as we said earlier, this implementation won't actually work because both branches of the if always have to be compiled, regardless of whether obj has a toString method. There are several possible options, but the most classical one is to use std::enable_if:
has_toString returns an IntegralConstant to write decltype(...)::value, which is a constant expression. For some reason, has_toString(obj) is not considered a constant expression, even though I think it should be one because we never read from obj (see the section on advanced constexpr).While this implementation is perfectly valid, it is still pretty cumbersome because it requires writing two different functions and going through the hoops of SFINAE explicitly by using std::enable_if. However, as you might remember from the section on compile-time branching, Hana provides an if_ function that can be used to emulate the functionality of static_if. Here is how we could write optionalToString with hana::if_:
Now, the previous example covered only the specific case of checking for the presence of a non-static member function. However, is_valid can be used to detect the validity of almost any kind of expression. For completeness, we now present a list of common use cases for validity checking along with how to use is_valid to implement them.
The first idiom we'll look at is checking for the presence of a non-static member. We can do it in a similar way as we did for the previous example:
Notice how we cast the result of x.member to void? This is to make sure that our detection also works for types that can't be returned from functions, like array types. Also, it is important to use a reference as the parameter to our generic lambda, because that would otherwise require x to be CopyConstructible, which is not what we're trying to check. This approach is simple and the most convenient when an object is available. However, when the checker is intended to be used with no object around, the following alternate implementation can be better suited:
This validity checker is different from what we saw earlier because the generic lambda is not expecting an usual object anymore; it is now expecting a type (which is an object, but still represents a type). We then use the hana::traits::declval lifted metafunction from the <boost/hana/traits.hpp> header to create an rvalue of the type represented by t, which we can then use to check for a non-static member. Finally, instead of passing an actual object to has_member (like Foo{} or Bar{}), we now pass a type_c<...>. This implementation is ideal for when no object is lying around.
Checking for a static member is easy, and it is provided for completeness:
Again, we expect a type to be passed to the checker. Inside the generic lambda, we use decltype(t)::type to fetch the actual C++ type represented by the t object, as explained in the section on type computations. Then, we fetch the static member inside that type and cast it to void, for the same reason as we did for non-static members.
Checking for a nested type name is not hard, but it is slightly more convoluted than the previous cases:
One might wonder why we use -> hana::type<typename-expression> instead of simply -> typename-expression. Again, the reason is that we want to support types that can't be returned from functions, like array types or incomplete types.
Checking for a nested template name is similar to checking for a nested type name, except we use the template_<...> variable template instead of type<...> in the generic lambda:
Checking whether a template specialization is valid can be done too, but we now pass a template_<...> to is_valid instead of a type<...>, because that's what we want to make the check on:
Doing something only if an expression is well-formed is a very common pattern in C++. Indeed, the optionalToString function is just one instance of the following pattern, which is very general:
To encapsulate this pattern, Hana provides the sfinae function, which allows executing an expression, but only if it is well-formed:
Here, we create a maybe_add function, which is simply a generic lambda wrapped with Hana's sfinae function. maybe_add is a function which takes two inputs and returns just the result of the generic lambda if that call is well-formed, and nothing otherwise. just(...) and nothing both belong to a type of container called hana::optional, which is essentially a compile-time std::optional. All in all, maybe_add is morally equivalent to the following function returning a std::optional, except that the check is done at compile-time:
It turns out that we can take advantage of sfinae and optional to implement the optionalToString function as follows:
First, we wrap toString with the sfinae function. Hence, maybe_toString is a function which either returns just(x.toString()) if that is well-formed, or nothing otherwise. Secondly, we use the .value_or() function to extract the optional value from the container. If the optional value is nothing, .value_or() returns the default value given to it; otherwise, it returns the value inside the just (here x.toString()). This way of seeing SFINAE as a special case of computations that might fail is very clean and powerful, especially since sfinae'd functions can be combined through the hana::optional Monad, which is left to the reference documentation.
Have you ever wanted to iterate over the members of a user-defined type? The goal of this section is to show you how Hana can be used to do it quite easily. To allow working with user-defined types, Hana defines the Struct concept. Once a user-defined type is a model of that concept, one can iterate over the members of an object of that type and query other useful information. To turn a user-defined type into a Struct, a couple of options are available. First, you may define the members of your user-defined type with the BOOST_HANA_DEFINE_STRUCT macro:
This macro defines two members (name and age) with the given types. Then, it defines some boilerplate inside a Person::hana nested struct, which is required to make Person a model of the Struct concept. No constructors are defined (so POD-ness is retained), the members are defined in the same order as they appear here and the macro can be used with template structs just as well, and at any scope. Also note that you are free to add more members to the Person type after or before you use the macro. However, only members defined with the macro will be picked up when introspecting the Person type. Easy enough? Now, a Person can be accessed programmatically:
Iteration over a Struct is done as if the Struct was a sequence of pairs, where the first element of a pair is the key associated to a member, and the second element is the member itself. When a Struct is defined through the BOOST_HANA_DEFINE_STRUCT macro, the key associated to any member is a compile-time hana::string representing the name of that member. This is why the function used with for_each takes a single argument pair, and then uses first and second to access the subparts of the pair. Also, notice how the to<char const*> function is used on the name of the member? This converts the compile-time string to a constexpr char const* so it can couted. Since it can be annoying to always use first and second to fetch the subparts of the pair, we can also use the fuse function to wrap our lambda and make it a binary lambda instead:
Now, it looks much cleaner. As we just mentioned, Structs are seen as a kind of sequence of pairs for the purpose of iteration. In fact, a Struct can even be searched like an associative data structure whose keys are the names of the members, and whose values are the members themselves:
_s user-defined literal creates a compile-time hana::string. It is located in the boost::hana::literals namespace. Note that it is not part of the standard yet, but it is supported by Clang and GCC. If you want to stay 100% standard, you can use the BOOST_HANA_STRING macro instead.The main difference between a Struct and a hana::map is that a map can be modified (keys can be added and removed), while a Struct is immutable. However, you can easily convert a Struct into a hana::map with to<map_tag>, and then you can manipulate it in a more flexible way.
Using the BOOST_HANA_DEFINE_STRUCT macro to adapt a struct is convenient, but sometimes one can't modify the type that needs to be adapted. In these cases, the BOOST_HANA_ADAPT_STRUCT macro can be used to adapt a struct in a ad-hoc manner:
BOOST_HANA_ADAPT_STRUCT macro must be used at global scope.The effect is exactly the same as with the BOOST_HANA_DEFINE_STRUCT macro, except you do not need to modify the type you want to adapt, which is sometimes useful. Finally, it is also possible to define custom accessors by using the BOOST_HANA_ADAPT_ADT macro:
This way, the names used to access the members of the Struct will be those specified, and the associated function will be called on the Struct when retrieving that member. Before we move on to a concrete example of using these introspection features, it should also be mentioned that structs can be adapted without using macros. This advanced interface for defining Structs can be used for example to specify keys that are not compile-time strings. The advanced interface is described in the documentation of the Struct concept.
Let's now move on with a concrete example of using the introspection capabilities we just presented for printing custom objects as JSON. Our end goal is to have something like this:
And the output, after passing it through a JSON pretty-printer, should look like
First, let's define a couple of utility functions to make string manipulation easier:
The quote and the to_json overloads are pretty self-explanatory. The join function, however, might need a bit of explanation. Basically, the intersperse function takes a sequence and a separator, and returns a new sequence with the separator in between each pair of elements of the original sequence. In other words, we take a sequence of the form [x1, ..., xn] and turn it into a sequence of the form [x1, sep, x2, sep, ..., sep, xn]. Finally, we fold the resulting sequence with the _ + _ function object, which is equivalent to std::plus<>{}. Since our sequence contains std::strings (we assume it does), this has the effect of concatenating all the strings of the sequence into one big string. Now, let's define how to print a Sequence:
First, we use the transform algorithm to turn our sequence of objects into a sequence of std::strings in JSON format. Then, we join that sequence with commas and we enclose it with [] to denote a sequence in JSON notation. Simple enough? Let's now take a look at how to print user-defined types:
Here, we use the keys method to retrieve a tuple containing the names of the members of the user-defined type. Then, we transform that sequence into a sequence of "name" : member strings, which we then join and enclose with {}, which is used to denote objects in JSON notation. And that's it!
This section explains several important notions about Hana's containers: how to create them, the lifetime of their elements and other concerns.
While the usual way of creating an object in C++ is to use its constructor, heterogeneous programming makes things a bit more complicated. Indeed, in most cases, one is not interested in (or even aware of) the actual type of the heterogeneous container to be created. At other times, one could write out that type explicitly, but it would be redundant or cumbersome to do so. For this reason, Hana uses a different approach borrowed from std::make_tuple to create new containers. Much like one can create a std::tuple with std::make_tuple, a hana::tuple can be created with hana::make_tuple. However, more generally, containers in Hana may be created with the make function:
In fact, make_tuple is just a shortcut for make<tuple_tag> so you don't have to type boost::hana::make<boost::hana::tuple_tag> when you are out of Hana's namespace. Simply put, make<...> is is used all around the library to create different types of objects, thus generalizing the std::make_xxx family of functions. For example, one can create a hana::range of compile-time integers with make<range_tag>:
These types with a trailing
_tagare dummy types representing a family of heterogeneous containers (hana::tuple,hana::map, etc..). Tags are documented in the section on Hana's core.
For convenience, whenever a component of Hana provides a make<xxx_tag> function, it also provides the make_xxx shortcut to reduce typing. Also, an interesting point that can be raised in this example is the fact that r is constexpr. In general, whenever a container is initialized with constant expressions only (which is the case for r), that container may be marked as constexpr.
So far, we have only created containers with the make_xxx family of functions. However, some containers do provide constructors as part of their interface. For example, one can create a hana::tuple just like one would create a std::tuple:
When constructors (or any member function really) are part of the public interface, they will be documented on a per-container basis. However, in the general case, one should not take for granted that a container can be constructed as the tuple was constructed above. For example, trying to create a hana::range that way will not work:
In fact, we can't even specify the type of the object we'd like to create in that case, because the exact type of a hana::range is implementation-defined, which brings us to the next section.
The goal of this section is to clarify what can be expected from the types of Hana's containers. Indeed, so far, we always let the compiler deduce the actual type of containers by using the make_xxx family of functions along with auto. But in general, what can we say about the type of a container?
The answer is that it depends. Some containers have well defined types, while others do not specify their representation. In this example, the type of the object returned by make_tuple is well-defined, while the type returned by make_range is implementation-defined:
This is documented on a per-container basis; when a container has an implementation-defined representation, a note explaining exactly what can be expected from that representation is included in the container's description. There are several reasons for leaving the representation of a container unspecified; they are explained in the rationales. When the representation of a container is implementation-defined, one must be careful not to make any assumptions about it, unless those assumption are explicitly allowed in the documentation of the container. For example, assuming that one can safely inherit from a container or that the elements in the container are stored in the same order as specified in its template argument list is generally not safe.
While necessary, leaving the type of some containers unspecified makes some things very difficult to achieve, like overloading functions on heterogeneous containers:
The is_a utility is provided for this reason (and others). is_a allows checking whether a type is a precise kind of container using its tag, regardless of the actual type of the container. For example, the above example could be rewritten as
This way, the second overload of f will only match when R is a type whose tag is range_tag, regardless of the exact representation of that range. Of course, is_a can be used with any kind of container: tuple, map, set and so on.
In Hana, containers own their elements. When a container is created, it makes a copy of the elements used to initialize it and stores them inside the container. Of course, unnecessary copies are avoided by using move semantics. Because of those owning semantics, the lifetime of the objects inside the container is the same as that of the container.
Much like containers in the standard library, containers in Hana expect their elements to be objects. For this reason, references may not be stored in them. When references must be stored inside a container, one should use a std::reference_wrapper instead:
Much like the previous section introduced general but important notions about heterogeneous containers, this section introduces general notions about heterogeneous algorithms.
Algorithms in Hana always return a new container holding the result. This allows one to easily chain algorithms by simply using the result of the first as the input of the second. For example, to apply a function to every element of a tuple and then reverse the result, one simply has to connect the reverse and transform algorithms:
This is different from the algorithms of the standard library, where one has to provide iterators to the underlying sequence. For reasons documented in the rationales, an iterator-based design was considered but was quickly dismissed in favor of composable and efficient abstractions better suited to the very particular context of heterogeneous programming.
One might also think that returning full sequences that own their elements from an algorithm would lead to tons of undesirable copies. For example, when using reverse and transform, one could think that an intermediate copy is made after the call to transform:
To make sure this does not happen, Hana uses perfect forwarding and move semantics heavily so it can provide an almost optimal runtime performance. So instead of doing a copy, a move occurs between reverse and transform:
Ultimately, the goal is that code written using Hana should be equivalent to clever hand-written code, except it should be enjoyable to write. Performance considerations are explained in depth in their own section.
Algorithms in Hana are not lazy. When an algorithm is called, it does its job and returns a new sequence containing the result, end of the story. For example, calling the permutations algorithm on a large sequence is a stupid idea, because Hana will actually compute all the permutations:
To contrast, algorithms in Boost.Fusion return views which hold the original sequence by reference and apply the algorithm on demand, as the elements of the sequence are accessed. This leads to subtle lifetime issues, like having a view that refers to a sequence that was destroyed. Hana's design assumes that most of the time, we want to access all or almost all the elements in a sequence anyway, and hence performance is not a big argument in favor of laziness.
Algorithms in Hana are a bit special with respect to the runtime code they are expanded into. The goal of this subsection is not to explain exactly what code is generated, which depends on the compiler anyway, but to give a feel for things. Basically, a Hana algorithm is like an unrolled version of an equivalent classical algorithm. Indeed, since the bounds of the processed sequence are known at compile-time, it makes sense that we can unroll the loop over the sequence. For example, let's consider the for_each algorithm:
If xs was a runtime sequence instead of a tuple, its length would only be known at runtime and the above code would have to be implemented as a loop:
However, in our case, the length of the sequence is known at compile-time and so we don't have to check the index at each iteration. Hence, we can just write:
The main difference here is that no bound checking and index increment is done at each step, because there is no index anymore; the loop was effectively unrolled. In some cases, this can be desirable for performance reasons. In other cases, this can be detrimental to performance because it causes the code size to grow. As always, performance is a tricky subject and whether you actually want loop unrolling to happen should be tackled on a case-by-case basis. As a rule of thumb, algorithms processing all (or a subset) of the elements of a container are unrolled. In fact, if you think about it, this unrolling is the only way to go for heterogeneous sequences, because different elements of the sequence may have different types. As you might have noticed, we're not using normal indices into the tuple, but compile-time indices, which can't be generated by a normal for loop. In other words, the following does not make sense:
By default, Hana assumes functions to be pure. A pure function is a function that has no side-effects at all. In other words, it is a function whose effect on the program is solely determined by its return value. In particular, such a function may not access any state that outlives a single invocation of the function. These functions have very nice properties, like the ability to reason mathematically about them, to reorder or even eliminate calls, and so on. Except where specified otherwise, all functions used with Hana (i.e. used in higher order algorithms) should be pure. In particular, functions passed to higher order algorithms are not guaranteed to be called any specific number of times. Furthermore, the order of execution is generally not specified and should therefore not be taken for granted. If this lack of guarantees about function invocations seems crazy, consider the following use of the any_of algorithm:
std::integral_constant contained in <boost/hana/ext/std/integral_constant.hpp> must be included.According to the previous section on unrolling, this algorithm should be expanded into something like:
Of course, the above code can't work as-is, because we're calling pred inside something that would have to be a constant expression, but pred is a lambda (and lambdas can't be called in constant expressions). However, whether any of these objects has an integral type is clearly known at compile-time, and hence we would expect that computing the answer only involves compile-time computations. In fact, this is exactly what Hana does, and the above algorithm is expanded into something like:
any_of must actually be more general than this. However, this lie-to-children is perfect for educational purposes.As you can see, the predicate is never even executed; only its result type on a particular object is used. Regarding the order of evaluation, consider the transform algorithm, which is specified (for tuples) as:
Since make_tuple is a function, and since the evaluation order for the arguments of a function is unspecified, the order in which f is called on each element of the tuple is unspecified too. If one sticks to pure functions, everything works fine and the resulting code is often easier to understand. However, some exceptional algorithms like for_each do expect impure functions, and they guarantee an order of evaluation. Indeed, a for_each algorithm that would only take pure functions would be pretty much useless. When an algorithm can accept an impure function or guarantees some order of evaluation, the documentation for that algorithm will mention it explicitly. However, by default, no guarantees may be taken for granted.
This section introduces the notion of cross-phase computations and algorithms. In fact, we have already used cross-phase algorithms in the quick start, for example with filter, but we did not explain exactly what was happening at that time. But before we introduce cross-phase algorithms, let's define what we mean by cross-phase. The phases we're referring to here are the compilation and the execution of a program. In C++ as in most statically typed languages, there is a clear distinction between compile-time and runtime; this is called phase distinction. When we speak of a cross-phase computation, we mean a computation that is somehow performed across those phases; i.e. that is partly executed at compile-time and partly executed at runtime.
Like we saw in earlier examples, some functions are able to return something that can be used at compile-time even when they are called on a runtime value. For example, let's consider the length function applied to a non-constexpr container:
Obviously, the tuple can't be made constexpr, since it contains runtime std::strings. Still, even though it is not called on a constant expression, length returns something that can be used at compile-time. If you think of it, the size of the tuple is known at compile-time regardless of its content, and hence it would only make sense for this information to be available to us at compile-time. If that seems surprising, think about std::tuple and std::tuple_size:
Since the size of the tuple is encoded in its type, it is always available at compile-time regardless of whether the tuple is constexpr or not. In Hana, this is implemented by having length return an IntegralConstant. Since an IntegralConstant's value is encoded in its type, the result of length is contained in the type of the object it returns, and the length is therefore known at compile-time. Because length goes from a runtime value (the container) to a compile-time value (the IntegralConstant), length is a trivial example of a cross-phase algorithm (trivial because it does not really manipulate the tuple). Another algorithm that is very similar to length is the is_empty algorithm, which returns whether a container is empty:
More generally, any algorithm that takes a container whose value is known at runtime but queries something that can be known at compile-time should be able to return an IntegralConstant or another similar compile-time value. Let's make things slightly more complicated by considering the any_of algorithm, which we already encountered in the previous section:
In this example, the result can't be known at compile-time, because the predicate returns a bool that is the result of comparing two std::strings. Since std::strings can't be compared at compile-time, the predicate must operate at runtime, and the overall result of the algorithm can then only be known at runtime too. However, let's say we used any_of with the following predicate instead:
std::integral_constant contained in <boost/hana/ext/std/integral_constant.hpp> must be included.First, since the predicate is only querying information about the type of each element of the tuple, it is clear that its result can be known at compile-time. Since the number of elements in the tuple is also known at compile-time, the overall result of the algorithm can, in theory, be known at compile-time. More precisely, what happens is that the predicate returns a value initialized std::is_same<...>, which inherits from std::integral_constant. Hana recognizes these objects, and the algorithm is written in such a way that it preserves the compile-timeness of the predicate's result. In the end, any_of hence returns an IntegralConstant holding the result of the algorithm, and we use the compiler's type deduction in a clever way to make it look easy. Hence, it would be equivalent to write (but then you would need to already know the result of the algorithm!):
Ok, so some algorithms are able to return compile-time values when their input satisfies some constraints with respect to compile-timeness. However, other algorithms are more restrictive and they require their inputs to satisfy some constraints regarding compile-timeness, without which they are not able to operate at all. An example of this is filter, which takes a sequence and a predicate, and returns a new sequence containing only those elements for which the predicate is satisfied. filter requires the predicate to return an IntegralConstant. While this requirement may seem stringent, it really makes sense if you think about it. Indeed, since we're removing some elements from the heterogeneous sequence, the type of the resulting sequence depends on the result of the predicate. Hence, the result of the predicate has to be known at compile-time for the compiler to be able to assign a type to the returned sequence. For example, consider what happens when we try to filter a heterogeneous sequence as follows:
Clearly, we know that the predicate will only return false on the second element, and hence the result should be a [Fish, Dog] tuple. However, the compiler has no way of knowing this since the predicate's result is the result of a runtime computation, which happens way after the compiler has finished its job. Hence, the compiler does not have enough information to determine the return type of the algorithm. However, we could filter the same sequence with any predicate whose result is available at compile-time:
Since the predicate returns an IntegralConstant, we know which elements of the heterogeneous sequence we'll be keeping at compile-time. Hence, the compiler is able to figure out the return type of the algorithm. Other algorithms like partition and sort work similarly; special algorithm requirements are always documented, just read the reference documentation of an algorithm before using it to avoid surprises.
This is the end of the section on algorithms. While this constitutes a fairly complete explanation of phase interaction inside algorithms, a deeper understanding can be gained by reading the advanced section on constexpr and the reference for Constant and IntegralConstant.
constexpr function objects instead of being template functions. This allows passing them to higher-order algorithms, which is very useful. However, since those function objects are defined at namespace scope in the header files, this causes each translation unit to see a different algorithm object. Hence, the address of an algorithm function object is not guaranteed to be unique across translation units, which can cause an ODR violation if one relies on such an address. So, in short, do not rely on the uniqueness of the address of any global object provided by Hana, which does not make sense in the general case anyway because such objects are constexpr. See issue #76 for more information.C++ programmers love performance, so here's a whole section dedicated to it. Since Hana lives on the frontier between runtime and compile-time computations, we are not only interested in runtime performance, but also compile-time performance. Since both topics are pretty much disjoint, we treat them separately below.
hana::map and hana::set) have a pretty bad compile-time behavior because of their naive implementation, and their runtime behavior also seems to be problematic in some cases. Improving this situation is in the TODO list.C++ metaprogramming brings its share of awful things. One of the most annoying and well-known problem associated to it is interminable compilation times. Hana claims to be more compile-time efficient than its predecessors; this is a bold claim and we will now try to back it. Of course, Hana can't do miracles; metaprogramming is a byproduct of the C++ template system and the compiler is not meant to be used as an interpreter for some meta language. However, by using cutting edge and intensely benchmarked techniques, Hana is able to minimize the strain on the compiler.
Before we dive, let me make a quick note on the methodology used to measure compile-time performance in Hana. Previous metaprogramming libraries measured the compile-time complexity of their meta-algorithms and meta-sequences by looking at the number of instantiations the compiler had to perform. While easy to understand, this way of measuring the compile-time complexity actually does not give us a lot of information regarding the compilation time, which is what we're interested in minimizing at the end of the day. Basically, the reason for this is that template metaprogramming is such a twisted model of computation that it's very hard to find a standard way of measuring the performance of algorithms. Hence, instead of presenting meaningless complexity analyses, we prefer to benchmark everything on every supported compiler and to pick the best implementation on that compiler. Also note that the benchmarks we present here are quite precise. Indeed, even though we do not take multiple measurements and take their mean or something similar to reduce incertitude, the benchmarks are very stable when they are regenerated, which suggests a reasonably good precision. Now, let's dive.
First, Hana minimizes its dependency on the preprocessor. In addition to yielding cleaner error messages in many cases, this reduces the overall parsing and preprocessing time for header files. Also, because Hana only supports cutting edge compilers, there are very few workarounds in the library, which results in a cleaner and smaller library. Finally, Hana minimizes reliance on any kind of external dependencies. In particular, it only uses other Boost libraries in a few specific cases, and it does not rely on the standard library for the largest part. There are several reasons (other than include times) for doing so; they are documented in the rationales.
Below is a chart showing the time required to include different libraries. The chart shows the time for including everything in the (non-external) public API of each library. For example, for Hana this means the <boost/hana.hpp> header, which excludes the external adapters. For other libraries like Boost.Fusion, this means including all the public headers in the boost/fusion/ directory, but not the adapters for external libraries like the MPL.
In addition to reduced preprocessing times, Hana uses modern techniques to implement heterogeneous sequences and algorithms in the most compile-time efficient way possible. Before jumping to the compile-time performance of the algorithms, we will have a look at the compile-time cost of creating heterogeneous sequences. Indeed, since we will be presenting algorithms that work on sequences, we must be aware of the cost of creating the sequences themselves, since that will influence the benchmarks for the algorithms. The following chart presents the compile-time cost of creating a sequence of n heterogeneous elements.
The benchmark methodology is to always create the sequences in the most efficient way possible. For Hana and std::tuple, this simply means using the appropriate make_tuple function. However, for the MPL, this means creating a mpl::vectorN of size up to 20, and then using mpl::push_back to create larger vectors. We use a similar technique for Fusion sequences. The reason for doing so is that Fusion and MPL sequences have fixed size limits, and the techniques used here have been found to be the fastest way to create longer sequences.
For completeness, we also present the compile-time cost of creating a std::array with n elements. However, note that std::array can only hold elements with a single type, so we're comparing apples and oranges here. As you can see, the cost of creating a std::array is constant and essentially inexistent (the non-zero overhead is that of simply including the <array> header). Hence, while Hana provides improved compile-times over other heterogeneous containers, please stick with normal homogeneous containers if that's all you need for your application; your compile-times will be much faster that way.
You can also see that creating sequences has a non-negligible cost. Actually, this is really the most expensive part of doing heterogeneous computations, as you will see in the following charts. Hence, when you look at the charts below, keep in mind the cost of merely creating the sequences. Also note that only the most important algorithms will be presented here, but the Metabench project provides micro benchmarks for compile-time performance for almost all of Hana's algorithms. Also, the benchmarks we present compare several different libraries. However, since Hana and Fusion can work with values and not only types, comparing their algorithms with type-only libraries like MPL is not really fair. Indeed, Hana and Fusion algorithms are more powerful since they also allow runtime effects to be performed. However, the comparison between Fusion and Hana is fair, because both libraries are just as powerful (strictly speaking). Finally, we can't show benchmarks of the algorithms for std::tuple, because the standard does not provide equivalent algorithms. Of course, we could use Hana's external adapters, but that would not be a faithful comparison.
The first algorithm which is ubiquitous in metaprogramming is transform. It takes a sequence and a function, and returns a new sequence containing the result of applying the function to each element. The following chart presents the compile-time performance of applying transform to a sequence of n elements. The x axis represents the number of elements in the sequence, and the y axis represents the compilation time in seconds. Also note that we're using the transform equivalent in each library; we're not using Hana's transform through the Boost.Fusion adapters, for example, because we really want to benchmark their implementation against ours.
Here, we can see that Hana's tuple performs better than all the other alternatives. This is mainly due to the fact that we use C++11 variadic parameter pack expansion to implement this algorithm under the hood, which is quite efficient.
Before we move on, it is important to mention something regarding the benchmark methodology for Fusion algorithms. Some algorithms in Fusion are lazy, which means that they don't actually perform anything, but simply return a modified view to the original data. This is the case of fusion::transform, which simply returns a transformed view that applies the function to each element of the original sequence as those elements are accessed. If we want to benchmark anything at all, we need to force the evaluation of that view, as would eventually happen when accessing the elements of the sequence in real code. However, for complex computations with multiple layers, a lazy approach may yield a substantially different compile-time profile. Of course, this difference is poorly represented in micro benchmarks, so keep in mind that these benchmarks only give a part of the big picture. For completeness in the rest of the section, we will mention when a Fusion algorithm is lazy, so that you know when we're artificially forcing the evaluation of the algorithm for the purpose of benchmarking.
The second important class of algorithms are folds. Folds can be used to implement many other algorithms like count_if, minimum and so on. Hence, a good compile-time performance for fold algorithms ensures a good compile-time performance for those derived algorithms, which is why we're only presenting folds here. Also note that all the non-monadic fold variants are somewhat equivalent in terms of compile-time, so we only present the left folds. The following chart presents the compile-time performance of applying fold_left to a sequence of n elements. The x axis represents the number of elements in the sequence, and the y axis represents the compilation time in seconds. The function used for folding is a dummy function that does nothing. In real code, you would likely fold with a nontrivial operation, so the curves would be worse than that. However, these are micro benchmarks and hence they only show the performance of the algorithm itself.
The third and last algorithm that we present here is the find_if algorithm. This algorithm is difficult to implement efficiently, because it requires stopping at the first element which satisfies the given predicate. For the same reason, modern techniques don't really help us here, so this algorithm constitutes a good test of the implementation quality of Hana, without taking into account the free lunch given to use by C++14.
As you can see, Hana performs better than Fusion, and as well as MPL, yet Hana's find_if can be used with values too, unlike MPL's. This concludes the section on compile-time performance. In case you want to see the performance of an algorithm that we have not presented here, the Metabench project provides compile-time benchmarks for most of Hana's algorithms.
Hana was designed to be very efficient at runtime. But before we dive into the details, let's clarify one thing. Hana being a metaprogramming library which allows manipulating both types and values, it does not always make sense to even talk about runtime performance. Indeed, for type-level computations and computations on IntegralConstants, runtime performance is simply not a concern, because the result of the computation is contained in a type, which is a purely compile-time entity. In other words, these computations involve only compile-time work, and no code is even generated to perform these computations at runtime. The only case where it makes sense to discuss runtime performance is when manipulating runtime values in heterogeneous containers and algorithms, because this is the only case where the compiler has to generate some runtime code. It is therefore only computations of this sort that we will be studying in the remainder of this section.
Like we did for compile-time benchmarks, the methodology used to measure runtime performance in Hana is data driven rather than analytical. In other words, instead of trying to determine the complexity of an algorithm by counting the number of basic operations it does as a function of the input size, we simply take measurements for the most interesting cases and see how it behaves. There are a couple of reasons for doing so. First, we do not expect Hana's algorithms to be called on large inputs since those algorithms work on heterogeneous sequences whose length must be known at compile-time. For example, if you tried to call the find_if algorithm on a sequence of 100k elements, your compiler would simply die while trying to generate the code for this algorithm. Hence, algorithms can't be called on very large inputs and the analytical approach then loses a lot of its attractiveness. Secondly, processors have evolved into pretty complex beasts, and the actual performance you'll be able to squeeze out is actually controlled by much more than the mere number of steps your algorithm is doing. For example, bad cache behavior or branch misprediction could turn a theoretically efficient algorithm into a slowpoke, especially for small inputs. Since Hana causes a lot of unrolling to happen, these factors must be considered even more carefully and any analytical approach would probably only comfort us into thinking we're efficient. Instead, we want hard data, and pretty charts to display it!
There are a couple of different aspects we will want to benchmark. First, we will obviously want to benchmark the execution time of the algorithms. Secondly, because of the by-value semantics used throughout the library, we will also want to make sure that the minimum amount of data is copied around. Finally, we will want to make sure that using Hana does not cause too much code bloat because of unrolling, as explained in the section on algorithms.
Just like we studied only a couple of key algorithms for compile-time performance, we will focus on the runtime performance of a few algorithms. For each benchmarked aspect, we will compare the algorithm as implemented by different libraries. Our goal is to always be at least as efficient as Boost.Fusion, which is near from optimality in terms of runtime performance. For comparison, we also show the same algorithm as executed on a runtime sequence, and on a sequence whose length is known at compile-time but whose transform algorithm does not use explicit loop unrolling. All the benchmarks presented here are done in a Release CMake configuration, which takes care of passing the proper optimization flags (usually -O3). Let's start with the following chart, which shows the execution time required to transform different kinds of sequences:
fusion::transform is usually lazy, and we're forcing its evaluation for the purpose of benchmarking.As you can see, Hana and Fusion are pretty much on the same line. std::array is slightly slower for larger collections data sets, and std::vector is noticeably slower for larger collections. Since we also want to look out for code bloat, let's take a look at the size of the executable generated for the exact same scenario:
As you can see, code bloat does not seem to be an issue, at least not one that can be detected in micro benchmarks such as this one. Let's now take a look at the fold algorithm, which is used very frequently:
Here, you can see that everybody is performing pretty much the same, which is a good sign that Hana is at least not screwing things up. Again, let's look at the executable size:
Here again, the code size did not explode. So at least for moderate usages of Hana (and Fusion for that matter, since they have the same problem), code bloat should not be a major concern. The containers in the charts we just presented contain randomly generated ints, which is cheap to copy around and lends itself well to micro benchmarks. However, what happens when we chain multiple algorithms on a container whose elements are expensive to copy? More generally, the question is: when an algorithm is passed a temporary object, does it seize the opportunity to avoid unnecessary copies? Consider:
To answer this question, we'll look at the chart generated when benchmarking the above code for strings of about 1k characters. However, note that it does not really make sense to benchmark this for standard library algorithms, because they do not return containers.
fusion::reverse is usually lazy, and we're forcing its evaluation for the purpose of benchmarking.As you can see, Hana is faster than Fusion, probably because of a more consistent use of move semantics in the implementation. If we had not provided a temporary container to reverse, no move could have been performed by Hana and both libraries would have performed similarly:
This concludes the section on runtime performance. Hopefully you are now convinced that Hana was built for speed. Performance is important to us: if you ever encounter a scenario where Hana causes bad code to be generated (and the fault is not on the compiler), please open an issue so the problem can be addressed.
Hana provides out-of-the-box integration with some existing libraries. Specifically, this means that you can use some containers from these libraries in Hana's algorithms by simply including the appropriate header making the bridge between Hana and the external component. This can be very useful for porting existing code from e.g. Fusion/MPL to Hana:
However, using external adapters has a couple of pitfalls. For example, after a while using Hana, you might become used to comparing Hana tuples using the normal comparison operators, or doing arithmetic with Hana integral_constants. Of course, nothing guarantees that these operators are defined for external adapters too (and in general they won't be). Hence, you'll have to stick to the functions provided by Hana that implement these operators. For example:
Instead, you should use the following:
But sometimes, it's much worse. Some external components define operators, but they don't necessarily have the same semantics as those from Hana. For example, comparing two std::tuples of different lengths will give an error when using operator==:
On the other hand, comparing Hana tuples of different lengths will just return a false IntegralConstant:
This is because std::tuple defines its own operators, and their semantics are different from that of Hana's operators. The solution is to stick with Hana's named functions instead of using operators when you know you'll have to work with other libraries:
When using external adapters, one should also be careful not to forget including the proper bridge headers. For example, suppose I want to use a Boost.MPL vector with Hana. I include the appropriate bridge header:
Now, however, suppose that I use mpl::size to query the size of the vector and then compare it to some value. I could also use hana::length and everything would be fine, but bear with me for the sake of the example:
The reason why this breaks is that mpl::size returns a MPL IntegralConstant, and Hana has no way of knowing about these unless you include the proper bridge header. Hence, you should do the following instead:
The morale is that when working with external libraries, you have to be a bit careful about what objects you are manipulating. The final pitfall is about implementation limits in external libraries. Many older libraries have limits regarding the maximum size of the heterogeneous containers that can be created with them. For example, one may not create a Fusion list of more than FUSION_MAX_LIST_SIZE elements in it. Obviously, these limits are inherited by Hana and for example, trying to compute the permutations of a fusion::list containing 5 elements (the resulting list would contain 120 elements) will fail in a gruesome way:
Apart from the pitfalls explained in this section, using external adapters should be just as straightforward as using normal Hana containers. Of course, whenever possible, you should try to stick with Hana's containers because they are usually more friendly to work with and are often more optimized.
The goal of this section is to give a high-level overview of Hana's core. This core is based on the notion of tag, which is borrowed from the Boost.Fusion and Boost.MPL libraries but taken much further by Hana. These tags are then used for several purposes, like algorithm customization, documentation grouping, improving error messages and converting containers into other containers. Because of its modular design, Hana can be extended in a ad-hoc manner very easily. In fact, all the functionality of the library is provided through an ad-hoc customization mechanism, which is explained here.
Heterogeneous programming is basically programming with objects having different types. However, it is clear that some families of objects, while having different representations (C++ types), are strongly related. For example, the std::integral_constant<int, n> types are different for each different n, but conceptually they all represent the same thing; a compile-time number. The fact that std::integral_constant<int, 1>{} and std::integral_constant<int, 2>{} have different types is just a side effect of the fact that we're using their type to encode the value of these objects. Indeed, when manipulating a sequence of std::integral_constant<int, ...>s, chances are that you actually think of it as a homogeneous sequence of an imaginary integral_constant type, disregarding the actual types of the objects and pretending they are all just integral_constants with different values.
To reflect this reality, Hana provides tags representing its heterogeneous containers and other compile-time entities. For example, all of Hana's integral_constant<int, ...>s have different types, but they all share the same tag, integral_constant_tag<int>. This allows the programmer to think in terms of that single type instead of trying to think in terms of the actual types of the objects. Concretely, tags are implemented as empty structs. To make them stand out, Hana adopts the convention of naming these tags by adding the _tag suffix.
T can be obtained by using tag_of<T>::type, or equivalently tag_of_t<T>.Tags are an extension to normal C++ types. Indeed, by default, the tag of a type T is T itself, and the core of the library is designed to work in those cases. For example, hana::make expects either a tag or an actual type; if you send it a type T, it will do the logical thing and construct an object of type T with the arguments you pass it. If you pass a tag to it, however, you should specialize make for that tag and provide your own implementation, as explained below. Because tags are an extension to usual types, we end up mostly reasoning in terms of tags instead of usual types, and the documentation sometimes uses the words type, data type and tag interchangeably.
Tag dispatching is a generic programming technique for picking the right implementation of a function depending on the type of the arguments passed to the function. The usual mechanism for overriding a function's behavior is overloading. Unfortunately, this mechanism is not always convenient when dealing with families of related types having different base templates, or when the kind of template parameters is not known (is it a type or a non-type template parameter?). For example, consider trying to overload a function for all Boost.Fusion vectors:
If you know Boost.Fusion, then you probably know that it won't work. This is because Boost.Fusion vectors are not necessarily specializations of the boost::fusion::vector template. Fusion vectors also exist in numbered forms, which are all of different types:
This is an implementation detail required by the lack of variadic templates in C++03 that leaks into the interface. This is unfortunate, but we need a way to work around it. To do so, we use an infrastructure with three distinct components:
tag_of metafunction. Specifically, for any type T, tag_of<T>::type is the tag used to dispatch it.transform or unpack.xxx_impl (for an interface function xxx) with a nested apply static function, as will be shown below.When the public interface function xxx is called, it will get the tag of the argument(s) it wishes to dispatch the call on, and then forward the call to the xxx_impl implementation associated to those tags. For example, let's implement a basic setup for tag dispatching of a function that prints its argument to a stream. First, we define the public interface function and the implementation that can be specialized:
Now, let's define a type that needs tag dispatching to customize the behavior of print. While some C++14 examples exist, they are too complicated to show in this tutorial and we will therefore use a C++03 tuple implemented as several different types to illustrate the technique:
The nested using hana_tag = vector_tag; part is a terse way of controling the result of the tag_of metafunction, and hence the tag of the vectorN type. This is explained in the reference for tag_of. Finally, if you wanted to customize the behavior of the print function for all the vectorN types, you would normally have to write something along the lines of
Now, with tag dispatching, you can rely on the vectorNs all sharing the same tag and specialize only the print_impl struct instead:
One upside is that all vectorNs can now be treated uniformly by the print function, at the cost of some boilerplate when creating the data structure (to specify the tag of each vectorN) and when creating the initial print function (to setup the tag dispatching system with print_impl). There are also other advantages to this technique, like the ability to check for preconditions in the interface function without having to do it in each custom implementation, which would be tedious:
print function, but consider for example a function to get the nth element of a sequence; you might want to make sure that the index is not out-of-bounds.This technique also makes it easier to provide interface functions as function objects instead of normal overloaded functions, because only the interface function itself must go through the trouble of defining a function object. Function objects have several advantages over overloaded functions, like the ability to be used in higher order algorithms or as variables:
As you are probably aware of, being able to implement an algorithm for many types at the same time is tremendously useful (that's precisely the goal of C++ templates!). However, even more useful is the ability to implement an algorithm for many types that satisfy some condition. C++ templates are currently missing this ability to constrain their template parameters, but a language feature called concepts is being rolled out with the goal of addressing this issue.
With something similar in mind, Hana's algorithms support an additional layer of tag-dispatching to what was explained above. This layer allows us to "specialize" an algorithm for all types that satisfy some predicate. For example, let's say we wanted to implement the print function above for all types that represent some kind of sequence. Right now, we wouldn't have an easy way to do this. However, the tag dispatching for Hana's algorithms is set up slightly differently than what was shown above, and we could hence write the following:
where Tag represents some kind of sequence would only need to be a boolean expression representing whether Tag is a sequence. We'll see how such predicates can be created in the next section, but for now let's assume that it just works. Without going into the details of how this tag-dispatching is set up, the above specialization will only be picked up when the predicate is satisfied, and if no better match can be found. Hence, for example, if our vector_tag was to satisfy the predicate, our initial implementation for vector_tag would still be preferred over the hana::when-based specialization, because it represents a better match. In general, any specialization (whether explicit or partial) not using hana::when will be preferred over a specialization using hana::when, which was designed to be as unsurprising as possible from a user point of view. This covers pretty much all there's to say about tag-dispatching in Hana. The next section will explain how we can create C++ concepts for metaprogramming, which could then be used in conjunction with hana::when to achieve a great deal of expressiveness.
The implementation of concepts in Hana is very simple. At its heart, a concept is just a template struct that inherits from a boolean integral_constant representing whether the given type is a model of the concept:
Then, one can test whether a type T is a model of Concept by looking at Concept<T>::value. Simple enough, right? Now, while the way one might implement the check does not have to be anything specific as far as Hana is concerned, the rest of this section will explain how it is usually done in Hana, and how it interacts with tag dispatching. You should then be able to define your own concepts if you so desire, or at least to understand better how Hana works internally.
Usually, a concept defined by Hana will require that any model implements some tag-dispatched functions. For example, the Foldable concept requires that any model defines at least one of hana::unpack and hana::fold_left. Of course, concepts usually also define semantic requirements (called laws) that must be satisfied by their models, but these laws are not (and couldn't be) checked by the concept. But how do we check that some functions are properly implemented? For this, we'll have to slightly modify the way we defined tag-dispatched methods as shown in the previous section. Let's go back to our print example and try to define a Printable concept for those objects that can be printed. Our end goal is to have a template struct such as
To know whether print_impl<...> has been defined, we'll modify print_impl so that it inherits from a special base class when it is not overridden, and we'll simply check whether print_impl<T> inherits from that base class:
Of course, when we specialize print_impl with a custom type, we don't inherit from that special_base_class type:
As you can see, Printable<T> really only checks whether the print_impl<T> struct was specialized by a custom type. In particular, it does not even check whether the nested ::apply function is defined or if it is syntactically valid. It is assumed that if one specializes print_impl for a custom type, the nested ::apply function exists and is correct. If it is not, a compilation error will be triggered when one tries to call print on an object of that type. Concepts in Hana make the same assumptions.
Since this pattern of inheriting from a special base class is quite abundant in Hana, the library provides a dummy type called hana::default_ that can be used in place of special_base_class. Then, instead of using std::is_base_of, one can use hana::is_default, which looks nicer. With this syntactic sugar, the code now becomes:
This is all that there's to know about the interaction between tag-dispatched functions and concepts. However, some concepts in Hana do not rely solely on the definition of specific tag-dispatched functions to determine if a type is a model of the concept. This can happen when a concept merely introduces semantic guarantees through laws and refined concepts, but no additional syntactic requirements. Defining such a concept can be useful for several reasons. First, it sometimes happen that an algorithm can be implemented more efficiently if we can assume some semantic guarantees X or Y, so we might create a concept to enforce those guarantees. Secondly, it is sometimes possible to automatically define the models for several concepts when we have additional semantic guarantees, which saves the user the trouble of defining those models manually. For example, this is the case of the Sequence concept, which basically adds semantic guarantees to Iterable and Foldable, and in turn allows us to define the models for a myriad of concepts ranging from Comparable to Monad.
For these concepts, it is usually necessary to specialize the corresponding template struct in the boost::hana namespace to provide a model for a custom type. Doing so is like providing a seal saying that the semantic guarantees required by the concept are respected by the custom type. The concepts that require being explicitly specialized will document that fact. So that's it! This is all that there's to know about concepts in Hana, which ends this section about the core of Hana.
The library is designed to be modular while keeping the number of headers that must be included to get basic functionality reasonably low. The structure of the library was also intentionally kept simple, because we all love simplicity. What follows is a general overview of the header organization. A list of all the headers provided by the library is also available in the panel on the left (under the Headers label) in case you need more details.
boost/hana.hppboost/hana/XXX, the corresponding header is boost/hana/XXX.hpp.boost/hana/concept/boost/hana/core/make and to.boost/hana/fwd/boost/hana/ directory, except all the headers contain only forward declarations and documentation. For example, to include the hana::tuple container, one can use the boost/hana/tuple.hpp header. However, if one only wants the forward declaration of that container, the boost/hana/fwd/tuple.hpp header can be used instead. Note that forward declarations for headers in boost/hana/ext/ and boost/hana/functional/ are not provided.boost/hana/functional/boost/hana/ext/
This directory contains adapters for external libraries. For a component named xxx in a namespace ns, the external adapter lives in the boost/hana/ext/ns/xxx.hpp header. For example, the external adapter for std::tuple lives in the boost/hana/ext/std/tuple.hpp header, while the external adapter for boost::mpl::vector is in boost/hana/ext/boost/mpl/vector.hpp.
Note that only the strict minimum required to adapt the external components is included in these headers (e.g. a forward declaration). This means that the definition of the external component should still be included when one wants to use it. For example:
boost/hana/experimental/
This directory contains experimental features that may or may not make it into the library at some point, but that were deemed useful enough to be made available to the public. Features in this subdirectory reside in the hana::experimental namespace. Also, do not expect these features to be stable; they may be moved, renamed, changed or removed between releases of the library. These features may also require additional external dependencies; each feature documents the additional dependencies it requires, if any.
Because of the potential additional dependencies, these headers are also not included by the master header of the library.
boost/hana/detail/detail/ is guaranteed to be stable, so you should not use it.You now have everything you need to start using the library. From this point forward, mastering the library is only a matter of understanding how to use the general purpose concepts and containers provided with it, which is best done by looking at the reference documentation. At some point, you will probably also want to create your own concepts and data types that fit your needs better; go ahead, the library was designed to be used that way.
Programming with heterogeneous objects is inherently functional – since it is impossible to modify the type of an object, a new object must be introduced instead, which rules out mutation. Unlike previous metaprogramming libraries whose design was modeled on the STL, Hana uses a functional style of programming which is the source for a good portion of its expressiveness. However, as a result, many concepts presented in the reference will be unfamiliar to C++ programmers without a knowledge of functional programming. The reference attempts to make these concepts approachable by using intuition whenever possible, but bear in mind that the highest rewards are usually the fruit of some effort.
Through the years, I have produced some material about Hana and metaprogramming more generally. You may find some of it useful:
The complete list of talks I've done on Hana and metaprogramming is here. There is also an unofficial translation of Hana's documentation to Chinese available here.
There is a growing number of projects using Hana. It can be useful to look at them to get a sense of how to best use the library. Here's a few of those projects (open an issue if you want your project to be listed here):
This finishes the tutorial part of the documentation. I hope you enjoy using the library, and please consider contributing to make it even better!
– Louis
As for most generic libraries, algorithms in Hana are documented by the concept to which they belong (Foldable, Iterable, Searchable, Sequence, etc...). The different containers are then documented on their own page, and the concepts that they model are documented there. The concepts modeled by some container defines what algorithms can be used with such a container.
More specifically, the structure of the reference (available in the menu to the left) goes as follow:
maybe for optional.After you get to know Hana a bit better, it will probably happen that you just want to find the reference for a precise function, concept or container. If you know the name of what you're looking for, you can use the search box located in the upper right corner of any page of the documentation. My personal experience is that this is by far the quickest way of finding what you want when you already know its name.
As you will see in the reference, several functions provide signatures documented in a semi-formal mathematical language. We are in the process of documenting all functions in this way, but this may take a while. The notation used is the usual mathematical notation for defining functions. Specifically, a function Return f(Arg1, ..., ArgN); can be defined equivalently using mathematical notation as
\[ \mathtt{f} : \mathtt{Arg}_1 \times \dots \times \mathtt{Arg}_n \to \mathtt{Return} \]
However, instead of documenting the actual argument and return types of functions, those signatures are written in terms of argument and return tags. This is done because of the heterogeneous setting, where the actual type of an object is usually pretty meaningless and does not help to reason about what's being returned or taken by a function. For example, instead of documenting the equal function for integral_constants as
\[ \mathtt{equal} : \mathtt{integral\_constant<T, n>} \times \mathtt{integral\_constant<T, m>} \to \mathtt{integral\_constant<bool, n == m>} \]
which is not really helpful (as it really presents nothing but the implementation), it is instead documented using integral_constant_tag, which acts as the "type" of all integral_constants. Note that since equal is part of the Comparable concept, it is not actually documented for hana::integral_constant specifically, but the idea is there:
\[ \mathtt{equal} : \mathtt{integral\_constant\_tag<T>} \times \mathtt{integral\_constant\_tag<T>} \to \mathtt{integral\_constant\_tag<bool>} \]
This clearly conveys the intention that comparing two integral_constants gives back another integral_constant holding a bool. In general, this abstraction of the actual representation of objects makes it possible for us to reason in a high level manner about functions, even though their actual return and argument types are heterogeneous and not helpful. Finally, most functions expect container elements to have some properties. For example, this is the case of the sort algorithm, which obviously requires the container elements to be Orderable. Normally, we would write the signature for the non-predicated version of sort as
\[ \mathtt{sort} : \mathtt{S} \to \mathtt{S} \\ \text{where S is a Sequence} \]
However, this fails to express the requirement that the contents of S are Orderable. To express this, we use the following notation:
\[ \mathtt{sort} : \mathtt{S(T)} \to \mathtt{S(T)} \\ \text{where S is a Sequence and T is Orderable} \]
One way to see this is to pretend that S, the sequence tag, is actually parameterized by the tag of the sequence's elements, T. We're also pretending that the elements all have the same tag T, which is not the case in general. Now, by stating that T must be Orderable, we're expressing the fact that the sequence's elements must be Orderable. This notation is used in different flavors to express different kinds of requirements. For example, the cartesian_product algorithm takes a sequence of sequences and returns the cartesian product of those sequences as a sequence of sequences. Using our notation, this can be conveyed very easily:
\[ \mathtt{cartesian\_product} : \mathtt{S(S(T))} \to \mathtt{S(S(T))} \\ \text{where S is a Sequence} \]
I'd like to thank the following persons and organizations for contributing to Hana in one way or another:
The reference documentation uses a couple of terms that are specific to this library. Also, a simplified implementation of functions is sometimes provided in pseudo-code, the actual implementation sometimes being slightly hard to understand. This section defines terms used in the reference and in the pseudo-code used to describe some functions.
forwarded(x)Means that the object is forwarded optimally. This means that if x is a parameter, it is std::forwarded, and if it is a captured variable, it is moved from whenever the enclosing lambda is an rvalue.
Also note that when x can be moved from, the statement return forwarded(x); in a function with decltype(auto) does not mean that an rvalue reference to x will be returned, which would create a dangling reference. Rather, it means that x is returned by value, the value being constructed with the std::forwarded x.
perfect-captureThis is used in lambdas to signify that the captured variables are initialized using perfect forwarding, as if [x(forwarded(x))...]() { } had been used.
tag-dispatchedThis means that the documented function uses tag dispatching, and hence the exact implementation depends on the model of the concept associated to the function.
implementation-definedThis expresses the fact that the exact implementation of an entity (usually a type) should not be relied upon by users. In particular, this means that one can not assume anything beyond what is written explicitly in the documentation. Usually, the concepts satisfied by an implementation-defined entity will be documented, because one could otherwise do nothing with it. Concretely, assuming too much about an implementation-defined entity will probably not kill you, but it will very probably break your code when you update to a newer version of Hana.
This section documents the rationale for some design choices. It also serves as a FAQ for some (not so) frequently asked questions. If you think something should be added to this list, open a GitHub issue and we'll consider either improving the documentation or adding the question here.
There are several reasons for doing so. First, Hana is a very fundamental library; we are basically reimplementing the core language and the standard library with support for heterogeneous types. When going through the code, one quickly realizes that other libraries are rarely needed, and that almost everything has to be implemented from scratch. Also, since Hana is very fundamental, there is even more incentive for keeping the dependencies minimal, because those dependencies will be handed down to the users. Regarding the minimal reliance on Boost in particular, one big argument for using it is portability. However, as a cutting edge library, Hana only targets very recent compilers. Hence, we can afford to depend on modern constructs and the portability given to us by using Boost would mostly represent dead weight.
Iterator based designs have their own merits, but they are also known to reduce the composability of algorithms. Furthermore, the context of heterogeneous programming brings a lot of points that make iterators much less interesting. For example, incrementing an iterator would have to return a new iterator with a different type, because the type of the new object it is pointing to in the sequence might be different. It also turns out that implementing most algorithms in terms of iterators leads to a worse compile-time performance, simply because the execution model of metaprogramming (using the compiler as an interpreter) is so different from the runtime execution model of C++ (a processor accessing contiguous memory).
First, it gives much more wiggle room for the implementation to perform compile-time and runtime optimizations by using clever representations for specific containers. For example, a tuple containing homogeneous objects of type T could be implemented as an array of type T instead, which is more efficient at compile-time. Secondly, and most importantly, it turns out that knowing the type of a heterogeneous container is not as useful as you would think. Indeed, in the context of heterogeneous programming, the type of the object returned by a computation is usually part of the computation too. In other words, there is no way to know the type of the object returned by an algorithm without actually performing the algorithm. For example, consider the find_if algorithm:
If the predicate is satisfied for some element of the tuple, result will be equal to just(x). Otherwise, result will be equal to nothing. However, the nothingness of the result is known at compile-time, which requires just(x) and nothing to have different types. Now, say you wanted to explicitly write the type of the result:
In order to possess the knowledge of what some_type is, you would need to actually perform the algorithm, because some_type depends on whether the predicate is satisfied or not for some element in the container. In other words, if you were able to write the above, then you would already know what the result of the algorithm is and you would not need to perform the algorithm in the first place. In Boost.Fusion, this problem is addressed by having a separate result_of namespace, which contains a metafunction computing the result type of any algorithm given the types of the arguments passed to it. For example, the above example could be rewritten with Fusion as:
Notice that we're basically doing the computation twice; once in the result_of namespace and once in the normal fusion namespace, which is highly redundant. Before the days of auto and decltype, such techniques were necessary to perform heterogeneous computations. However, since the advent of modern C++, the need for explicit return types in the context of heterogeneous programming is largely obsolete, and knowing the actual type of containers is usually not that useful.
No, it isn't the name of my girlfriend! I just needed a short and good looking name that people would easily remember, and Hana came up. It also came to my attention that Hana means flower in Japanese, and one in Korean. Since Hana is pretty and it unifies type-level and heterogeneous programming under a single paradigm, the name appears to be quite well chosen in retrospect :-).
Since Hana defines a lot of algorithms on tuples, a possible way to go would have been to simply use std::tuple and provide the algorithms only, instead of also providing our own tuple. The reason for providing our own tuple is principally performance. Indeed, all the std::tuple implementations tested so far have a very bad compile-time performance. Also, to get truly amazing compile-time performance, we need to take advantage of the tuple's internal representation in some algorithms, which requires defining our own. Finally, some sugar like operator[] could not be provided if we were using a std::tuple, since that operator must be defined as a member function.
When deciding upon a name X, I try to balance the following things (in no specific order):
X in C++?X in the rest of the programming world?X actually is, regardless of historical reasonsXXX, like name clashes or names reserved by the standardOf course, good naming is and will always be hard. Names are and will always be tainted by the author's own bias. Still, I try to choose names in a reasonable manner.
Unlike naming, which is fairly subjective, the order of the parameters of a function is usually pretty straightforward to determine. Basically, the rule of thumb is "the container goes first". It has always been this way in Fusion and MPL, and this is intuitive for most C++ programmers. Also, in higher-order algorithms, I try to put the function parameter last, so that multi-line lambdas look nice:
There are several different techniques we could have used to provide customization points in the library, and tag-dispatching was chosen. Why? First, I wanted a two-layer dispatching system because this allows functions from the first layer (the ones that are called by users) to actually be function objects, which allows passing them to higher-order algorithms. Using a dispatching system with two layers also allows adding some compile-time sanity checks to the first layer, which improves error messages.
Now, tag-dispatching was chosen over other techniques with two layers for a couple of reasons. First, having to explicitly state how some tag is a model of a concept gives the responsibility of making sure that the semantic requirements of the concept are respected to the user. Secondly, when checking whether a type is a model of some concept, we basically check that some key functions are implemented. In particular, we check that the functions from the minimal complete definition of that concept are implemented. For example, Iterable<T> checks whether the is_empty, at and drop_front functions implemented for T. However, the only way to detect this without tag-dispatching is to basically check whether the following expressions are valid in a SFINAE-able context:
Unfortunately, this requires actually doing the algorithms, which might either trigger a hard compile-time error or hurt compile-time performance. Also, this requires picking an arbitrary index N to call at with: what if the Iterable is empty? With tag dispatching, we can just ask whether at_impl<T>, is_empty_impl<T> and drop_front_impl<T> are defined, and nothing happens until we actually call their nested ::apply function.
It would require either (1) padding the shortest sequences with an arbitrary object, or (2) padding the shortest sequences with an object provided by the user when calling zip_longest. Since there is no requirement that all the zipped sequences have elements of similar types, there is no way to provide a single consistent padding object in all cases. A tuple of padding objects should be provided, but I find it perhaps too complicated to be worth it for now. If you need this functionality, open a GitHub issue.
Since the C++ concept proposal maps concepts to boolean constexpr functions, it would make sense that Hana defines its concepts as such too, instead of as structs with a nested ::value. Indeed, this was the first choice, but it had to be revised because template functions have one limitation that makes them less flexible. Specifically, a template function can't be passed to a higher-order metafunction. In other words, it is not possible to write the following
This sort of code is very useful in some contexts, such as checking whether two types have a common embedding modeling a concept:
With concepts as boolean constexpr functions, this can't be written generically. When concepts are just template structs, however, we can use template template parameters:
In C++, the border between compile-time and runtime is hazy, a fact that is even more true with the introduction of generalized constant expressions in C++14. However, being able to manipulate heterogeneous objects is all about understanding that border and then crossing it at one's will. The goal of this section is to set things straight with constexpr; to understand which problems it can solve and which ones it can't. This section covers advanced concepts about to constant expressions; only readers with a good understanding of constexpr should attempt to read this.
Let's start with a challenging question. Should the following code compile?
The answer is no, and the error given by Clang goes like
The explanation is that inside of f's body, t is not a constant expression, and hence it can't be used as the operand to a static_assert. The reason is that such a function simply can't be generated by the compiler. To understand the issue, consider what should happen when we instantiate the f template with a concrete type:
Clearly, the compiler can't generate f<int>'s code, which should trigger a static_assert if t != 1, because we haven't specified t yet. Even worse, the generated function should work on both constant and non-constant expressions:
Clearly, fptr's code can't be generated, because it would require being able to static_assert on a runtime value, which does not make sense. Furthermore, note that it does not matter whether you make the function constexpr or not; making f constexpr would only state that the result of f is a constant expression whenever its argument is a constant expression, but it still does not give you the ability to know whether you were called with a constant expression from f's body. In other words, what we would want is something like:
In this hypothetical scenario, the compiler would know that t is a constant expression from the body of f, and the static_assert could be made to work. However, constexpr parameters do not exist in the current language, and adding them would bring up very challenging design and implementation issues. The conclusion of this little experiment is that argument passing strips away constexpr-ness. What might be unclear by now are the consequences of this stripping, which are explained next.
The fact that an argument is not a constant expression means that we can't use it as a non-type template parameter, as an array bound, inside a static_assert or anything else that requires a constant expression. In addition, this means that the return type of a function can't depend on the value of an argument which is nothing new if you think about it:
In fact, the return type of a function may only depend on the types of its arguments, and constexpr can't change this fact. This is of utmost importance to us, because we're interested in manipulating heterogeneous objects, which eventually means returning objects with different types depending on the argument of the function. For example, a function might want to return an object of type T in one case and an object of type U in the other; from our analysis, we now know that these "cases" will have to depend on information encoded in the types of the arguments, not in their values.
To preserve constexpr-ness through argument passing, we have to encode the constexpr value into a type, and then pass a not-necessarily-constexpr object of that type to the function. The function, which must be a template, may then access the constexpr value encoded inside that type.
Let me ask a tricky question. Is the following code valid?
The answer is yes, but the reason might not be obvious at first. What happens here is that we have a non-constexpr int n, and a constexpr function f taking a reference to its argument. The reason why most people think it shouldn't work is that n is not constexpr. However, we're not doing anything with n inside of f, so there is no actual reason why this shouldn't work! This is a bit like throwing inside of a constexpr function:
As long as the code path where throw appears is not executed, the result of the invocation can be a constant expression. Similarly, we can do whatever we want inside of f, as long as we don't execute a code path that requires accessing its argument n, which is not a constant expression:
The error given by Clang for the second invocation is
Let's now step the game up a bit and consider a more subtle example. Is the following code valid?
The only difference with our initial scenario is that f now takes its argument by value instead of by reference. However, this makes a world of difference. Indeed, we're now asking the compiler to make a copy of n and to pass this copy to f. However, n is not constexpr, so its value is only known at runtime. How could the compiler make a copy (at compile-time) of a variable whose value is only known at runtime? Of course, it can't. Indeed, the error message given by Clang is pretty explicit about what's happening: