# Advanced Topics

This section discusses several features of the library often required for advanced uses of `variant`. Unlike in the above section, each feature presented below is largely independent of the others. Accordingly, this section is not necessarily intended to be read linearly or in its entirety.

## Preprocessor macros

While the `variant` class template's variadic parameter list greatly simplifies use for specific instantiations of the template, it significantly complicates use for generic instantiations. For instance, while it is immediately clear how one might write a function accepting a specific `variant` instantiation, say `variant<int, std::string>`, it is less clear how one might write a function accepting any given `variant`.

Due to the lack of support for true variadic template parameter lists in the C++98 standard, the preprocessor is needed. While the Preprocessor library provides a general and powerful solution, the need to repeat `BOOST_VARIANT_LIMIT_TYPES` unnecessarily clutters otherwise simple code. Therefore, for common use-cases, this library provides its own macro `BOOST_VARIANT_ENUM_PARAMS`.

This macro simplifies for the user the process of declaring `variant` types in function templates or explicit partial specializations of class templates, as shown in the following:

    // general cases
    template <typename T> void some_func(const T &);
    template <typename T> class some_class;

    // function template overload
    template <BOOST_VARIANT_ENUM_PARAMS(typename T)>
    void some_func(const boost::variant<BOOST_VARIANT_ENUM_PARAMS(T)> &);

    // explicit partial specialization
    template <BOOST_VARIANT_ENUM_PARAMS(typename T)>
    class some_class< boost::variant<BOOST_VARIANT_ENUM_PARAMS(T)> >;

## Using a type sequence to specify bounded types

While convenient for typical uses, the `variant` class template's variadic template parameter list is limiting in two significant dimensions. First, due to the lack of support for true variadic template parameter lists in C++, the number of parameters must be limited to some implementation-defined maximum (namely, `BOOST_VARIANT_LIMIT_TYPES`). Second, the nature of parameter lists in general makes compile-time manipulation of the lists excessively difficult.

To solve these problems, `make_variant_over< Sequence >` exposes a `variant` whose bounded types are the elements of `Sequence` (where `Sequence` is any type fulfilling the requirements of MPL's Sequence concept). For instance,

    typedef mpl::vector< std::string > types_initial;
    typedef mpl::push_front< types_initial, int >::type types;

    boost::make_variant_over< types >::type v1;

behaves equivalently to

    boost::variant< int, std::string > v2;

Portability: Unfortunately, due to standard conformance issues in several compilers, `make_variant_over` is not universally available. On these compilers the library indicates its lack of support for the syntax via the definition of the preprocessor symbol `BOOST_VARIANT_NO_TYPE_SEQUENCE_SUPPORT`.

## Recursive `variant` types

Recursive types facilitate the construction of complex semantics from simple syntax. For instance, nearly every programmer is familiar with the canonical definition of a linked list implementation, whose simple definition allows sequences of unlimited length:

    template <typename T>
    struct list_node
    {
        T data;
        list_node * next;
    };

The nature of `variant` as a generic class template unfortunately precludes the straightforward construction of recursive `variant` types. Consider the following attempt to construct a structure for simple mathematical expressions:

    struct add;
    struct sub;
    template <typename OpTag> struct binary_op;

    typedef boost::variant<
          int
        , binary_op<add>
        , binary_op<sub>
        > expression;

    template <typename OpTag>
    struct binary_op
    {
        expression left;  // variant instantiated here...
        expression right;

        binary_op( const expression & lhs, const expression & rhs )
            : left(lhs), right(rhs)
        {
        }

    }; // ...but binary_op not complete until here!

While well-intentioned, the above approach will not compile because `binary_op` is still incomplete when the `variant` type `expression` is instantiated. Further, the approach suffers from a more significant logical flaw: even if C++ syntax were different such that the above example could be made to "work," `expression` would need to be of infinite size, which is clearly impossible.

To overcome these difficulties, `variant` includes special support for the ``boost::recursive_wrapper`` class template, which breaks the circular dependency at the heart of these problems. Further, ``boost::make_recursive_variant`` provides a more convenient syntax for declaring recursive `variant` types. Tutorials for use of these facilities is described in and .

### Recursive types with `recursive_wrapper`

The following example demonstrates how `recursive_wrapper` could be used to solve the problem presented in :

    typedef boost::variant<
          int
        , boost::recursive_wrapper< binary_op<add> >
        , boost::recursive_wrapper< binary_op<sub> >
        > expression;

Because `variant` provides special support for `recursive_wrapper`, clients may treat the resultant `variant` as though the wrapper were not present. This is seen in the implementation of the following visitor, which calculates the value of an `expression` without any reference to `recursive_wrapper`:

    class calculator : public boost::static_visitor<int>
    {
    public:

        int operator()(int value) const
        {
            return value;
        }

        int operator()(const binary_op<add> & binary) const
        {
            return boost::apply_visitor( calculator(), binary.left )
                 + boost::apply_visitor( calculator(), binary.right );
        }

        int operator()(const binary_op<sub> & binary) const
        {
            return boost::apply_visitor( calculator(), binary.left )
                 - boost::apply_visitor( calculator(), binary.right );
        }

    };

Finally, we can demonstrate `expression` in action:

    void f()
    {
        // result = ((7-3)+8) = 12
        expression result(
            binary_op<add>(
                binary_op<sub>(7,3)
              , 8
              )
          );

        assert( boost::apply_visitor(calculator(),result) == 12 );
    }

Performance: `boost::recursive_wrapper` has no empty state, which makes its move constructor not very optimal. Consider using `std::unique_ptr` or some other safe pointer for better performance on C++11 compatible compilers.

### Recursive types with `make_recursive_variant`

For some applications of recursive `variant` types, a user may be able to sacrifice the full flexibility of using `recursive_wrapper` with `variant` for the following convenient syntax:

    typedef boost::make_recursive_variant<
          int
        , std::vector< boost::recursive_variant_ >
        >::type int_tree_t;

Use of the resultant `variant` type is as expected:

    std::vector< int_tree_t > subresult;
    subresult.push_back(3);
    subresult.push_back(5);

    std::vector< int_tree_t > result;
    result.push_back(1);
    result.push_back(subresult);
    result.push_back(7);

    int_tree_t var(result);

To be clear, one might represent the resultant content of `var` as `( 1 ( 3 5 ) 7 )`.

Finally, note that a type sequence can be used to specify the bounded types of a recursive `variant` via the use of ``boost::make_recursive_variant_over``, whose semantics are the same as `make_variant_over` (which is described in ).

Portability: Unfortunately, due to standard conformance issues in several compilers, `make_recursive_variant` is not universally supported. On these compilers the library indicates its lack of support via the definition of the preprocessor symbol `BOOST_VARIANT_NO_FULL_RECURSIVE_VARIANT_SUPPORT`. Thus, unless working with highly-conformant compilers, maximum portability will be achieved by instead using `recursive_wrapper`, as described in .

## Binary visitation

As the tutorial above demonstrates, visitation is a powerful mechanism for manipulating `variant` content. Binary visitation further extends the power and flexibility of visitation by allowing simultaneous visitation of the content of two different `variant` objects.

Notably this feature requires that binary visitors are incompatible with the visitor objects discussed in the tutorial above, as they must operate on two arguments. The following demonstrates the implementation of a binary visitor:

    class are_strict_equals
        : public boost::static_visitor<bool>
    {
    public:

        template <typename T, typename U>
        bool operator()( const T &, const U & ) const
        {
            return false; // cannot compare different types
        }

        template <typename T>
        bool operator()( const T & lhs, const T & rhs ) const
        {
            return lhs == rhs;
        }

    };

As expected, the visitor is applied to two `variant` arguments by means of `apply_visitor`:

    boost::variant< int, std::string > v1( "hello" );

    boost::variant< double, std::string > v2( "hello" );
    assert( boost::apply_visitor(are_strict_equals(), v1, v2) );

    boost::variant< int, const char * > v3( "hello" );
    assert( !boost::apply_visitor(are_strict_equals(), v1, v3) );

Finally, we must note that the function object returned from the "delayed" form of `apply_visitor` also supports binary visitation, as the following demonstrates:

    typedef boost::variant<double, std::string> my_variant;

    std::vector< my_variant > seq1;
    seq1.push_back("pi is close to ");
    seq1.push_back(3.14);

    std::list< my_variant > seq2;
    seq2.push_back("pi is close to ");
    seq2.push_back(3.14);

    are_strict_equals visitor;
    assert( std::equal(
          seq1.begin(), seq1.end(), seq2.begin()
        , boost::apply_visitor( visitor )
        ) );

## Multi visitation

Multi visitation extends the power and flexibility of visitation by allowing simultaneous visitation of the content of three and more different `variant` objects. Note that header for multi visitors shall be included separately.

Notably this feature requires that multi visitors are incompatible with the visitor objects discussed in the tutorial above, as they must operate on same amout of arguments that was passed to `apply_visitor`. The following demonstrates the implementation of a multi visitor for three parameters:

    #include <boost/variant/multivisitors.hpp>

    typedef boost::variant<int, double, bool> bool_like_t;
    typedef boost::variant<int, double> arithmetics_t;

    struct if_visitor: public boost::static_visitor<arithmetics_t> {
        template <class T1, class T2>
        arithmetics_t operator()(bool b, T1 v1, T2 v2) const {
            if (b) {
                return v1;
            } else {
                return v2;
            }
        }
    };

As expected, the visitor is applied to three `variant` arguments by means of `apply_visitor`:

    bool_like_t v0(true), v1(1), v2(2.0);

    assert(
        boost::apply_visitor(if_visitor(), v0, v1, v2)
        ==
        arithmetics_t(1)
    );