boost_mp11/doc/mp11/examples.qbk

[/
 /  Copyright 2017 Peter Dimov
 /
 / Distributed under the Boost Software License, Version 1.0. (See
 / accompanying file LICENSE_1_0.txt or copy at
 / http://www.boost.org/LICENSE_1_0.txt)
 /]

[section:examples Examples]

[section Generating Test Cases]

Let's suppose that we have written a metafunction `result<T, U>`:

  template<class T> using promote = std::common_type_t<T, int>;
  template<class T, class U> using result = std::common_type_t<promote<T>, promote<U>>;

that ought to represent the result of an arithmetic operation on the integer types `T` and `U`,
for example `t + u`. We want to test whether `result<T, U>` gives correct results for various combinations
of `T` and `U`, so we write the function

    template<class T1, class T2> void test_result()
    {
        using T3 = decltype( T1() + T2() );
        using T4 = result<T1, T2>;

        std::cout << ( std::is_same<T3, T4>::value? "[PASS]": "[FAIL]" ) << std::endl;
    }

and then need to call it a substantial number of times:

    int main()
    {
        test_result<char, char>();
        test_result<char, short>();
        test_result<char, int>();
        test_result<char, unsigned>();
        // ...
    }

Writing all those type combinations by hand is unwieldy, error prone, and worst of all, boring. This is
how we can leverage Mp11 to automate the task:

    #include <boost/mp11.hpp>
    #include <boost/tuple_for_each.hpp>
    #include <boost/core/demangle.hpp>
    #include <type_traits>
    #include <iostream>
    #include <typeinfo>

    using namespace boost::mp11;

    template<class T> std::string name()
    {
        return boost::core::demangle( typeid(T).name() );
    }

    template<class T> using promote = std::common_type_t<T, int>;
    template<class T, class U> using result = std::common_type_t<promote<T>, promote<U>>;

    template<class T1, class T2> void test_result( mp_list<T1, T2> const& )
    {
        using T3 = decltype( T1() + T2() );
        using T4 = result<T1, T2>;

        std::cout << ( std::is_same<T3, T4>::value? "[PASS] ": "[FAIL] " )
            << name<T1>() << " + " << name<T2>() << " -> " << name<T3>() << ", result: " << name<T4>() << std::endl;
    }

    int main()
    {
        using L = std::tuple<char, short, int, unsigned, long, unsigned long>;
        boost::tuple_for_each( mp_product<mp_list, L, L>(), [](auto&& x){ test_result(x); } );
    }

How does it work?

`mp_product<F, L1, L2>` calls `F<T1, T2>` where `T1` varies over the elements of `L1` and `T2` varies over
the elements of `L2`, as if by executing two nested loops. It then returns a list of these results, of the same
type as `L1`.

In our case, both lists are the same `std::tuple`, and `F` is `mp_list`, so `mp_product<mp_list, L, L>` will get us
`std::tuple<mp_list<char, char>, mp_list<char, short>, mp_list<char, int>, ..., mp_list<unsigned long, long>, mp_list<unsigned long, unsigned long>>`.

We then default-construct this tuple and pass it to `tuple_for_each`. `tuple_for_each(tp, f)` calls `f` for every
tuple element; we use a (C++14) lambda that calls `test_result`. (In pure C++11, we'd need to make `test_result` a
function object with a templated `operator()` and pass that to `tuple_for_each` directly.)
[endsect]

[section Fixing `tuple_cat`]

The article [@http://pdimov.com/cpp2/simple_cxx11_metaprogramming.html Simple C++11 metaprogramming] builds an
implementation of the standard function `tuple_cat`, with the end result given below:

    template<class L> using F = mp_iota<mp_size<L>>;

    template<class R, class...Is, class... Ks, class Tp>
    R tuple_cat_( mp_list<Is...>, mp_list<Ks...>, Tp tp )
    {
        return R{ std::get<Ks::value>(std::get<Is::value>(tp))... };
    }

    template<class... Tp,
        class R = mp_append<std::tuple<>, typename std::remove_reference<Tp>::type...>>
        R tuple_cat( Tp &&... tp )
    {
        std::size_t const N = sizeof...(Tp);

        // inner

        using list1 = mp_list<mp_rename<typename std::remove_reference<Tp>::type, mp_list>...>;
        using list2 = mp_iota_c<N>;

        using list3 = mp_transform<mp_fill, list1, list2>;

        using inner = mp_apply<mp_append, list3>;

        // outer

        using list4 = mp_transform<F, list1>;

        using outer = mp_apply<mp_append, list4>;

        //

        return tuple_cat_<R>( inner(), outer(), std::forward_as_tuple( std::forward<Tp>(tp)... ) );
    }

This function, however, is not entirely correct, in that it doesn't handle some cases properly. For example,
trying to concatenate tuples containing move-only elements such as `unique_ptr` fails:

    std::tuple<std::unique_ptr<int>> t1;
    std::tuple<std::unique_ptr<float>> t2;

    auto result = ::tuple_cat( std::move( t1 ), std::move( t2 ) );

Trying to concatenate `const` tuples fails:

	std::tuple<int> const t1;
	std::tuple<float> const t2;

	auto result = ::tuple_cat( t1, t2 );

And finally, the standard `tuple_cat` is specified to work on arbitrary tuple-like types (that is, all types
that support `tuple_size`, `tuple_element`, and `get`), while our implementation only works with `tuple` and
`pair`. `std::array`, for example, fails:

    std::array<int, 2> t1{ 1, 2 };
    std::array<float, 3> t2{ 3.0f, 4.0f, 5.0f };

    auto result = ::tuple_cat( t1, std::move( t2 ) );

Let's fix these one by one. Support for move-only types is easy, if one knows where to look. The problem is
that `Tp` that we're passing to the helper `tuple_cat_` is (correctly) `tuple<unique_ptr<int>&&, unique_ptr<float>&&>`,
but `std::get<0>(tp)` still returns `unique_ptr<int>&`, because `tp` is an lvalue. This behavior is a bit
surprising, but consistent with how rvalue reference members are treated by the language.

Long story short, we need `std::move(tp)` in `tuple_cat_` to make `tp` an rvalue:

    template<class R, class...Is, class... Ks, class Tp>
    R tuple_cat_( mp_list<Is...>, mp_list<Ks...>, Tp tp )
    {
        return R{ std::get<Ks::value>(std::get<Is::value>(std::move(tp)))... };
    }

Next, `const`-qualified tuples. The issue here is that we're stripping references from the input tuples, but not
`const`. As a result, we're trying to manipulate types such as `tuple<int> const` with Mp11 algorithms, and these
types do not fit the list concept. We just need to strip qualifiers as well, by defining the useful `remove_cv_ref`
primitive that is inexplicably missing from the standard library:

    template<class T> using remove_cv_ref = typename std::remove_cv<
        typename std::remove_reference<T>::type>::type;

and then by using `remove_cv_ref<Tp>` in place of `typename std::remove_reference<Tp>::type`:

    template<class... Tp,
        class R = mp_append<std::tuple<>, remove_cv_ref<Tp>...>>
        R tuple_cat( Tp &&... tp )
    {
        std::size_t const N = sizeof...(Tp);

        // inner

        using list1 = mp_list<mp_rename<remove_cv_ref<Tp>, mp_list>...>;
        
        // ...

Finally, tuple-like types. We've so far exploited the fact that `std::pair` and `std::tuple` are valid Mp11 lists,
but in general, arbitrary tuple-like types aren't, so we need to convert them into such. For that, we'll need to
define a metafunction `from_tuple_like` that will take an arbitrary tuple-like type and will return, in our case,
the corresponding `mp_list`.

Technically, a more principled approach would've been to return `std::tuple`, but here `mp_list` will prove more
convenient.

What we need is, given a tuple-like type `Tp`, to obtain `mp_list<std::tuple_element<0, Tp>, std::tuple_element<1, Tp>,
..., std::tuple_element<N-1, Tp>>`, where `N` is `tuple_size<Tp>::value`. Here's one way to do it:

    template<class T, class I> using tuple_element = std::tuple_element_t<I::value, T>;
    template<class T> using from_tuple_like = mp_product<tuple_element, mp_list<T>, mp_iota<std::tuple_size<T>>>;

(`mp_iota<N>` is an algorithm that returns an `mp_list` with elements `mp_size_t<0>`, `mp_size_t<1>`, ..., `mp_size_t<N-1>`.)

Remember that `mp_product<F, L1, L2>` performs the equivalent of two nested loops over the elements of `L1` and `L2`,
applying `F` to the two variables and gathering the result. In our case `L1` consists of the single element `T`, so
only the second loop (over `mp_iota<N>`, where `N` is `tuple_size<T>`), remains, and we get a list of the same type
as `L1` (an `mp_list`) with contents `tuple_element<T, mp_size_t<0>>`, `tuple_element<T, mp_size_t<1>>`, ...,
`tuple_element<T, mp_size_t<N-1>>`.

For completeness's sake, here's another, more traditional way to achieve the same result:

    template<class T> using from_tuple_like = mp_transform_q<mp_bind_front<tuple_element, T>, mp_iota<std::tuple_size<T>>>;

With all these fixes applied, our fully operational `tuple_cat` now looks like this:

    template<class L> using F = mp_iota<mp_size<L>>;

    template<class R, class...Is, class... Ks, class Tp>
    R tuple_cat_( mp_list<Is...>, mp_list<Ks...>, Tp tp )
    {
        return R{ std::get<Ks::value>(std::get<Is::value>(std::move(tp)))... };
    }

    template<class T> using remove_cv_ref = typename std::remove_cv<
        typename std::remove_reference<T>::type>::type;

    template<class T, class I> using tuple_element = std::tuple_element_t<I::value, T>;
    template<class T> using from_tuple_like = mp_product<tuple_element, mp_list<T>, mp_iota<std::tuple_size<T>>>;

    template<class... Tp,
        class R = mp_append<std::tuple<>, from_tuple_like<remove_cv_ref<Tp>>...>>
        R tuple_cat( Tp &&... tp )
    {
        std::size_t const N = sizeof...(Tp);

        // inner

        using list1 = mp_list<from_tuple_like<remove_cv_ref<Tp>>...>;
        using list2 = mp_iota_c<N>;

        using list3 = mp_transform<mp_fill, list1, list2>;

        using inner = mp_apply<mp_append, list3>;

        // outer

        using list4 = mp_transform<F, list1>;

        using outer = mp_apply<mp_append, list4>;

        //

        return tuple_cat_<R>( inner(), outer(), std::forward_as_tuple( std::forward<Tp>(tp)... ) );
    }

[endsect]

[section Computing Return Types]

C++17 has a standard variant type, called `std::variant`. It also defines a function template
`std::visit` that can be used to apply a function to the contained value of one or more `variant`s.
So for instance, if the `variant` `v1` contains `1`, and the `variant` `v2` contains `2.0f`,
`std::visit(f, v1, v2)` will call `f(1, 2.0f)`.

However, `std::visit` has one limitation: it cannot return a result unless all
possible applications of the function have the same return type. If, for instance, `v1` and `v2`
are both of type `std::variant<short, int, float>`,

    std::visit( []( auto const& x, auto const& y ){ return x + y; }, v1, v2 );

will fail to compile because the result of `x + y` can be either `int` or `float` depending on
what `v1` and `v2` hold.

A type that can hold either `int` or `float` already exists, called, surprisingly enough, `std::variant<int, float>`.
Let's write our own function template `rvisit` that is the same as `visit` but returns a `variant`:

    template<class F, class... V> auto rvisit( F&& f, V&&... v )
    {
        using R = /*...*/;
        return std::visit( [&]( auto&&... x ){ return R( std::forward<F>(f)( std::forward<decltype(x)>(x)... ) ); }, std::forward<V>( v )... );
    }

What this does is basically calls `std::visit` to do the work, but instead of passing it `f`, we pass a lambda that does the same as `f` except
it converts the result to a common type `R`. `R` is supposed to be `std::variant<...>` where the ellipsis denotes the return types of
calling `f` with all possible combinations of variant values.

We'll first define a helper quoted metafunction `Qret<F>` that returns the result of the application of `F` to arguments of type `T...`:

    template<class F> struct Qret
    {
        template<class... T> using fn = decltype( std::declval<F>()( std::declval<T>()... ) );
    };

(Unfortunately, we can't just define this metafunction inside `rvisit`; the language prohibits defining template aliases inside functions.)

With `Qret` in hand, a `variant` of the possible return types is just a matter of applying it over the possible combinations of the variant values:

    using R = mp_product_q<Qret<F>, std::remove_reference_t<V>...>;

Why does this work? `mp_product<F, L1<T1...>, L2<T2...>, ..., Ln<Tn...>>` returns `L1<F<U1, U2, ..., Un>, ...>`, where `Ui` traverse all
possible combinations of list values. Since in our case all `Li` are `std::variant`, the result will also be `std::variant`. (`mp_product_q` is
the same as `mp_product`, but for quoted metafunctions such as our `Qret<F>`.)

One more step remains. Suppose that, as above, we're passing two variants of type `std::variant<short, int, float>` and `F` is
`[]( auto const& x, auto const& y ){ return x + y; }`. This will generate `R` of length 9, one per each combination, but many of those
elements will be the same, either `int` or `float`, and we need to filter out the duplicates. So,

    using R = mp_unique<mp_product<Qret<F>::template fn, std::remove_reference_t<V>...>>;

and we're done:

    #include <boost/mp11.hpp>
    #include <boost/core/demangle.hpp>
    #include <variant>
    #include <type_traits>
    #include <typeinfo>
    #include <iostream>

    using namespace boost::mp11;

    template<class F> struct Qret
    {
        template<class... T> using fn = decltype( std::declval<F>()( std::declval<T>()... ) );
    };

    template<class F, class... V> auto rvisit( F&& f, V&&... v )
    {
        using R = mp_unique<mp_product<Qret<F>::template fn, std::remove_reference_t<V>...>>;
        return std::visit( [&]( auto&&... x ){ return R( std::forward<F>(f)( std::forward<decltype(x)>(x)... ) ); }, std::forward<V>( v )... );
    }

    template<class T> std::string name()
    {
        return boost::core::demangle( typeid(T).name() );
    }

    int main()
    {
        std::variant<signed char, unsigned char, signed short, unsigned short, int, unsigned> v1( 1 );

        std::cout << "(" << name<decltype(v1)>() << ")v1: ";
        std::visit( []( auto const& x ){ std::cout << "(" << name<decltype(x)>() << ")" << x << std::endl; }, v1 );

        std::variant<int, float, double> v2( 2.0f );

        std::cout << "(" << name<decltype(v2)>() << ")v2: ";
        std::visit( []( auto const& x ){ std::cout << "(" << name<decltype(x)>() << ")" << x << std::endl; }, v2 );

        auto v3 = rvisit( []( auto const& x, auto const& y ){ return x + y; }, v1, v2 );

        std::cout << "(" << name<decltype(v3)>() << ")v3: ";
        std::visit( []( auto const& x ){ std::cout << "(" << name<decltype(x)>() << ")" << x << std::endl; }, v3 );
    }

[endsect]

[endsect:examples]