Quick Start

| Home | Libraries | People | FAQ | More

## Quick Start

I assume the reader is already familiar with tuples (Boost.Tuple) and its ancestor `std::pair`. The tuple is a generalization of `std::pair` for multiple heterogeneous elements (triples, quadruples, etc.). The tuple is more or less a synonym for fusion's ``vector``.

For starters, we shall include all of Fusion's Sequence(s) [1] :

    #include <boost/fusion/sequence.hpp>
    #include <boost/fusion/include/sequence.hpp>

Let's begin with a ``vector`` [2] :

    vector<int, char, std::string> stuff(1, 'x', "howdy");
    int i = at_c<0>(stuff);
    char ch = at_c<1>(stuff);
    std::string s = at_c<2>(stuff);

Just replace `tuple` for ``vector`` and `get` for ``at_c`` and this is exactly like Boost.Tuple. Actually, either names can be used interchangeably. Yet, the similarity ends there. You can do a lot more with Fusion ``vector`` or `tuple`. Let's see some examples.

#### Print the vector as XML

First, let's include the algorithms:

    #include <boost/fusion/algorithm.hpp>
    #include <boost/fusion/include/algorithm.hpp>

Now, let's write a function object that prints XML of the form <type>data</type> for each member in the tuple.

    struct print_xml
    {
        template <typename T>
        void operator()(T const& x) const
        {
            std::cout
                << '<' << typeid(x).name() << '>'
                << x
                << "</" << typeid(x).name() << '>'
                ;
        }
    };

Now, finally:

    for_each(stuff, print_xml());

That's it! ``for_each`` is a fusion algorithm. It is a generic algorithm similar to STL's. It iterates over the sequence and calls a user supplied function. In our case, it calls `print_xml`'s `operator()` for each element in `stuff`.

| Caution
The result of `typeid(x).name()` is platform specific. The code here is just for exposition. Of course you already know that :-)

``for_each`` is generic. With `print_xml`, you can use it to print just about any Fusion Sequence.

#### Print only pointers

Let's get a little cleverer. Say we wish to write a generic function that takes in an arbitrary sequence and XML prints only those elements which are pointers. Ah, easy. First, let's include the `is_pointer` boost type trait:

    #include <boost/type_traits/is_pointer.hpp>

Then, simply:

    template <typename Sequence>
    void xml_print_pointers(Sequence const& seq)
    {
        for_each(filter_if<boost::is_pointer<_> >(seq), print_xml());
    }

``filter_if`` is another Fusion algorithm. It returns a `filter_view`, a conforming Fusion sequence. This view reflects only those elements that pass the given predicate. In this case, the predicate is `boost::is_pointer<_>`. This "filtered view" is then passed to the `for_each` algorithm, which then prints the "filtered view" as XML.

Easy, right?

#### Associative tuples

Ok, moving on...

Apart from ``vector``, fusion has a couple of other sequence types to choose from. Each sequence has its own characteristics. We have ``list``, ``set``, ``map``, plus a multitude of `views` that provide various ways to present the sequences.

Fusion's ``map`` associate types with elements. It can be used as a cleverer replacement of the `struct`. Example:

    namespace fields
    {
        struct name;
        struct age;
    }

    typedef map<
        fusion::pair<fields::name, std::string>
      , fusion::pair<fields::age, int> >
    person;

``map`` is an associative sequence. Its elements are Fusion pairs which differ somewhat from `std::pair`. Fusion pairs only contain one member, with the type of their second template parameter. The first type parameter of the pair is used as an index to the associated element in the sequence. For example, given a `a_person` of type, `person`, you can do:

    using namespace fields;
    std::string person_name = at_key<name>(a_person);
    int person_age = at_key<age>(a_person);

Why go through all this trouble, you say? Well, for one, unlike the `struct`, we are dealing with a generic data structure. There are a multitude of facilities available at your disposal provided out of the box with fusion or written by others. With these facilities, introspection comes for free, for example. We can write one serialization function (well, two, if you consider loading and saving) that will work for all your fusion ``map``s. Example:

    struct saver
    {
        template <typename Pair>
        void operator()(Pair const& data) const
        {
            some_archive << data.second;
        }
    };

    template <typename Stuff>
    void save(Stuff const& stuff)
    {
        for_each(stuff, saver());
    }

The `save` function is generic and will work for all types of `stuff` regardless if it is a `person`, a `dog` or a whole `alternate_universe`.

#### Tip of the Iceberg

And... we've barely scratched the surface! You can compose and expand the data structures, remove elements from the structures, find specific data types, query the elements, filter out types for inspection, transform data structures, etc. What you've seen is just the tip of the iceberg.

[1] There are finer grained header files available if you wish to have more control over which components to include (see section Orgainization for details).

[2] Unless otherwise noted, components are in namespace `boost::fusion`. For the sake of simplicity, code in this quick start implies `using` directives for the fusion components we will be using.