extension.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

    {
        template<typename Iterator>
        struct apply
        {
            typedef typename Iterator::struct_type struct_type;
            typedef typename Iterator::index index;
            typedef example::example_struct_iterator<struct_type, index::value + 1> type;

            static type
            call(Iterator const& i)
            {
                 return type(i.struct_);
            }
        };
    };

This should be very familiar from our `deref_impl` implementation, we will be
using this approach again and again now. Our design is simply to increment
the `index` counter to move on to the next element. The various other iterator
manipulations we need to perform will all just involve simple calculations
with the `index` variables.

We also need to provide a suitable `equal_to_impl` so that iterators can be
correctly compared. A __bidirectional_iterator__ will also need an implementation of `prior_impl`. For a
__random_access_iterator__ `distance_impl` and `advance_impl` also need to be provided
in order to satisfy the necessary complexity guarantees. As our iterator is
a __random_access_iterator__ we will have to implement all of these functions.

Full implementations of `prior_impl`, `advance_impl`, `distance_impl` and `equal_to_impl` are
provided in the example code.

[heading Implementing the intrinsic functions of the sequence]

In order that Fusion can correctly identify our sequence as a Fusion sequence, we
need to enable `is_sequence` for our sequence type. As usual we just create
an `impl` type specialized for our sequence tag:

     template<>
     struct is_sequence_impl<example::example_sequence_tag>
     {
         template<typename T>
         struct apply : mpl::true_ {};
     };

We've some similar formalities to complete, providing `category_of_impl` so Fusion
can correctly identify our sequence type, and `is_view_impl` so Fusion can correctly
identify our sequence as not being a __view__ type. Implementations are
provide in the example code.

Now we've completed some formalities, on to more interesting features. Lets get
__begin__ working so that we can get an iterator to start accessing the data in
our sequence.

    template<>
    struct begin_impl<example::example_sequence_tag>
    {
        template<typename Sequence>
        struct apply
        {
            typedef example::example_struct_iterator<Sequence, 0> type;

            static type
            call(Sequence& seq)
            {
                return type(seq);
            }
        };
    };

The implementation uses the same ideas we have applied throughout, in this case
we are just creating one of the iterators we developed earlier, pointing to the
first element in the sequence. The implementation of __end__ is very similar, and
is provided in the example code.

For our __random_access_sequence__ we will also need to implement `size_impl`,
`value_at_impl` and `at_impl`.

[heading Enabling our type as an associative container]

In order for `example_struct` to serve as an associative container,
we need to enable 3 lookup features, __at_key__, __value_at_key__ and __has_key__.
We also need to provide an implementation of the `is_associative` trait
so that our sequence can be correctly identified as an associative container.

To implement `at_key_impl` we need to associate the `fields::age` and `fields::age`
types described in the __quick_start__ guide with the appropriate members of `example_struct`.
Our implementation is as follows:

    template<>
    struct at_key_impl<example::example_sequence_tag>
    {
        template<typename Sequence, typename Key>
        struct apply;

        template<typename Sequence>
        struct apply<Sequence, fields::name>
        {
            typedef typename mpl::if_<
                is_const<Sequence>,
                std::string const&,
                std::string&>::type type;

            static type
            call(Sequence& seq)
            {
                return seq.name;
            };
        };

        template<typename Sequence>
        struct apply<Sequence, fields::age>
        {
            typedef typename mpl::if_<
                is_const<Sequence>,
                int const&,
                int&>::type type;

            static type
            call(Sequence& seq)
            {
                return seq.age;
            };
        };
    };

Its all very similar to the implementations we've seen previously,
such as `deref_impl` and `value_of_impl`. Instead of identifying
the members by index or position, we are now selecting them using
the types `fields::name` and `fields::age`. The implementations of
`value_at_key_impl` and `has_key_impl` are equally straightforward,
and are provided in the example code, along with an implementation
of `is_associative_impl`.

[heading Summary]

We've now worked through the entire process for adding a new random
access sequence and we've also enabled our type to serve as an associative
container. The implementation was slightly longwinded, but followed
a simple repeating pattern.

The support for `std::pair`, __mpl__ sequences, and `boost::array` all
use the same approach, and provide additional examples of the approach
for a variety of types.

[endsect]

[section Sequence Facade]

[heading Description]
The __sequence_facade__ template provides an intrusive mechanism for
producing a conforming Fusion iterator.

[heading Synopsis]
    template<typename Derived, typename TravesalTag, typename IsView = mpl::false_>
    struct sequence_facade;

[heading Usage]
The user of __sequence_facade__ derives his sequence type from a specialization of __sequence_facade__ and passes the derived sequence type as the first template parameter. The second template parameter should be the traversal category of the sequence being implemented. The 3rd parameter should be set to `mpl::true_` if the sequence is a view.

The user must the implement the key expressions required by their sequence type.

[table Parameters
[[Name][Description]]
[[`sequence`, `Seq`][A type derived from __sequence_facade__]]
[[`N`][An __mpl_integral_constant__]]
]

[table Key Expressions
[[Expression][Result]]
[[`sequence::template begin<Seq>::type`][The type of an iterator to the beginning of a sequence of type `Seq`]]
[[`sequence::template begin<Seq>::call(seq)`][An iterator to the beginning of sequence `seq`]]
[[`sequence::template end<Seq>::type`][The type of an iterator to the end of a sequence of type `Seq`]]
[[`sequence::template end<Seq>::call(seq)`][An iterator to the end of sequence `seq`]]
[[`sequence::template size<Seq>::type`][The size of a sequence of type `Seq` as an __mpl_integral_constant__]]
[[`sequence::template size<Seq>::call(seq)`][The size of sequence `seq`]]
[[`sequence::template at<Seq, N>::type`][The type of element `N` in a sequence of type `Seq`]]
[[`sequence::template at<Seq, N>::call(seq)`][Element `N` in sequence `seq`]]
[[`sequence::template value_at<Sequence, N>::type`][The type of the `N`th element in a sequence of type `Seq`]]
]

[heading Include]

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

[heading Example]
A full working example using __sequence_facade__ is provided in triple.cpp in the extension examples.

[endsect]

[section Iterator Facade]

[heading Description]
The __iterator_facade__ template provides an intrusive mechanism for
producing a conforming Fusion iterator.

[heading Synopsis]

    template<typename Derived, typename TravesalTag>
    struct iterator_facade;

[heading Usage]
The user of iterator_facade derives his iterator type from a specialization of iterator_facade and passes the derived iterator type as the first template parameter. The second template parameter should be the traversal category of the iterator being implemented.

The user must the implement the key expressions required by their iterator type.

[table Parameters
[[Name][Description]]
[[`iterator`, `It`, `It1`, `It2`][A type derived from __iterator_facade__]]
[[`N`][An __mpl_integral_constant__]]
]

[table Key Expressions
[[Expression][Result][Default]]
[[`iterator::template value_of<It>::type`][The element stored at iterator position `It`][None]]
[[`iterator::template deref<It>::type`][The type returned when dereferencing an iterator of type `It`][None]]
[[`iterator::template deref<It>::call(it)`][Dereferences iterator `it`][None]]
[[`iterator::template next<It>::type`][The type of the next element from `It`][None]]
[[`iterator::template next<It>::call(it)`][The next iterator after `it`][None]]
[[`iterator::template prior<It>::type`][The type of the next element from `It`][None]]
[[`iterator::template prior<It>::call(it)`][The next iterator after `it`][None]]
[[`iterator::template advance<It, N>::type`][The type of an iterator advanced `N` elements from `It`][Implemented in terms of `next` and `prior`]]
[[`iterator::template advance<It, N>::call(it)`][An iterator advanced `N` elements from `it`][Implemented in terms of `next` and `prior`]]
[[`iterator::template distance<It1, It2>::type`][The distance between iterators of type `It1` and `It2` as an __mpl_integral_constant__][None]]
[[`iterator::template distance<It1, It2>::call(it1, it2)`][The distance between iterator `it1` and `it2`][None]]
[[`iterator::template equal_to<It1, It2>::type`][The distance between iterators of type `It1` and `It2`][`boost::same_type<It1, It2>::type`]]
[[`iterator::template equal_to<It1, It2>::call(it1, it2)`][The distance between iterators `it1` and `it2`][`boost::same_type<It1, It2>::type()`]]
]

[heading Header]

    #include <boost/fusion/iterator/iterator_facade.hpp>
    #include <boost/fusion/include/iterator_facade.hpp>

[heading Example]
A full working example using __iterator_facade__ is provided in triple.cpp in the extension examples.

[endsect]

[endsect]