fusion/doc/support.qbk

[section Support]

A couple of classes and metafunctions provide basic support for Fusion.

[section is_sequence]

[heading Description]

Metafunction that evaluates to `mpl::true_` if a certain type `T` is a 
conforming Fusion __sequence__, `mpl::false_` otherwise. This may be 
specialized to accomodate clients which provide Fusion conforming sequences.

[heading Synopsis]

    namespace traits
    {
        template <typename T>
        struct is_sequence 
        {
            typedef __unspecified__ type;
        };
    }

[heading Parameters]

[table
    [[Parameter]    [Requirement]                       [Description]]
    [[`T`]          [Any type]                          [The type to query.]]
]

[heading Expression Semantics]

    typedef traits::is_sequence<T>::type c;

[*Return type]: An __mpl_boolean_constant__.

[*Semantics]: Metafunction that evaluates to `mpl::true_` if a certain type 
`T` is a conforming Fusion sequence, `mpl::false_` otherwise.

[heading Header]

    #include <boost/fusion/support/is_sequence.hpp>

[heading Example]

    BOOST_MPL_ASSERT_NOT(( traits::is_sequence< std::vector<int> > ));
    BOOST_MPL_ASSERT_NOT(( is_sequence< int > ));
    BOOST_MPL_ASSERT(( traits::is_sequence<__list__<> > ));
    BOOST_MPL_ASSERT(( traits::is_sequence<__list__<int> > ));
    BOOST_MPL_ASSERT(( traits::is_sequence<__vector__<> > ));
    BOOST_MPL_ASSERT(( traits::is_sequence<__vector__<int> > ));

[endsect]

[section is_view]

[heading Description]

Metafunction that evaluates to `mpl::true_` if a certain type `T` is a 
conforming Fusion __view__, `mpl::false_` otherwise. A view is a 
specialized sequence that does not actually contain data. Views hold 
sequences which may be other views. In general, views are held by other 
views by value, while non-views are held by other views by reference. `is_view` 
may be specialized to accomodate clients providing Fusion conforming views.

[heading Synopsis]

    namespace traits
    {
        template <typename T>
        struct is_view 
        {
            typedef __unspecified__ type;
        };
    }

[heading Parameters]

[table
    [[Parameter]    [Requirement]                       [Description]]
    [[`T`]          [Any type]                          [The type to query.]]
]

[heading Expression Semantics]

    typedef traits::is_view<T>::type c;

[*Return type]: An __mpl_boolean_constant__.

[*Semantics]: Metafunction that evaluates to `mpl::true_` if a certain type 
`T` is a conforming Fusion view, `mpl::false_` otherwise.

[heading Header]

    #include <boost/fusion/support/is_view.hpp>

[heading Example]

    BOOST_MPL_ASSERT_NOT(( traits::is_view<std::vector<int> > ));
    BOOST_MPL_ASSERT_NOT(( traits::is_view<int> ));

    using boost::mpl::_
    using boost::is_pointer;
    typedef __vector__<int*, char, long*, bool, double> vector_type;
    typedef __filter_view__<vector_type, is_pointer<_> > filter_view_type;
    BOOST_MPL_ASSERT(( traits::is_view<filter_view_type> ));

[endsect]

[section tag_of]

[heading Description]

All conforming Fusion sequences and iterators have an associated tag type. 
The purpose of the tag is to enable __tag_dispatching__ from  __intrinsic__
functions to implementations appropriate for the type. The default implementation
of `tag_of` returns `T::fusion_tag` for a given type `T`, if such a member typedef exists.

This metafunction may be specialized to accomodate clients providing Fusion conforming sequences.

[heading Synopsis]

    namespace traits
    {
        template<typename Sequence>
        struct tag_of 
        {
            typedef __unspecified__ type;
        };
    }
[heading Parameters]

[table
    [[Parameter]    [Requirement]                       [Description]]
    [[`T`]          [Any type]                          [The type to query.]]
]

[heading Expression Semantics]

    typedef traits::tag_of<T>::type tag;

[*Return type]: Any type.

[*Semantics]: Returns the tag type associated with `T`.

[heading Header]

    #include <boost/fusion/support/tag_of.hpp>

[heading Example]

    typedef traits::is_sequence<__list__<> tag1;
    typedef traits::is_sequence<__list__<int> > tag2;
    typedef traits::is_sequence<__vector__<> > tag3;
    typedef traits::is_sequence<__vector__<int> > tag4;

    BOOST_MPL_ASSERT((boost::is_same<tag1, tag2>));
    BOOST_MPL_ASSERT((boost::is_same<tag3, tag4>));

[endsect]

[section category_of]

[heading Description]

A metafunction that establishes the conceptual classification of a particular 
__sequence__ or __iterator__ (see __iterator_concepts__ and 
__sequence_concepts__).

[heading Synopsis]

    namespace traits
    {
        template <typename T>
        struct category_of 
        {
            typedef __unspecified__ type;
        };
    }

[heading Parameters]

[table
    [[Parameter]    [Requirement]                       [Description]]
    [[`T`]          [Any type]                          [The type to query.]]
]

[heading Expression Semantics]

    typedef traits::category_of<T>::type category;

[*Return type]:

For Iterators, the return type is derived from one of:

		namespace boost { namespace fusion
		{
		    struct incrementable_traversal_tag {};
		
		    struct single_pass_traversal_tag
		        : incrementable_traversal_tag {};
		
		    struct forward_traversal_tag
		        : single_pass_traversal_tag {};
		
		    struct bidirectional_traversal_tag
		        : forward_traversal_tag {};
		
		    struct random_access_traversal_tag
		        : bidirectional_traversal_tag {};
		}}

For Sequences, the return type is derived from one of:

		namespace boost { namespace fusion
		{
		    struct incrementable_sequence_tag {};
		
		    struct single_pass_sequence_tag
		        : incrementable_sequence_tag {};
		
		    struct forward_traversal_tag
		        : single_pass_sequence_tag {};
		
		    struct bidirectional_traversal_tag
		        : forward_traversal_tag {};
		
		    struct random_access_traversal_tag
		        : bidirectional_traversal_tag {};
		}}

And optionally from:

		namespace boost { namespace fusion
		{
		    struct associative_sequence_tag {};
		}}

[*Semantics]: Establishes the conceptual classification of a particular 
__sequence__ or __iterator__.

[heading Header]

    #include <boost/fusion/support/category_of.hpp>

[heading Example]

    using boost::is_base_of;
    typedef traits::category_of<__list__<> >::type list_category;
    typedef traits::category_of<__vector__<> >::type vector_category;
    BOOST_MPL_ASSERT(( is_base_of<forward_traversal_tag, list_category> ));
    BOOST_MPL_ASSERT(( is_base_of<random_access_traversal_tag, vector_category> ));

[endsect]

[section pair]

[heading Description]

Fusion `pair` type is a half runtime pair. A half runtime pair is similar 
to a __std_pair__, but, unlike __std_pair__, the first type does not have data. 
It is used as elements in __map__s, for example.

[heading Synopsis]

    template <typename First, typename Second>
    struct pair;

    namespace result_of
    {
        template <typename First, typename Second>
        struct first;

        template <typename First, typename Second>
        struct second;

        template <typename First, typename Second>
        struct make_pair;
    }

    template <typename First, typename Second>
    typename result_of::make_pair<First,Second>::type
    make_pair(Second const &);

[heading Template parameters]

[table
    [[Parameter]    [Description]]
    [[First]        [The first type. This is purely a type. No data is held.]]
    [[Second]       [The second type. This contains data.]]
]

[variablelist Notation
    [[`P`]          [Fusion pair type]]
    [[`p`, `p2`]    [Fusion pairs]]
    [[`F`, `S`]     [Arbitrary types]]
    [[`s`]          [Value of type `S`]]
    [[`o`]          [Output stream]]
    [[`i`]          [Input stream]]
]

[heading Expression Semantics]

[table
    [[Expression]       [Semantics]]
    [[`P::first_type`]  [The type of the first template parameter, `F`, equivalent to
                        `result_of::first<P>::type`. ]]
    [[`P::second_type`] [The type of the second template parameter, `S`, equivalent to
                        `result_of::second<P>::type`. ]]
    [[`P()`]            [Default construction.]]
    [[`P(s)`]           [Construct a pair given value for the second type, `s`.]]
    [[`P(p2)`]          [Copy constructs a pair from another pair, `p2`.]]
    [[`p = p2`]         [Assigns a pair, p1, from another pair, `p2`.]]
    [[make_pair<F>(s)]  [Make a pair given the first type, `F`, and a value for 
                        the second type, `s`. The second type assumes the type of `s`]]
    [[`o << p`]         [Output `p` to output stream, `o`.]]
    [[`i >> p`]         [Input `p` from input stream, `i`.]]
    [[`p == p2`]        [Tests two pairs for equality.]]
    [[`p != p2`]        [Tests two pairs for inequality.]]
]

[heading Header]

    #include <boost/fusion/support/pair.hpp>

[heading Example]

    pair<int, char> p('X');
    std::cout << p << std::endl;
    std::cout << make_pair<int>('X') << std::endl;
    assert((p == make_pair<int>('X')));

[endsect]

[endsect]