| Boost.Hana 1.7.1 Your standard library for metaprogramming |

User Manual

# Description

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.

# Prerequisites and installation

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:

1. Install Boost
   Hana is included in the Boost distribution starting from Boost 1.61.0, so installing that will give you access to Hana.
2. Install manually
   You can download the code from the official GitHub repository and install the library manually by issuing the following commands from the root of the project (requires CMake):
   mkdir build && cd build
   cmake ..
   cmake --build . --target install
   This will install Hana to the default install-directory for your platform (`/usr/local` for Unix, `C:/Program Files` for Windows). If you want to install Hana in a custom location, you can use
   cmake .. -DCMAKE_INSTALL_PREFIX=/custom/install/prefix

If you just want to contribute to Hana, you can see how to best setup your environment for development in the README.

Note
  Do not mix a standalone installation of Hana (i.e. Hana not installed through Boost) with a full installation of Boost. The Hana provided within Boost and the standalone one may clash, and you won't know which version is used where. This is asking for trouble.

## Note for CMake users

If you use CMake, depending on Hana has never been so easy. When installed manually, 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 manually with CMake, use `find_package(Hana)`, and then link your own targets against the `hana` target. Here is a minimal example of doing this:

cmake_minimum_required(VERSION 3.0)
project(external CXX)
find_package(Hana REQUIRED)
add_executable(external main.cpp)
target_link_libraries(external hana)

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

list(APPEND CMAKE_PREFIX_PATH "${INSTALLATION_PREFIX_FOR_HANA}")
or
cmake ... -DCMAKE_PREFIX_PATH=${INSTALLATION_PREFIX_FOR_HANA}

where `INSTALLATION_PREFIX_FOR_HANA` is the path to the place where Hana was installed.

## Compiler requirements

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 >= 7 | Fully working; tested on each push to GitHub
Xcode >= 11 | Fully working; tested on each push to GitHub
GCC >= 8 | 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):

- Generic lambdas
- Generalized `constexpr`
- Variable templates
- Automatically deduced return type
- All the C++14 type traits from the `<type_traits>` header

Using 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.

# Support

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.

# Introduction

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.

## C++ computational quadrants

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:

auto f = [](int i) -> std::string {
return std::to_string(i * i);
};
std::vector<int> ints{1, 2, 3, 4};
std::vector<std::string> strings;
std::transform(ints.begin(), ints.end(), std::back_inserter(strings), f);
assert((strings == std::vector<std::string>{"1", "4", "9", "16"}));

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:

constexpr int factorial(int n) {
return n == 0 ? 1 : n * factorial(n - 1);
}
template <typename T, std::size_t N, typename F>
constexpr std::array<std::invoke_result_t<F, T>, N>
transform(std::array<T, N> array, F f) {
// ...
}
constexpr std::array<int, 4> ints{{1, 2, 3, 4}};
constexpr std::array<int, 4> facts = transform(ints, factorial);
static_assert(facts == std::array<int, 4>{{1, 2, 6, 24}}, "");
std::array
Adaptation of std::array for Hana.
Definition: array.hpp:64

Note
  For the above code to actually work, `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:

auto to_string = [](auto t) {
std::stringstream ss;
ss << t;
return ss.str();
};
fusion::vector<int, std::string, float> seq{1, "abc", 3.4f};
fusion::vector<std::string, std::string, std::string>
strings = fusion::transform(seq, to_string);
assert(strings == fusion::make_vector("1"s, "abc"s, "3.4"s));
boost::hana::string::to_string
constexpr auto to_string
Equivalent to to<string_tag>; provided for convenience.
Definition: string.hpp:194

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.

template <typename T>
struct add_const_pointer {
using type = T const*;
};
using types = mpl::vector<int, char, float, void>;
using pointers = mpl::transform<types, add_const_pointer<mpl::_1>>::type;
static_assert(mpl::equal<
pointers,
mpl::vector<int const*, char const*, float const*, void const*>
>::value, "");
boost::hana::equal
constexpr auto equal
Returns a Logical representing whether x is equal to y.
Definition: equal.hpp:64
boost::hana::value
constexpr auto value
Return the compile-time value associated to a constant.
Definition: value.hpp:54

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.

## What is this library about?

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.

# Quick start

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:

#include <boost/hana.hpp>
namespace hana = boost::hana;
hana.hpp
Includes all the library components except the adapters for external libraries.
boost::hana
Namespace containing everything in the library.
Definition: accessors.hpp:20

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:

#include <cassert>
#include <iostream>
#include <string>
struct Fish { std::string name; };
struct Cat { std::string name; };
struct Dog { std::string name; };

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`:

auto animals = hana::make_tuple(Fish{"Nemo"}, Cat{"Garfield"}, Dog{"Snoopy"});

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::tuple`s, Hana provides several operations and algorithms to manipulate its own tuples:

using namespace hana::literals;
// Access tuple elements with operator[] instead of std::get.
Cat garfield = animals[1_c];
// Perform high level algorithms on tuples (this is like std::transform)
auto names = hana::transform(animals, [](auto a) {
return a.name;
});
assert(hana::reverse(names) == hana::make_tuple("Snoopy", "Garfield", "Nemo"));
boost::hana::reverse
constexpr auto reverse
Reverse a sequence.
Definition: reverse.hpp:33

Note
  `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:

auto animal_types = hana::make_tuple(hana::type_c<Fish*>, hana::type_c<Cat&>, hana::type_c<Dog>);
auto no_pointers = hana::remove_if(animal_types, [](auto a) {
return hana::traits::is_pointer(a);
});
static_assert(no_pointers == hana::make_tuple(hana::type_c<Cat&>, hana::type_c<Dog>), "");

Note
  `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:

auto has_name = hana::is_valid([](auto&& x) -> decltype((void)x.name) { });
static_assert(has_name(garfield), "");
static_assert(!has_name(1), "");

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:

// 1. Give introspection capabilities to 'Person'
struct Person {
BOOST_HANA_DEFINE_STRUCT(Person,
(std::string, name),
(int, age)
);
};
// 2. Write a generic serializer (bear with std::ostream for the example)
auto serialize = [](std::ostream& os, auto const& object) {
hana::for_each(hana::members(object), [&](auto member) {
os << member << std::endl;
});
};
// 3. Use it
Person john{"John", 30};
serialize(std::cout, john);
// output:
// John
// 30
boost::hana::for_each
constexpr auto for_each
Perform an action on each element of a foldable, discarding the result each time.
Definition: for_each.hpp:39
boost::hana::members
constexpr auto members
Returns a Sequence containing the members of a Struct.
Definition: members.hpp:30

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:

auto serialize = [](std::ostream& os, auto const& object) {
hana::for_each(os, [&](auto member) {
// ^^ oopsie daisy!
os << member << std::endl;
});
};

Now, the punishment:

error: static_assert failed "hana::for_each(xs, f) requires 'xs' to be Foldable"
static_assert(Foldable<S>::value,
^ ~~~~~~~~~~~~~~~~~~
note: in instantiation of function template specialization
'boost::hana::for_each_t::operator()<
std::__1::basic_ostream<char> &, (lambda at [snip])>' requested here
hana::for_each(os, [&](auto member) {
^
note: in instantiation of function template specialization
'main()::(anonymous class)::operator()<Person>' requested here
serialize(std::cout, john);
^
boost::hana::in
constexpr auto in
Return whether the key occurs in the structure.
Definition: contains.hpp:70

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.

## A real world example

In this section our goal will be to implement a kind of `switch` statement able to process `boost::any`s. Given a `boost::any`, the goal is to dispatch to the function associated to the dynamic type of the `any`:

boost::any a = 'x';
std::string r = switch_(a)(
case_<int>([](auto i) { return "int: "s + std::to_string(i); }),
case_<char>([](auto c) { return "char: "s + std::string{c}; }),
default_([] { return "unknown"s; })
);
assert(r == "char: x"s);
boost::hana::any
constexpr auto any
Returns whether any key of the structure is true-valued.
Definition: any.hpp:30

Note
  In the documentation, we will often use the `s` suffix on string literals to create `std::string`s 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:

boost::any a = 'x';
auto r = switch_(a)(
case_<int>([](auto) -> int { return 1; }),
case_<char>([](auto) -> long { return 2l; }),
default_([]() -> long long { return 3ll; })
);
// r is inferred to be a long long
static_assert(std::is_same<decltype(r), long long>{}, "");
assert(r == 2ll);

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:

template <typename T>
auto case_ = [](auto f) {
return hana::make_pair(hana::type_c<T>, f);
};
struct default_t;
auto default_ = case_<default_t>;

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::pair`s), 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:

template <typename Any>
auto switch_(Any& a) {
return [&a](auto ...cases_) {
// ...
};
}

However, since parameter packs are not very flexible, we'll put the cases into a tuple so we can manipulate them:

template <typename Any>
auto switch_(Any& a) {
return [&a](auto ...cases_) {
auto cases = hana::make_tuple(cases_...);
// ...
};
}

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`:

template <typename Any>
auto switch_(Any& a) {
return [&a](auto ...cases_) {
auto cases = hana::make_tuple(cases_...);
auto default_ = hana::find_if(cases, [](auto const& c) {
return hana::first(c) == hana::type_c<default_t>;
});
// ...
};
}
boost::hana::first
constexpr auto first
Returns the first element of a pair.
Definition: first.hpp:33
boost::hana::find_if
constexpr auto find_if
Finds the value associated to the first key satisfying a predicate.
Definition: find_if.hpp:41

`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::pair`s 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!

template <typename Any>
auto switch_(Any& a) {
return [&a](auto ...cases_) {
auto cases = hana::make_tuple(cases_...);
auto default_ = hana::find_if(cases, [](auto const& c) {
return hana::first(c) == hana::type_c<default_t>;
});
static_assert(default_ != hana::nothing,
"switch is missing a default_ case");
// ...
};
}

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:

template <typename Any>
auto switch_(Any& a) {
return [&a](auto ...cases_) {
auto cases = hana::make_tuple(cases_...);
auto default_ = hana::find_if(cases, [](auto const& c) {
return hana::first(c) == hana::type_c<default_t>;
});
static_assert(default_ != hana::nothing,
"switch is missing a default_ case");
auto rest = hana::filter(cases, [](auto const& c) {
return hana::first(c) != hana::type_c<default_t>;
});
// ...
};
}
boost::hana::filter
constexpr auto filter
Filter a monadic structure using a custom predicate.
Definition: filter.hpp:65

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:

template <typename Any>
auto switch_(Any& a) {
return [&a](auto ...cases_) {
auto cases = hana::make_tuple(cases_...);
auto default_ = hana::find_if(cases, [](auto const& c) {
return hana::first(c) == hana::type_c<default_t>;
});
static_assert(default_ != hana::nothing,
"switch is missing a default_ case");
auto rest = hana::filter(cases, [](auto const& c) {
return hana::first(c) != hana::type_c<default_t>;
});
return hana::unpack(rest, [&](auto& ...rest) {
return process(a, a.type(), hana::second(*default_), rest...);
});
};
}
boost::hana::unpack
constexpr auto unpack
Invoke a function with the elements of a Foldable as arguments.
Definition: unpack.hpp:79
boost::hana::second
constexpr auto second
Returns the second element of a pair.
Definition: second.hpp:32

`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:

template <typename Any, typename Default>
auto process(Any&, std::type_index const&, Default& default_) {
return default_();
}
template <typename Any, typename Default, typename Case, typename ...Rest>
auto process(Any& a, std::type_index const& t, Default& default_,
Case& case_, Rest& ...rest)
{
using T = typename decltype(+hana::first(case_))::type;
return t == typeid(T) ? hana::second(case_)(*boost::unsafe_any_cast<T>(&a))
: process(a, t, default_, rest...);
}

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:

#include <boost/hana.hpp>
#include <boost/any.hpp>
#include <cassert>
#include <string>
#include <typeindex>
#include <typeinfo>
#include <utility>
namespace hana = boost::hana;
//! [cases]
template <typename T>
auto case_ = [](auto f) {
return hana::make_pair(hana::type_c<T>, f);
};
struct default_t;
auto default_ = case_<default_t>;
//! [cases]
//! [process]
template <typename Any, typename Default>
auto process(Any&, std::type_index const&, Default& default_) {
return default_();
}
template <typename Any, typename Default, typename Case, typename ...Rest>
auto process(Any& a, std::type_index const& t, Default& default_,
Case& case_, Rest& ...rest)
{
using T = typename decltype(+hana::first(case_))::type;
return t == typeid(T) ? hana::second(case_)(*boost::unsafe_any_cast<T>(&a))
: process(a, t, default_, rest...);
}
//! [process]
//! [switch_]
template <typename Any>
auto switch_(Any& a) {
return [&a](auto ...cases_) {
auto cases = hana::make_tuple(cases_...);
auto default_ = hana::find_if(cases, [](auto const& c) {
return hana::first(c) == hana::type_c<default_t>;
});
static_assert(default_ != hana::nothing,
"switch is missing a default_ case");
auto rest = hana::filter(cases, [](auto const& c) {
return hana::first(c) != hana::type_c<default_t>;
});
return hana::unpack(rest, [&](auto& ...rest) {
return process(a, a.type(), hana::second(*default_), rest...);
});
};
}
//! [switch_]

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.

# Cheatsheet

### Remarks

- Most algorithms work on both types and values (see the section on type computations)
- Algorithms always return their result as a new container; no in-place mutation is ever performed (see the section on algorithms)
- All algorithms are `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 `IntegralConstant`s.
`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.

# Assertions

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.

# Compile-time numbers

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`?

template<class T, T v>
struct integral_constant {
static constexpr T value = v;
typedef T value_type;
typedef integral_constant type;
constexpr operator value_type() const noexcept { return value; }
constexpr value_type operator()() const noexcept { return value; }
};

Note
  If this is totally new to you, you might want to take a look at the documentation for `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:

template <typename N>
using succ = integral_constant<int, N::value + 1>;
using one = integral_constant<int, 1>;
using two = succ<one>;
using three = succ<two>;
// ...
boost::hana::one
constexpr auto one
Identity of the Ring multiplication.
Definition: one.hpp:30

This is the way `integral_constant`s 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:

auto one = integral_constant<int, 1>{};

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:

auto one = integral_constant<int, 1>{};
constexpr int one_constexpr = decltype(one)::value;

But why on earth would we want to consider `integral_constant`s as objects instead of type-level entities? To see why, consider how we could now implement the same successor function as before:

template <typename N>
auto succ(N) {
return integral_constant<int, N::value + 1>{};
}
auto one = integral_constant<int, 1>{};
auto two = succ(one);
auto three = succ(two);
// ...

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.

## Compile-time arithmetic

The MPL defines arithmetic operators that can be used to do compile-time computations with `integral_constant`s. A typical example of such an operation is `plus`, which is implemented roughly as:

template <typename X, typename Y>
struct plus {
using type = integral_constant<
decltype(X::value + Y::value),
X::value + Y::value
>;
};
using three = plus<integral_constant<int, 1>,
integral_constant<int, 2>>::type;
boost::hana::plus
constexpr auto plus
Associative binary operation on a Monoid.
Definition: plus.hpp:47

By viewing `integral_constant`s as objects instead of types, the translation from a metafunction to a function is very straightforward:

template <typename V, V v, typename U, U u>
constexpr auto
operator+(integral_constant<V, v>, integral_constant<U, u>)
{ return integral_constant<decltype(v + u), v + u>{}; }
auto three = integral_constant<int, 1>{} + integral_constant<int, 2>{};

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`:

template <int i>
constexpr integral_constant<int, i> int_c{};
auto three = int_c<1> + int_c<2>;

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:

template <char ...digits>
constexpr auto operator"" _c() {
// parse the digits and return an integral_constant
}
auto three = 1_c + 2_c;

Hana provides its own `integral_constant`s, which define arithmetic operators just like we showed above. Hana also provides variable templates to easily create different kinds of `integral_constant`s: `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:

using namespace hana::literals;
auto three = 1_c + 2_c;

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.

## Example: Euclidean distance

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):

template <typename P1, typename P2>
struct distance {
using xs = typename mpl::minus<typename P1::x,
typename P2::x>::type;
using ys = typename mpl::minus<typename P1::y,
typename P2::y>::type;
using type = typename sqrt<
typename mpl::plus<
typename mpl::multiplies<xs, xs>::type,
typename mpl::multiplies<ys, ys>::type
>::type
>::type;
};
static_assert(mpl::equal_to<
distance<point<mpl::int_<3>, mpl::int_<5>>,
point<mpl::int_<7>, mpl::int_<2>>>::type,
mpl::int_<5>
>::value, "");
boost::hana::minus
constexpr auto minus
Subtract two elements of a group.
Definition: minus.hpp:51

Yeah... Now, let's implement it with the value-level approach presented above:

template <typename P1, typename P2>
constexpr auto distance(P1 p1, P2 p2) {
auto xs = p1.x - p2.x;
auto ys = p1.y - p2.y;
return sqrt(xs*xs + ys*ys);
}
BOOST_HANA_CONSTANT_CHECK(distance(point(3_c, 5_c), point(7_c, 2_c)) == 5_c);
BOOST_HANA_CONSTANT_CHECK
#define BOOST_HANA_CONSTANT_CHECK(...)
Equivalent to BOOST_HANA_CONSTANT_ASSERT, but not influenced by the BOOST_HANA_CONFIG_DISABLE_ASSERTI...
Definition: assert.hpp:239

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!

auto p1 = point(3, 5); // dynamic values now
auto p2 = point(7, 2); //
BOOST_HANA_RUNTIME_CHECK(distance(p1, p2) == 5); // same function works!
BOOST_HANA_RUNTIME_CHECK
#define BOOST_HANA_RUNTIME_CHECK(...)
Equivalent to BOOST_HANA_RUNTIME_ASSERT, but not influenced by the BOOST_HANA_CONFIG_DISABLE_ASSERTIO...
Definition: assert.hpp:209

Without changing any code, we can use our `distance` function on runtime values and everything just works. Now that's DRY.

## Compile-time branching

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):

template <typename T, typename ...Args>
std::enable_if_t<std::is_constructible<T, Args...>::value,
std::unique_ptr<T>> make_unique(Args&&... args) {
return std::unique_ptr<T>(new T(std::forward<Args>(args)...));
}
template <typename T, typename ...Args>
std::enable_if_t<!std::is_constructible<T, Args...>::value,
std::unique_ptr<T>> make_unique(Args&&... args) {
return std::unique_ptr<T>(new T{std::forward<Args>(args)...});
}

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:

template <typename T, typename ...Args>
std::unique_ptr<T> make_unique(Args&&... args) {
if (std::is_constructible<T, Args...>::value)
return std::unique_ptr<T>(new T(std::forward<Args>(args)...));
else
return std::unique_ptr<T>(new T{std::forward<Args>(args)...});
}

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:

auto one_two_three = hana::if_(hana::true_c, 123, "hello");
auto hello = hana::if_(hana::false_c, 123, "hello");
boost::hana::if_
constexpr auto if_
Conditionally return one of two values based on a condition.
Definition: if.hpp:41

Note
  `hana::true_c` and `hana::false_c` are just boolean `IntegralConstant`s 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:

// fails in both cases because both branches have incompatible types
auto one_two_three = hana::true_c ? 123 : "hello";
auto hello = hana::false_c ? 123 : "hello";

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`:

template <typename T, typename ...Args>
std::unique_ptr<T> make_unique(Args&&... args) {
return hana::if_(std::is_constructible<T, Args...>{},
[](auto&& ...x) { return std::unique_ptr<T>(new T(std::forward<Args>(x)...)); },
[](auto&& ...x) { return std::unique_ptr<T>(new T{std::forward<Args>(x)...}); }
)(std::forward<Args>(args)...);
}

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.

Note
  The branches inside the `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

template <typename T, typename ...Args>
std::unique_ptr<T> make_unique(Args&&... args) {
return hana::if_(std::is_constructible<T, Args...>{},
[&] { return std::unique_ptr<T>(new T(std::forward<Args>(args)...)); },
[&] { return std::unique_ptr<T>(new T{std::forward<Args>(args)...}); }
);
}

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_`:

template <typename T, typename ...Args>
std::unique_ptr<T> make_unique(Args&&... args) {
return hana::eval_if(std::is_constructible<T, Args...>{},
[&] { return std::unique_ptr<T>(new T(std::forward<Args>(args)...)); },
[&] { return std::unique_ptr<T>(new T{std::forward<Args>(args)...}); }
);
}
boost::hana::eval_if
constexpr auto eval_if
Conditionally execute one of two branches based on a condition.
Definition: eval_if.hpp:139

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:

template <typename T, typename ...Args>
std::unique_ptr<T> make_unique(Args&&... args) {
return hana::eval_if(std::is_constructible<T, Args...>{},
[&](auto _) { return std::unique_ptr<T>(new T(std::forward<Args>(_(args))...)); },
[&](auto _) { return std::unique_ptr<T>(new T{std::forward<Args>(_(args))...}); }
);
}
boost::hana::_
constexpr unspecified _
Create simple functions representing C++ operators inline.
Definition: placeholder.hpp:70

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 stop here?

Why should we limit ourselves to arithmetic operations and branching? When you start considering `IntegralConstant`s as objects, it becomes sensible to augment their interface with more functions that are generally useful. For example, Hana's `IntegralConstant`s 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:

__attribute__((noinline)) void f() { }
int main() {
hana::int_c<10>.times(f);
}

In the above code, the 10 calls to `f` are expanded at compile-time. In other words, this is equivalent to writing

f(); f(); ... f(); // 10 times

Note
  Always be careful about manually unrolling loops or doing other such optimizations manually. In most cases, your compiler is probably better than you at optimizing. When in doubt, benchmark.

Another nice use of `IntegralConstant`s 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:

auto values = hana::make_tuple(1, 'x', 3.4f);
char x = values[1_c];
boost::hana::map::values
constexpr auto values
Returns a Sequence of the values of the map, in unspecified order.
Definition: map.hpp:199

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

template <typename N>
constexpr decltype(auto) operator[](N const&) {
return std::get<N::value>(*this);
}

This is the end of the section on `IntegralConstant`s. 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.

# Type computations

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.

## Types as objects

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 `IntegralConstant`s, 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 `IntegralConstant`s, let's start by defining a dummy template that could be used to represent a type:

template <typename T>
struct basic_type {
// empty (for now)
};
basic_type<int> Int{};
basic_type<char> Char{};
// ...

Note
  We're using the name `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`:

template <typename T>
constexpr basic_type<T*> add_pointer(basic_type<T> const&)
{ return {}; }
template <typename T>
constexpr auto is_pointer(basic_type<T> const&)
{ return hana::bool_c<false>; }
template <typename T>
constexpr auto is_pointer(basic_type<T*> const&)
{ return hana::bool_c<true>; }

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:

basic_type<int> t{};
auto p = add_pointer(t);
BOOST_HANA_CONSTANT_CHECK(is_pointer(p));

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:

template <typename T>
constexpr basic_type<T> type_c{};
auto t = type_c<int>;
auto p = add_pointer(t);
BOOST_HANA_CONSTANT_CHECK(is_pointer(p));
boost::hana::type::type_c
constexpr type< T > type_c
Creates an object representing the C++ type T.
Definition: type.hpp:128

Note
  This is not exactly how the `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<...>`.

## Benefits of this representation

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:

auto types = hana::make_tuple(hana::type_c<int*>, hana::type_c<char&>, hana::type_c<void>);
auto char_ref = types[1_c];
BOOST_HANA_CONSTANT_CHECK(char_ref == hana::type_c<char&>);

Note
  Writing `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 `int`s, 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:

using types = mpl::vector<int, char&, void*>;
using ts = mpl::copy_if<types, mpl::or_<std::is_pointer<mpl::_1>,
std::is_reference<mpl::_1>>>::type;
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
// placeholder expression
static_assert(mpl::equal<ts, mpl::vector<char&, void*>>::value, "");

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:

auto types = hana::tuple_t<int*, char&, void>;
auto ts = hana::filter(types, [](auto t) {
return is_pointer(t) || is_reference(t);
});
BOOST_HANA_CONSTANT_CHECK(ts == hana::tuple_t<int*, char&>);

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:

// types (MPL)
using types = mpl::vector<int*, char&, void>;
using ts = mpl::copy_if<types, mpl::or_<std::is_pointer<mpl::_1>,
std::is_reference<mpl::_1>>>::type;
// values (Fusion)
auto values = fusion::make_vector(1, 'c', nullptr, 3.5);
auto vs = fusion::filter_if<std::is_integral<mpl::_1>>(values);

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:

// types
auto types = hana::tuple_t<int*, char&, void>;
auto ts = hana::filter(types, [](auto t) {
return is_pointer(t) || is_reference(t);
});
// values
auto values = hana::make_tuple(1, 'c', nullptr, 3.5);
auto vs = hana::filter(values, [](auto const& t) {
return is_integral(hana::typeid_(t));
});

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:

auto map = fusion::make_map<char, int, long, float, double, void>(
"char", "int", "long", "float", "double", "void"
);
std::string Int = fusion::at_key<int>(map);
BOOST_HANA_RUNTIME_CHECK(Int == "int");

However, with a unified syntax for types and values, the same thing becomes much clearer:

auto map = hana::make_map(
hana::make_pair(hana::type_c<char>, "char"),
hana::make_pair(hana::type_c<int>, "int"),
hana::make_pair(hana::type_c<long>, "long"),
hana::make_pair(hana::type_c<float>, "float"),
hana::make_pair(hana::type_c<double>, "double")
);
std::string Int = map[hana::type_c<int>];
BOOST_HANA_RUNTIME_CHECK(Int == "int");

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.

## Working with this representation

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?

auto t = add_pointer(hana::type_c<int>); // could be a complex type computation
using T = the-type-represented-by-t;
T var = ...;

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

template <typename T>
struct basic_type {
using type = T;
};

Note
  This is equivalent to making `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:

auto t = add_pointer(hana::type_c<int>);
using T = decltype(t)::type; // fetches basic_type<T>::type
T var = ...;

In general, doing type-level metaprogramming with Hana is a three step process:

1. Represent types as objects by wrapping them with `hana::type_c<...>`
2. Perform type transformations with value syntax
3. Unwrap the result with `decltype(...)::type`

Now, 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.

auto t = hana::type_c<T>;
auto result = huge_type_computation(t);
using Result = decltype(result)::type;

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:

auto t = hana::type_c<T>;
auto result = type_computation(t);
BOOST_HANA_CONSTANT_CHECK(is_pointer(result)); // third step skipped

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:

auto types = hana::tuple_t<int*, char&, void>; // first step skipped
auto pointers = hana::transform(types, [](auto t) {
return add_pointer(t);
});

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:

template <typename ...T>
struct smallest
: mpl::deref<
typename mpl::min_element<
mpl::vector<T...>,
mpl::less<mpl::sizeof_<mpl::_1>, mpl::sizeof_<mpl::_2>>
>::type
>
{ };
template <typename ...T>
using smallest_t = typename smallest<T...>::type;
static_assert(std::is_same<
smallest_t<char, long, long double>,
char
>::value, "");

The result is quite readable (for anyone familiar with the MPL). Let's now implement the same thing using Hana:

template <typename ...T>
auto smallest = hana::minimum(hana::make_tuple(hana::type_c<T>...), [](auto t, auto u) {
return hana::sizeof_(t) < hana::sizeof_(u);
});
template <typename ...T>
using smallest_t = typename decltype(smallest<T...>)::type;
static_assert(std::is_same<
smallest_t<char, long, long double>, char
>::value, "");

As you can witness, the syntactic noise of the 3-step process is almost completely hidden by the rest of the computation.

## The generic lifting process

The first type-level computation that we introduced in the form of a function looked like:

template <typename T>
constexpr auto add_pointer(hana::basic_type<T> const&) {
return hana::type_c<T*>;
}

While it looks more complicated, we could also write it as:

template <typename T>
constexpr auto add_pointer(hana::basic_type<T> const&) {
return hana::type_c<typename std::add_pointer<T>::type>;
}

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:

template <typename T>
constexpr auto add_const(hana::basic_type<T> const&)
{ return hana::type_c<typename std::add_const<T>::type>; }
template <typename T>
constexpr auto add_volatile(hana::basic_type<T> const&)
{ return hana::type_c<typename std::add_volatile<T>::type>; }
template <typename T>
constexpr auto add_lvalue_reference(hana::basic_type<T> const&)
{ return hana::type_c<typename std::add_lvalue_reference<T>::type>; }
// etc...

This mechanical transformation is easy to abstract into a generic lifter that can handle any MPL Metafunction as follows:

template <template <typename> class F, typename T>
constexpr auto metafunction(hana::basic_type<T> const&)
{ return hana::type_c<typename F<T>::type>; }
auto t = hana::type_c<int>;
BOOST_HANA_CONSTANT_CHECK(metafunction<std::add_pointer>(t) == hana::type_c<int*>);
boost::hana::metafunction
constexpr auto metafunction
Lift a MPL-style metafunction to a Metafunction.
Definition: type.hpp:437

More generally, we'll want to allow metafunctions with any number of arguments, which brings us to the following less naive implementation:

template <template <typename ...> class F, typename ...T>
constexpr auto metafunction(hana::basic_type<T> const& ...)
{ return hana::type_c<typename F<T...>::type>; }
BOOST_HANA_CONSTANT_CHECK(
metafunction<std::common_type>(hana::type_c<int>, hana::type_c<long>) == hana::type_c<long>
);

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:

template <template <typename ...> class F, typename ...T>
constexpr auto template_(hana::basic_type<T> const& ...)
{ return hana::type_c<F<T...>>; }
BOOST_HANA_CONSTANT_CHECK(
template_<std::vector>(hana::type_c<int>) == hana::type_c<std::vector<int>>
);
boost::hana::template_
constexpr auto template_
Lift a template to a Metafunction.
Definition: type.hpp:406

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:

template <typename T>
struct legacy {
using type = ...; // something you really don't want to mess with
};
auto types = hana::make_tuple(...);
auto use = hana::transform(types, hana::metafunction<legacy>);

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:

auto extent = [](auto t, auto n) {
return std::extent<typename decltype(t)::type, hana::value(n)>{};
};
BOOST_HANA_CONSTANT_CHECK(extent(hana::type_c<char>, hana::int_c<1>) == hana::size_c<0>);
BOOST_HANA_CONSTANT_CHECK(extent(hana::type_c<char[1][2]>, hana::int_c<1>) == hana::size_c<2>);

Note
  Do not forget to include the bridge header for `std::integral_constant`s (`<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:

BOOST_HANA_CONSTANT_CHECK(hana::traits::add_pointer(hana::type_c<int>) == hana::type_c<int*>);
BOOST_HANA_CONSTANT_CHECK(hana::traits::common_type(hana::type_c<int>, hana::type_c<long>) == hana::type_c<long>);
BOOST_HANA_CONSTANT_CHECK(hana::traits::is_integral(hana::type_c<int>));
auto types = hana::tuple_t<int, char, long>;
BOOST_HANA_CONSTANT_CHECK(hana::all_of(types, hana::traits::is_integral));
boost::hana::all_of
constexpr auto all_of
Returns whether all the keys of the structure satisfy the predicate.
Definition: all_of.hpp:38

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.

Note
  Curious or skeptical readers should consider checking the minimal reimplementation of the MPL presented in the appendices.

# Introspection

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`?

struct Person {
std::string name;
int age;
};
Person john{"John", 30};
for (auto& member : john)
std::cout << member.name << ": " << member.value << std::endl;
// name: John
// age: 30

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.

## Checking expression validity

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:

template <typename T>
std::string optionalToString(T const& obj) {
if (obj.toString() is a valid expression)
return obj.toString();
else
return "toString not defined";
}

Note
  While most use cases for this technique will be addressed by concepts lite in future revisions of the standard, there will still be cases where a quick and dirty check is more convenient than creating a full blown concept.

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:

template <typename T, typename = void>
struct has_toString
: std::false_type
{ };
template <typename T>
struct has_toString<T, decltype((void)std::declval<T>().toString())>
: std::true_type
{ };

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

template <typename T>
std::string optionalToString(T const& obj) {
if (has_toString<T>::value)
return obj.toString();
else
return "toString not defined";
}

Note
  Of course, this implementation won't actually work because both branches of the `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:

auto has_toString = hana::is_valid([](auto&& obj) -> decltype(obj.toString()) { });

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`:

template <typename T>
std::string optionalToString(T const& obj) {
if (has_toString(obj))
return obj.toString();
else
return "toString not defined";
}

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`:

template <typename T>
auto optionalToString(T const& obj)
-> std::enable_if_t<decltype(has_toString(obj))::value, std::string>
{ return obj.toString(); }
template <typename T>
auto optionalToString(T const& obj)
-> std::enable_if_t<decltype(!has_toString(obj))::value, std::string>
{ return "toString not defined"; }

Note
  We're using the fact that `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_`:

template <typename T>
std::string optionalToString(T const& obj) {
return hana::if_(has_toString(obj),
[](auto& x) { return x.toString(); },
[](auto& x) { return "toString not defined"; }
)(obj);
}

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.

### Non-static members

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:

auto has_member = hana::is_valid([](auto&& x) -> decltype((void)x.member) { });
struct Foo { int member[4]; };
struct Bar { };
BOOST_HANA_CONSTANT_CHECK(has_member(Foo{}));
BOOST_HANA_CONSTANT_CHECK(!has_member(Bar{}));

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:

auto has_member = hana::is_valid([](auto t) -> decltype(
(void)hana::traits::declval(t).member
) { });
struct Foo { int member[4]; };
struct Bar { };
BOOST_HANA_CONSTANT_CHECK(has_member(hana::type_c<Foo>));
BOOST_HANA_CONSTANT_CHECK(!has_member(hana::type_c<Bar>));

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.

### Static members

Checking for a static member is easy, and it is provided for completeness:

auto has_member = hana::is_valid([](auto t) -> decltype(
(void)decltype(t)::type::member
) { });
struct Foo { static int member[4]; };
struct Bar { };
BOOST_HANA_CONSTANT_CHECK(has_member(hana::type_c<Foo>));
BOOST_HANA_CONSTANT_CHECK(!has_member(hana::type_c<Bar>));

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.

### Nested type names

Checking for a nested type name is not hard, but it is slightly more convoluted than the previous cases:

auto has_member = hana::is_valid([](auto t) -> hana::type<
typename decltype(t)::type::member
//^^^^^^^^ needed because of the dependent context
> { });
struct Foo { struct member; /* not defined! */ };
struct Bar { };
BOOST_HANA_CONSTANT_CHECK(has_member(hana::type_c<Foo>));
BOOST_HANA_CONSTANT_CHECK(!has_member(hana::type_c<Bar>));

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.

### Nested templates

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:

auto has_member = hana::is_valid([](auto t) -> decltype(hana::template_<
decltype(t)::type::template member
// ^^^^^^^^ needed because of the dependent context
>) { });
struct Foo { template <typename ...> struct member; };
struct Bar { };
BOOST_HANA_CONSTANT_CHECK(has_member(hana::type_c<Foo>));
BOOST_HANA_CONSTANT_CHECK(!has_member(hana::type_c<Bar>));

### Template specializations

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:

template <typename T, typename U>
struct Foo;
template <typename T>
struct Bar;
auto is_binary_template = hana::is_valid([](auto trait) -> decltype(
trait(hana::type_c<void>, hana::type_c<void>)
) { });
BOOST_HANA_CONSTANT_CHECK(is_binary_template(hana::template_<Foo>));
BOOST_HANA_CONSTANT_CHECK(!is_binary_template(hana::template_<Bar>));
boost::hana::trait
constexpr auto trait
Alias to integral(metafunction<F>), provided for convenience.
Definition: type.hpp:539

Note
  Doing this will not cause the template to be instantiated. Hence, it will only check whether the given template can be mentioned with the provided template arguments, not whether the instantiation of the template with those arguments is valid. Generally speaking, there is no way to check that programmatically.

## Taking control of SFINAE

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:

template <typename T>
auto f(T x) {
if (some expression involving x is well-formed)
return something involving x;
else
return something else;
}

To encapsulate this pattern, Hana provides the `sfinae` function, which allows executing an expression, but only if it is well-formed:

auto maybe_add = hana::sfinae([](auto x, auto y) -> decltype(x + y) {
return x + y;
});
maybe_add(1, 2); // hana::just(3)
std::vector<int> v;
maybe_add(v, "foobar"); // hana::nothing

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:

auto maybe_add = [](auto x, auto y) {
if (x + y is well formed)
return std::optional<decltype(x + y)>{x + y};
else
return std::optional<???>{};
};

It turns out that we can take advantage of `sfinae` and `optional` to implement the `optionalToString` function as follows:

template <typename T>
std::string optionalToString(T const& obj) {
auto maybe_toString = hana::sfinae([](auto&& x) -> decltype(x.toString()) {
return x.toString();
});
return maybe_toString(obj).value_or("toString not defined");
}

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.

## Introspecting user-defined types

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:

struct Person {
BOOST_HANA_DEFINE_STRUCT(Person,
(std::string, name),
(int, age)
);
};

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 `struct`s 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:

Person john{"John", 30};
hana::for_each(john, [](auto pair) {
std::cout << hana::to<char const*>(hana::first(pair)) << ": "
<< hana::second(pair) << std::endl;
});
// name: John
// age: 30

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 `cout`ed. 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:

hana::for_each(john, hana::fuse([](auto name, auto member) {
std::cout << hana::to<char const*>(name) << ": " << member << std::endl;
}));
boost::hana::fuse
constexpr auto fuse
Transform a function taking multiple arguments into a function that can be called with a compile-time...
Definition: fuse.hpp:40

Now, it looks much cleaner. As we just mentioned, `Struct`s 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:

std::string name = hana::at_key(john, "name"_s);
BOOST_HANA_RUNTIME_CHECK(name == "John");
int age = hana::at_key(john, "age"_s);
BOOST_HANA_RUNTIME_CHECK(age == 30);
boost::hana::at_key
constexpr auto at_key
Returns the value associated to the given key in a structure, or fail.
Definition: at_key.hpp:51

Note
  The `_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.

auto map = hana::insert(hana::to<hana::map_tag>(john), hana::make_pair("last name"_s, "Doe"s));
std::string name = map["name"_s];
BOOST_HANA_RUNTIME_CHECK(name == "John");
std::string last_name = map["last name"_s];
BOOST_HANA_RUNTIME_CHECK(last_name == "Doe");
int age = map["age"_s];
BOOST_HANA_RUNTIME_CHECK(age == 30);
boost::hana::insert
constexpr insert_t insert
Insert a value at a given index in a sequence.
Definition: insert.hpp:29

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:

namespace not_my_namespace {
struct Person {
std::string name;
int age;
};
}
BOOST_HANA_ADAPT_STRUCT(not_my_namespace::Person, name, age);

Note
  The `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:

namespace also_not_my_namespace {
struct Person {
std::string get_name();
int get_age();
};
}
BOOST_HANA_ADAPT_ADT(also_not_my_namespace::Person,
(name, [](auto const& p) { return p.get_name(); }),
(age, [](auto const& p) { return p.get_age(); })
);

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 `struct`s can be adapted without using macros. This advanced interface for defining `Struct`s 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.

## Example: generating JSON

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:

struct Car {
BOOST_HANA_DEFINE_STRUCT(Car,
(std::string, brand),
(std::string, model)
);
};
struct Person {
BOOST_HANA_DEFINE_STRUCT(Person,
(std::string, name),
(std::string, last_name),
(int, age)
);
};
Car bmw{"BMW", "Z3"}, audi{"Audi", "A4"};
Person john{"John", "Doe", 30};
auto tuple = hana::make_tuple(john, audi, bmw);
std::cout << to_json(tuple) << std::endl;

And the output, after passing it through a JSON pretty-printer, should look like

[
{
"name": "John",
"last_name": "Doe",
"age": 30
},
{
"brand": "Audi",
"model": "A4"
},
{
"brand": "BMW",
"model": "Z3"
}
]

First, let's define a couple of utility functions to make string manipulation easier:

template <typename Xs>
std::string join(Xs&& xs, std::string sep) {
return hana::fold(hana::intersperse(std::forward<Xs>(xs), sep), "", hana::_ + hana::_);
}
std::string quote(std::string s) { return "\"" + s + "\""; }
template <typename T>
auto to_json(T const& x) -> decltype(std::to_string(x)) {
return std::to_string(x);
}
std::string to_json(char c) { return quote({c}); }
std::string to_json(std::string s) { return quote(s); }
boost::hana::fold
constexpr auto fold
Equivalent to fold_left; provided for convenience.
Definition: fold.hpp:35
boost::hana::intersperse
constexpr auto intersperse
Insert a value between each pair of elements in a finite sequence.
Definition: intersperse.hpp:41

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::string`s (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`:

template <typename Xs>
std::enable_if_t<hana::Sequence<Xs>::value,
std::string> to_json(Xs const& xs) {
auto json = hana::transform(xs, [](auto const& x) {
return to_json(x);
});
return "[" + join(std::move(json), ", ") + "]";
}

First, we use the `transform` algorithm to turn our sequence of objects into a sequence of `std::string`s 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:

template <typename T>
std::enable_if_t<hana::Struct<T>::value,
std::string> to_json(T const& x) {
auto json = hana::transform(hana::keys(x), [&](auto name) {
auto const& member = hana::at_key(x, name);
return quote(hana::to<char const*>(name)) + " : " + to_json(member);
});
return "{" + join(std::move(json), ", ") + "}";
}
boost::hana::keys
constexpr keys_t keys
Returns a Sequence containing the name of the members of the data structure.
Definition: keys.hpp:29

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!

# Generalities on containers

This section explains several important notions about Hana's containers: how to create them, the lifetime of their elements and other concerns.

## Container creation

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:

auto xs = hana::make<hana::tuple_tag>(1, 2.2, 'a', "bcde"s);

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>`:

constexpr auto r = hana::make<hana::range_tag>(hana::int_c<3>, hana::int_c<10>);
static_assert(r == hana::make_range(hana::int_c<3>, hana::int_c<10>), "");

> These types with a trailing `_tag` are 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`:

hana::tuple<int, double, char, std::string> xs{1, 2.2, 'a', "bcde"s};

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:

hana::range<???> xs{hana::int_c<3>, hana::int_c<10>};

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.

## Container types

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?

auto xs = hana::make_tuple(1, '2', "345");
auto ints = hana::make_range(hana::int_c<0>, hana::int_c<100>);
// what can we say about the types of `xs` and `ints`?

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:

hana::tuple<int, char, char const*> xs = hana::make_tuple(1, '2', "345");
auto ints = hana::make_range(hana::int_c<0>, hana::int_c<100>);
// can't specify the type of ints, however

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.

### Overloading on container types

While necessary, leaving the type of some containers unspecified makes some things very difficult to achieve, like overloading functions on heterogeneous containers:

template <typename T>
void f(std::vector<T> xs) {
// ...
}
template <typename ...???>
void f(unspecified-range-type<???> r) {
// ...
}

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

template <typename T>
void f(std::vector<T> xs) {
// ...
}
template <typename R, typename = std::enable_if_t<hana::is_a<hana::range_tag, R>()>>
void f(R r) {
// ...
}

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.

## Container elements

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.

std::string hello = "Hello";
std::vector<char> world = {'W', 'o', 'r', 'l', 'd'};
// hello is copied, world is moved-in
auto xs = hana::make_tuple(hello, std::move(world));
// s is a reference to the copy of hello inside xs.
// It becomes a dangling reference as soon as xs is destroyed.
std::string& s = xs[0_c];

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:

std::vector<int> ints = { /* huge vector of ints */ };
std::vector<std::string> strings = { /* huge vector of strings */ };
auto map = hana::make_map(
hana::make_pair(hana::type_c<int>, std::ref(ints)),
hana::make_pair(hana::type_c<std::string>, std::ref(strings))
);
auto& v = map[hana::type_c<int>].get();
BOOST_HANA_RUNTIME_CHECK(&v == &ints);

# Generalities on algorithms

Much like the previous section introduced general but important notions about heterogeneous containers, this section introduces general notions about heterogeneous algorithms.

## By-value semantics

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:

auto to_str = [](auto const& x) {
std::stringstream ss;
ss << x;
return ss.str();
};
auto xs = hana::make_tuple(1, 2.2, 'a', "bcde");
BOOST_HANA_RUNTIME_CHECK(
hana::reverse(hana::transform(xs, to_str)) == hana::make_tuple("bcde", "a", "2.2", "1")
);

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`:

hana::reverse(
hana::transform(xs, to_str) // <-- copy into reverse(...) here?
);

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`:

hana::reverse(
hana::transform(xs, to_str) // <-- nope, move from the temporary instead!
);

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.

## (Non-)Laziness

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:

auto perms = hana::permutations(hana::make_tuple(1, 2, 3, 4, 5, 6, 7, 8, 9, 10));
// perms has 3 628 800 elements, and your compiler just crashed
boost::hana::permutations
constexpr auto permutations
Return a sequence of all the permutations of the given sequence.
Definition: permutations.hpp:34

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.

## What is generated?

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:

auto xs = hana::make_tuple(0, 1, 2, 3);
hana::for_each(xs, f);

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:

for (int i = 0; i < xs.size(); ++i) {
f(xs[i]);
}

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:

f(xs[0_c]);
f(xs[1_c]);
f(xs[2_c]);
f(xs[3_c]);

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:

for (??? i = 0_c; i < xs.size(); ++i) {
f(xs[i]);
}

## Side effects and purity

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:

auto r = hana::any_of(hana::make_tuple("hello"s, 1.2, 3), [](auto x) {
return std::is_integral<decltype(x)>{};
});
BOOST_HANA_CONSTANT_CHECK(r);
boost::hana::any_of
constexpr auto any_of
Returns whether any key of the structure satisfies the predicate.
Definition: any_of.hpp:37

Note
  For this to work, the external adapters for `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:

auto xs = hana::make_tuple("hello"s, 1.2, 3);
auto pred = [](auto x) { return std::is_integral<decltype(x)>{}; };
auto r = hana::bool_c<
pred(xs[0_c]) ? true :
pred(xs[1_c]) ? true :
pred(xs[2_c]) ? true :
false
>;
BOOST_HANA_CONSTANT_CHECK(r);

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:

auto xs = hana::make_tuple("hello"s, 1.2, 3);
auto pred = [](auto x) { return std::is_integral<decltype(x)>{}; };
auto r = hana::bool_c<
decltype(pred(xs[0_c]))::value ? true :
decltype(pred(xs[1_c]))::value ? true :
decltype(pred(xs[2_c]))::value ? true :
false
>;
BOOST_HANA_CONSTANT_CHECK(r);

Note
  As you will be able to deduce from the next section on cross-phase computations, the implementation of `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:

hana::transform(hana::make_tuple(x1, ..., xn), f) == hana::make_tuple(f(x1), ..., f(xn))

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.

## Cross-phase algorithms

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:

struct Fish { std::string name; };
struct Cat { std::string name; };
struct Dog { std::string name; };
auto animals = hana::make_tuple(Fish{"Nemo"}, Cat{"Garfield"}, Dog{"Snoopy"});
// ^^^^^^^ not a compile-time value
BOOST_HANA_CONSTANT_CHECK(hana::length(animals) == hana::size_c<3>);
// ^^^^^^^^^^^^^^^^^^^^^ assertion done at compile-time
boost::hana::length
constexpr auto length
Return the number of elements in a foldable structure.
Definition: length.hpp:34

Obviously, the tuple can't be made `constexpr`, since it contains runtime `std::string`s. 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`:

std::tuple<int, char, std::string> xs{1, '2', std::string{"345"}};
static_assert(std::tuple_size<decltype(xs)>::value == 3u, "");
std::tuple
Adapter for std::tuples.
Definition: tuple.hpp:49

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:

BOOST_HANA_CONSTANT_CHECK(!hana::is_empty(animals));
// ^^^^^^^^^^^^^^^^^^^^^^^ assertion done at compile-time
boost::hana::is_empty
constexpr auto is_empty
Returns whether the iterable is empty.
Definition: is_empty.hpp:33

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:

bool any_garfield = hana::any_of(animals, [](auto animal) {
return animal.name == "Garfield"s;
});
BOOST_HANA_RUNTIME_CHECK(any_garfield);

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::string`s. Since `std::string`s 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:

auto any_cat = hana::any_of(animals, [](auto x) {
return std::is_same<decltype(x), Cat>{};
});
BOOST_HANA_CONSTANT_CHECK(any_cat);

Note
  For this to work, the external adapters for `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-time`ness 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!):

hana::integral_constant<bool, true> any_cat = hana::any_of(animals, [](auto x) {
return std::is_same<decltype(x), Cat>{};
});
BOOST_HANA_CONSTANT_CHECK(any_cat);

Ok, so some algorithms are able to return compile-time values when their input satisfies some constraints with respect to `compile-time`ness. However, other algorithms are more restrictive and they require their inputs to satisfy some constraints regarding `compile-time`ness, 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:

auto animals = hana::make_tuple(Fish{"Nemo"}, Cat{"Garfield"}, Dog{"Snoopy"});
auto no_garfield = hana::filter(animals, [](auto animal) {
return animal.name != "Garfield"s;
});

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:

auto mammals = hana::filter(animals, [](auto animal) {
return hana::type_c<decltype(animal)> != hana::type_c<Fish>;
});

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`.

Warning
  Hana's algorithms are `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, we require support for C++17 inline variables in order to avoid ODR violations (by means of the same object being defined twice in different translation units). When compiling in C++14 mode, where inline variables are not available, each translation unit will see a different algorithm object, so the address of an algorithm function object is not guaranteed to be unique across translation units. This is technically an ODR violation, but it shouldn't bite you unless you rely on the addresses being the same. So, in short, do not rely on the uniqueness of the address of any global object provided by Hana if you are compiling in C++14 mode.

# Performance considerations

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.

Note
  The benchmarks presented in this section are updated automatically when we push to the repository. If you notice results that do not withstand the claims made here, open a GitHub issue; it could be a performance regression.

Warning
  As of writing this, not all of Hana's containers are optimized. Implementing Hana was a big enough challenge that containers were initially written naively and are now in the process of being rigorously optimized. In particular, the associative containers (`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.

## Compile-time performance

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.

Note
  While Hana has better compile-times than pre-C++11 metaprogramming libraries, modern libraries supporting only type-level computations (such as Brigand) can provide better compile-times, at the cost of generality. Indeed, Hana's ability to manipulate runtime values comes at a compile-time cost, no matter how hard we try to mitigate it. If you want to use Hana for intensive type-level computations, you should benchmark and see whether it suits you.

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.

Note
  You can zoom on the chart by selecting an area to zoom into. Also, you can hide a series of points by clicking on it in the legend on the right.

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.

Note
  We are currently considering adding lazy views to Hana. If this feature is important to you, please let us know by commenting this issue.

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.

## Runtime performance

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 `IntegralConstant`s, 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!

Note
  Like for compile-time performance, we're forcing the evaluation of some Fusion algorithms that are normally lazy. Again, depending on the complexity of the computation, a lazy algorithm may cause substantially different code to be generated or a different design to be used, for better or worse. Keep this in mind when you look at these runtime benchmarks. If performance is absolutely critical to your application, you should profile before and after switching from Fusion to Hana. And let us know if Hana performs worse; we'll fix 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:

Note
  Keep in mind that `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 `int`s, 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:

auto xs = hana::make_tuple("some"s, "huge"s, "string"s);
// No copy of xs's elements should be made: they should only be moved around.
auto ys = hana::reverse(std::move(xs));

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.

Note
  Keep in mind that `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.

# Integration with external libraries

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:

// In the old code, this used to receive a Fusion sequence.
// Now, it can be either a Hana sequence or a Fusion sequence.
template <typename Sequence>
void f(Sequence const& seq) {
hana::for_each(seq, [](auto const& element) {
std::cout << element << std::endl;
});
}

Note
  - At this time, only adapters to use data types from other libraries inside Hana are provided; adapters for the other way around (using Hana containers inside other libraries) are not provided.
  - The Fusion and MPL adapters are only guaranteed to work on the version of Boost matching the version of Hana being used.

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_constant`s. 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:

auto r = std::ratio<3, 4>{} + std::ratio<4, 5>{}; // error, the operator is not defined!
std::ratio
Adaptation of std::ratio for Hana.
Definition: ratio.hpp:58

Instead, you should use the following:

#include <boost/hana/ext/std/ratio.hpp>
#include <boost/hana/plus.hpp>
#include <ratio>
namespace hana = boost::hana;
auto r = hana::plus(std::ratio<3, 4>{}, std::ratio<4, 5>{});
plus.hpp
Defines boost::hana::plus.
ratio.hpp
Adapts std::ratio for use with Hana.

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::tuple`s of different lengths will give an error when using `operator==`:

std::make_tuple(1, 2, 3) == std::make_tuple(1, 2); // compiler error

On the other hand, comparing Hana tuples of different lengths will just return a false `IntegralConstant`:

hana::make_tuple(1, 2, 3) == hana::make_tuple(1, 2); // hana::false_c

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:

hana::equal(std::make_tuple(1, 2, 3), std::make_tuple(1, 2)); // hana::false_c

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:

#include <boost/hana/ext/boost/mpl/vector.hpp> // bridge header
using Vector = mpl::vector<int, char, float>;
static_assert(hana::front(Vector{}) == hana::type_c<int>, "");
vector.hpp
Adapts boost::mpl::vector for use with Hana.
boost::hana::front
constexpr auto front
Returns the first element of a non-empty iterable.
Definition: front.hpp:32

Note
  The exact layout of these bridge headers is documented in the section about Header organization.

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:

using Size = mpl::size<Vector>::type;
static_assert(hana::equal(Size{}, hana::int_c<3>), ""); // breaks!

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:

#include <boost/hana/ext/boost/mpl/integral_c.hpp>
using Size = mpl::size<Vector>::type;
static_assert(hana::equal(Size{}, hana::int_c<3>), "");
integral_c.hpp
Adapts Boost.MPL IntegralConstants for use with Hana.

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:

auto list = fusion::make_list(1, 2, 3, 4, 5);
auto oh_jeez = hana::permutations(list); // probably won't make it

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.

# Hana's core

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.

## Tags

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_constant`s 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 `struct`s. To make them stand out, Hana adopts the convention of naming these tags by adding the `_tag` suffix.

Note
  The tag of an object of type `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

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:

template <typename ...T>
void function(boost::fusion::vector<T...> v) {
// whatever
}
boost::fusion::vector
Adapter for Boost.Fusion vectors.
Definition: vector.hpp:48

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:

boost::fusion::vector1<T>
boost::fusion::vector2<T, U>
boost::fusion::vector3<T, U, V>
...

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:

1. A metafunction associating a single tag to every type in a family of related types. In Hana, this tag can be accessed using the `tag_of` metafunction. Specifically, for any type `T`, `tag_of<T>::type` is the tag used to dispatch it.
2. A function belonging to the public interface of the library, for which we'd like to be able to provide a customized implementation. In Hana, these functions are the algorithms associated to a concept, like `transform` or `unpack`.
3. An implementation for the function, parameterized with the tag(s) of the argument(s) passed to the function. In Hana, this is usually done by having a separate template called `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:

template <typename Tag>
struct print_impl {
template <typename X>
static void apply(std::ostream&, X const&) {
// possibly some default implementation
}
};
template <typename X>
void print(std::ostream& os, X x) {
using Tag = typename hana::tag_of<X>::type;
print_impl<Tag>::apply(os, x);
}
boost::hana::experimental::print
auto print
Returns a string representation of the given object.
Definition: printable.hpp:69
boost::hana::apply
constexpr auto apply
Invokes a Callable with the given arguments.
Definition: apply.hpp:40

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:

struct vector_tag;
struct vector0 {
using hana_tag = vector_tag;
static constexpr std::size_t size = 0;
};
template <typename T1>
struct vector1 {
T1 t1;
using hana_tag = vector_tag;
static constexpr std::size_t size = 1;
template <typename Index>
auto const& operator[](Index i) const {
static_assert(i == 0u, "index out of bounds");
return t1;
}
};
template <typename T1, typename T2>
struct vector2 {
T1 t1; T2 t2;
using hana_tag = vector_tag;
static constexpr std::size_t size = 2;
// Using Hana as a backend to simplify the example.
template <typename Index>
auto const& operator[](Index i) const {
return *hana::make_tuple(&t1, &t2)[i];
}
};
// and so on...
boost::hana::size
constexpr auto size
Equivalent to length; provided for consistency with the standard library.
Definition: size.hpp:30

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

void print(std::ostream& os, vector0)
{ os << "[]"; }
template <typename T1>
void print(std::ostream& os, vector1<T1> v)
{ os << "[" << v.t1 << "]"; }
template <typename T1, typename T2>
void print(std::ostream& os, vector2<T1, T2> v)
{ os << "[" << v.t1 << ", " << v.t2 << "]"; }
// and so on...

Now, with tag dispatching, you can rely on the `vectorN`s all sharing the same tag and specialize only the `print_impl` struct instead:

template <>
struct print_impl<vector_tag> {
template <typename vectorN>
static void apply(std::ostream& os, vectorN xs) {
auto N = hana::size_c<vectorN::size>;
os << "[";
N.times.with_index([&](auto i) {
os << xs[i];
if (i != N - hana::size_c<1>) os << ", ";
});
os << "]";
}
};

One upside is that all `vectorN`s 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:

template <typename X>
void print(std::ostream& os, X x) {
// **** check some precondition ****
// The precondition only has to be checked here; implementations
// can assume their arguments to always be sane.
using Tag = typename hana::tag_of<X>::type;
print_impl<Tag>::apply(os, x);
}

Note
  Checking preconditions does not make much sense for a `print` function, but consider for example a function to get the `n`th 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:

// Defining a function object is only needed once and implementations do not
// have to worry about static initialization and other painful tricks.
struct print_t {
template <typename X>
void operator()(std::ostream& os, X x) const {
using Tag = typename hana::tag_of<X>::type;
print_impl<Tag>::apply(os, x);
}
};
constexpr print_t print{};

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:

template <typename Tag>
struct print_impl<Tag, hana::when<Tag represents some kind of sequence>> {
template <typename Seq>
static void apply(std::ostream& os, Seq xs) {
// Some implementation for any sequence
}
};

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.

## Emulation of C++ concepts

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:

template <typename T>
struct Concept
: hana::integral_constant<bool, whether T models 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 `print`ed. Our end goal is to have a template struct such as

template <typename T>
struct Printable
: hana::integral_constant<bool, whether print_impl<tag of T> is defined>
{ };

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:

struct special_base_class { };
template <typename T>
struct print_impl : special_base_class {
template <typename ...Args>
static constexpr auto apply(Args&& ...) = delete;
};
template <typename T>
struct Printable
: hana::integral_constant<bool,
!std::is_base_of<special_base_class, print_impl<hana::tag_of_t<T>>>::value
>
{ };

Of course, when we specialize `print_impl` with a custom type, we don't inherit from that `special_base_class` type:

struct Person { std::string name; };
template <>
struct print_impl<Person> /* don't inherit from special_base_class */ {
// ... implementation ...
};
static_assert(Printable<Person>::value, "");
static_assert(!Printable<void>::value, "");

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:

template <typename T>
struct print_impl : hana::default_ {
template <typename ...Args>
static constexpr auto apply(Args&& ...) = delete;
};
template <typename T>
struct Printable
: hana::integral_constant<bool,
!hana::is_default<print_impl<hana::tag_of_t<T>>>::value
>
{ };

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.

# Header organization

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.hpp`
  This is the master header of the library, which includes the whole public interface of the library. Note that external adapters, experimental features and implementation details are not included by this header, however, since some of them require additional dependencies.
- `boost/hana/`
  This is the main directory of the library containing the definitions of everything provided by the library. Each algorithm and container provided by the library has its own header. For a container or an algorithm named `XXX`, the corresponding header is `boost/hana/XXX.hpp`.
  - `boost/hana/concept/`
    This subdirectory contains the definition of Hana's concepts. These headers provide a way to check whether an object is a model of the corresponding concept, and they sometimes also provide default implementations for other related concepts, which are documented on a per-concept basis. They also include all the algorithms associated to that concept.
  - `boost/hana/core/`
    This subdirectory contains the machinery for tag dispatching and other related utilities like `make` and `to`.
  - `boost/hana/fwd/`
    This subdirectory contains the forward declaration of everything in the library. It is essentially a mirror of the `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/`
    This subdirectory contains various function objects that are often useful, but that do not necessarily belong to a concept.

  - `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:

    #include <boost/hana/ext/std/tuple.hpp>
    #include <boost/hana/front.hpp>
    #include <tuple> // still required to create a tuple
    namespace hana = boost::hana;
    int main() {
    constexpr std::tuple<int, char, float> xs{1, '2', 3.0f};
    static_assert(hana::front(xs) == 1, "");
    }
    tuple.hpp
    Adapts std::tuple for use with Hana.
    front.hpp
    Defines boost::hana::front.

  - `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/`
    This directory contains utilities required internally. Nothing in `detail/` is guaranteed to be stable, so you should not use it.

# Conclusion

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.

## Fair warning: functional programming ahead

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.

## Related material

Through the years, I have produced some material about Hana and metaprogramming more generally. You may find some of it useful:

- Keynote on metaprogramming at Meeting C++ 2016 (slides/video)
- Talk on advanced metaprogramming techniques used in Hana at C++Now 2016 (slides/video)
- Introduction to metaprogramming with Hana at C++Now 2016 (slides/video)
- Talk on the MPL11 library at C++Now 2014. This is how Hana started out. (slides/video)
- My bachelor's thesis was a formalization of C++ metaprogramming using category theory. The thesis is available here, and the slides of a related presentation are available here. Unfortunately, both are in french only.

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.

## Projects using Hana

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):

- Dyno: A policy-based type erasure library. Uses Hana for vtable generation and concept map emulation under the hood.
- yap: An expression template library built on top of Hana.
- NBDL: Library for managing application state across network. Uses Hana for some things under the hood.
- ECST: An experimental multithreaded compile-time entity-component system using Hana under the hood for a few things.

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

# Using the reference

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:

- Core
  Documentation for the core module, which contains everything needed to create concepts, data types and related utilities. This is relevant if you need to extend the library, but otherwise you can probably ignore this.
- Concepts
  Documentation for all the concepts provided with the library. Each concept:
  - Documents which functions must be implemented absolutely in order to model that concept. The set of functions that must be provided is called a minimal complete definition.
  - Documents semantic constraints that any model of that concept must satisfy. These constraints are usually called laws and they are expressed in a semi-formal mathematical language. Of course, those laws can't be checked automatically but you should still make sure you satisfy them.
  - Documents the concept(s) it refines, if any. Sometimes, a concept is powerful enough to provide a model of a concept it refines, or at least the implementation for some of its associated functions. When this is the case, the concept will document which functions of the refined concept it provides, and how it does so. Also, it is sometimes possible that the model for a refined concept is unique, in which case it can be provided automatically. When this happens, it will be documented but you don't have to do anything special to get that model.
- Data types
  Documentation for all the data structures provided with the library. Each data structure documents the concept(s) it models, and how it does so. It also documents the methods tied to it but not to any concept, for example `maybe` for `optional`.
- Functional
  General purpose function objects that are generally useful in a purely functional setting. These are currently not tied to any concept or container.
- External adapters
  Documentation for all the adapters for external libraries. These adapters are documented as if they were native types provided by Hana, but obviously Hana only provides the compatibility layer between them and the library.
- Configuration options
  Macros that can be used to tweak the global behavior of the library.
- Assertions
  Macros to perform various types of assertions.
- Alphabetical index
  Alphabetical index of everything provided in the library.
- Headers
  A list of all the headers provided by the library.
- Details
  Implementation details; don't go there. Anything not documented at all or documented in this group is not guaranteed to be stable.

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.

## Function signatures

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_constant`s 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_constant`s. 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_constant`s 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} \]

# Acknowledgements

I'd like to thank the following persons and organizations for contributing to Hana in one way or another:

- Zach Laine and Matt Calabrese for the original idea of using function call syntax to do type-level computations, as presented in their BoostCon presentation (slides 1) (slides 2).
- Joel Falcou for mentoring me two consecutive years during my work on Hana as part of the Google Summer of Code program, Niall Douglas for being the GSoC admin for Boost and helping me get in the program, and finally Google for their awesome GSoC program.
- The Boost Steering committee for unlocking a grant for me to work on Hana in the winter of 2015, as an extension to the previous year's GSoC.
- Several C++Now attendees and members of the Boost mailing list for insightful conversations, comments and questions about the project.

# Glossary

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::forward`ed, 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::forward`ed `x`.

- `perfect-capture`

  This is used in lambdas to signify that the captured variables are initialized using perfect forwarding, as if `[x(forwarded(x))...]() { }` had been used.

- `tag-dispatched`

  This 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-defined`

  This 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.

# Rationales/FAQ

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.

## Why restrict usage of external dependencies?

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.

## Why no iterators?

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).

## Why leave some container's representation implementation-defined?

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:

auto tuple = hana::make_tuple(1, 'x', 3.4f);
auto result = hana::find_if(tuple, [](auto const& x) {
return hana::traits::is_integral(hana::typeid_(x));
});

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 `nothing`ness 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:

some_type result = hana::find_if(tuple, [](auto const& x) {
return hana::traits::is_integral(hana::typeid_(x));
});

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:

using Container = fusion::result_of::make_vector<int, char, float>::type;
Container tuple = fusion::make_vector(1, 'x', 3.4f);
using Predicate = mpl::quote1<std::is_integral>;
using Result = fusion::result_of::find_if<Container, Predicate>::type;
Result result = fusion::find_if<Predicate>(tuple);

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.

## Why Hana?

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 :-).

## Why define our own tuple?

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.

## How are names chosen?

When deciding upon a name `X`, I try to balance the following things (in no specific order):

- How idiomatic is `X` in C++?
- How idiomatic is `X` in the rest of the programming world?
- How good of a name `X` actually is, regardless of historical reasons
- How do I, as the library author, feel about `X`
- How do users of the library feel about `X`
- Are there technical reasons not to use `X`, like name clashes or names reserved by the standard

Of 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.

## How is the parameter order decided?

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:

algorithm(container, [](auto x) {
return ...;
});
// is nicer than
algorithm([](auto x) {
return ...;
}, container);

## Why tag dispatching?

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:

implementation_of_at(std::declval<T>(), std::declval<N>())
implementation_of_is_empty(std::declval<T>())
implementation_of_drop_front(std::declval<T>())

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.

## Why not provide zip_longest?

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.

## Why aren't concepts constexpr functions?

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

template <??? Concept>
struct some_metafunction {
// ...
};

This sort of code is very useful in some contexts, such as checking whether two types have a common embedding modeling a concept:

template <??? Concept, typename T, typename U>
struct have_common_embedding {
// whether T and U both model Concept, and share a common type that also models 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:

template <template <typename ...> class Concept, typename T, typename U>
struct have_common_embedding {
// whether T and U both model Concept, and share a common type that also models Concept
};

# Appendix I: Advanced constexpr

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.

## Constexpr stripping

Let's start with a challenging question. Should the following code compile?

template <typename T>
void f(T t) {
static_assert(t == 1, "");
}
constexpr int one = 1;
f(one);

The answer is no, and the error given by Clang goes like

error: static_assert expression is not an integral constant expression
static_assert(t == 1, "");
^~~~~~
boost::hana::integral
constexpr auto integral
Turn a Metafunction into a function taking types and returning a default-constructed object.
Definition: type.hpp:513

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:

// Here, the compiler should generate the code for f<int> and store the
// address of that code into fptr.
void (*fptr)(int) = f<int>;

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:

void (*fptr)(int) = f<int>; // assume this was possible
int i = ...; // user input
fptr(i);

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:

template <typename T>
void f(constexpr T t) {
static_assert(t == 1, "");
}
constexpr int one = 1;
f(one);

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.

## Constexpr preservation

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:

template <int i>
struct foo { };
auto f(int i) -> foo<i>; // obviously won't work

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.

Todo:
  Improve this explanation and talk about non-integral constant expressions wrapped into types.

## Side effects

Let me ask a tricky question. Is the following code valid?

template <typename T>
constexpr int f(T& n) { return 1; }
int n = 0;
constexpr int i = f(n);

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 `throw`ing inside of a `constexpr` function:

constexpr int sqrt(int i) {
if (i < 0) throw "i should be non-negative";
return ...;
}
constexpr int two = sqrt(4); // ok: did not attempt to throw
constexpr int error = sqrt(-4); // error: can't throw in a constant expression

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:

template <typename T>
constexpr int f(T& n, bool touch_n) {
if (touch_n) n + 1;
return 1;
}
int n = 0;
constexpr int i = f(n, false); // ok
constexpr int j = f(n, true); // error

The error given by Clang for the second invocation is

error: constexpr variable 'j' must be initialized by a constant expression
constexpr int j = f(n, true); // error
^ ~~~~~~~~~~
note: read of non-const variable 'n' is not allowed in a constant expression
if (touch_n) n + 1;
^

Let's now step the game up a bit and consider a more subtle example. Is the following code valid?

template <typename T>
constexpr int f(T n) { return 1; }
int n = 0;
constexpr int i = f(n);

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:

error: constexpr variable 'i' must be initialized by a constant expression
constexpr int i = f(n);
^ ~~~~
note: read of non-const variable 'n' is not allowed in a constant expression
constexpr int i = f(n);
^

Todo:
  Explain how side-effects may not appear inside constant expressions, even if the expression they yield are not accessed.