iterator.qbk

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

Overloaded operators are provided to provide a more natural syntax for dereferencing iterators, and comparing them for equality.

[section:operator_unary_star Operator *]

[heading Description]
Dereferences an iterator.

[heading Synopsis]
    template<
        typename I
        >
    typename __result_of_deref__<I>::type operator*(__unspecified__<I> const& i);

[table Parameters
    [[Parameter]      [Requirement]    [Description]]
    [[`i`]            [Model of __forward_iterator__] [Operation's argument]]
]

[heading Expression Semantics]
    *i

[*Return type]: Equivalent to the return type of `__deref__(i)`.

[*Semantics]: Equivalent to `__deref__(i)`.

[heading Header]
    #include <boost/fusion/iterator/deref.hpp>
    #include <boost/fusion/include/deref.hpp>

[heading Example]
    typedef __vector__<int,int&> vec;

    int i(0);
    vec v(1,i);
    assert(*__begin__(v) == 1);
    assert(*__next__(__begin__(v)) == 0);
    assert(&(*__next__(__begin__(v))) == &i);

[endsect]

[section:operator_equality Operator ==]

[heading Description]
Compares 2 iterators for equality.

[heading Synopsis]
    template<
        typename I,
        typename J
        >
    __unspecified__ operator==(I const& i, J const& i);

[table Parameters
    [[Parameter]    [Requirement]   [Description]]
    [[`i`, `j`]     [Any fusion iterators] [Operation's arguments]]
]

[heading Expression Semantics]
    i == j

[*Return type]: Convertible to `bool`.

[*Semantics]: Equivalent to `__result_of_equal_to__<I,J>::value` where `I` and `J` are the types of `i` and `j` respectively.

[heading Header]
    #include <boost/fusion/iterator/equal_to.hpp>
    #include <boost/fusion/include/equal_to.hpp>

[endsect]

[section:operator_inequality Operator !=]

[heading Description]
Compares 2 iterators for inequality.

[heading Synopsis]
    template<
        typename I,
        typename J
        >
    __unspecified__ operator==(I const& i, J const& i);

[table Parameters
    [[Parameter]    [Requirement]   [Description]]
    [[`i`, `j`]     [Any fusion iterators] [Operation's arguments]]
]

[heading Expression Semantics]

[*Return type]: Convertible to `bool`.

[*Semantics]: Equivalent to `!__result_of_equal_to__<I,J>::value` where `I` and `J` are the types of `i` and `j` respectively.

[heading Header]
    #include <boost/fusion/iterator/equal_to.hpp>
    #include <boost/fusion/include/equal_to.hpp>

[endsect]

[endsect]

[section Metafunctions]

[section value_of]

[heading Description]

Returns the type stored at the position of an iterator.

[heading Synopsis]
    template<
        typename I
        >
    struct value_of
    {
        typedef __unspecified__ type;
    };

[table Parameters
    [[Parameter]    [Requirement]   [Description]]
    [[`I`]          [Model of __forward_iterator__] [Operation's argument]]
]

[heading Expression Semantics]
    __result_of_value_of__<I>::type

[*Return type]: Any type

[*Semantics]: Returns the type stored in a sequence at iterator position `I`.

[heading Header]
    #include <boost/fusion/iterator/value_of.hpp>
    #include <boost/fusion/include/value_of.hpp>

[heading Example]
    typedef __vector__<int,int&,const int&> vec;
    typedef __result_of_begin__<vec>::type first;
    typedef __result_of_next__<first>::type second;
    typedef __result_of_next__<second>::type third;

    BOOST_MPL_ASSERT((boost::is_same<__result_of_value_of__<first>::type, int>));
    BOOST_MPL_ASSERT((boost::is_same<__result_of_value_of__<second>::type, int&>));
    BOOST_MPL_ASSERT((boost::is_same<__result_of_value_of__<third>::type, const int&>));

[endsect]

[section deref]

[heading Description]
Returns the type that will be returned by dereferencing an iterator.

[heading Synposis]
    template<
        typename I
        >
    struct deref
    {
        typedef __unspecified__ type;
    };

[table Parameters
    [[Parameter] [Requirement]                   [Description]]
    [[`I`]       [Model of __forward_iterator__] [Operation's argument]]
]

[heading Expression Semantics]
    __result_of_deref__<I>::type

[*Return type]: Any type

[*Semantics]: Returns the result of dereferencing an iterator of type `I`.

[heading Header]
    #include <boost/fusion/iterator/deref.hpp>
    #include <boost/fusion/include/deref.hpp>

[heading Example]
    typedef __vector__<int,int&> vec;
    typedef const vec const_vec;
    typedef __result_of_begin__<vec>::type first;
    typedef __result_of_next__<first>::type second;

    typedef __result_of_begin__<const_vec>::type const_first;
    typedef __result_of_next__<const_first>::type const_second;

    BOOST_MPL_ASSERT((boost::is_same<__result_of_deref__<first>::type, int&>));
    BOOST_MPL_ASSERT((boost::is_same<__result_of_deref__<second>::type, int&>));

[endsect]

[section next]

[heading Description]
Returns the type of the next iterator in a sequence.

[heading Synposis]
    template<
        typename I
        >
    struct next
    {
        typedef __unspecified__ type;
    };

[table Parameters
    [[Parameter]    [Requirement]   [Description]]
    [[`I`]          [Model of __forward_iterator__] [Operation's argument]]
]

[heading Expression Semantics]
    __result_of_next__<I>::type

[*Return type]: A model of the same iterator concept as `I`.

[*Semantics]: Returns an iterator to the next element in the sequence after `I`.

[heading Header]
    #include <boost/fusion/iterator/next.hpp>
    #include <boost/fusion/include/next.hpp>

[heading Example]
    typedef __vector__<int,double> vec;
    typedef __result_of_next__<__result_of_begin__<vec>::type>::type second;

    BOOST_MPL_ASSERT((boost::is_same<__result_of_value_of__<second>::type, double>));

[endsect]

[section prior]

[heading Description]
Returns the type of the previous iterator in a sequence.

[heading Synopsis]
    template<
        typename I
        >
    struct prior
    {
        typedef __unspecified__ type;
    };

[table Parameters
    [[Parameter]    [Requirement]   [Description]]
    [[`I`]          [Model of __bidirectional_iterator__] [Operation's argument]]
]

[heading Expression Semantics]
    __result_of_prior__<I>::type

[*Return type]: A model of the same iterator concept as `I`.

[*Semantics]: Returns an iterator to the previous element in the sequence before `I`.

[heading Header]
    #include <boost/fusion/iterator/prior.hpp>
    #include <boost/fusion/include/prior.hpp>

[heading Example]
    typedef __vector__<int,double> vec;
    typedef __result_of_next__<__result_of_begin__<vec>::type>::type second;

    BOOST_MPL_ASSERT((boost::is_same<__result_of_value_of__<second>::type, double>));

    typedef __result_of_prior__<second>::type first;
    BOOST_MPL_ASSERT((boost::is_same<__result_of_value_of__<first>::type, int>));

[endsect]

[section equal_to]

[heading Description]
Returns a true-valued __mpl_integral_constant__ if `I` and `J` are equal.

[heading Synopsis]
    template<
        typename I,
        typename J
        >
    struct equal_to
    {
        typedef __unspecified__ type;
    };

[table Parameters
    [[Parameter]    [Requirement]   [Description]]
    [[`I`, `J`]     [Any fusion iterators] [Operation's arguments]]
]

[heading Expression Semantics]
    __result_of_equal_to__<I, J>::type

[*Return type]: A model of __mpl_integral_constant__.

[*Semantics]: Returns `boost::mpl::true_` if `I` and `J` are iterators to the same position. Returns `boost::mpl::false_` otherwise.

[heading Header]
    #include <boost/fusion/iterator/equal_to.hpp>
    #include <boost/fusion/include/equal_to.hpp>

[heading Example]
    typedef __vector__<int,double> vec;
    typedef __result_of_begin__<vec>::type first;
    typedef __result_of_end__<vec>::type last;
    BOOST_MPL_ASSERT((__result_of_equal_to__<first, first>));
    BOOST_MPL_ASSERT_NOT((__result_of_equal_to__<first,last>));

[endsect]

[section distance]

[heading Description]
Returns the distance between two iterators.

[heading Synopsis]
    template<
        typename I,
        typename J
        >
    struct distance
    {
        typedef __unspecified__ type;
    };

[table Parameters
    [[Parameter]    [Requirement]   [Description]]
    [[`I`, `J`]          [Models of __forward_iterator__ into the same sequence] [The start and end points of the distance to be measured]]
]

[heading Expression Semantics]
    __result_of_distance__<I, J>::type

[*Return type]: A model of __mpl_integral_constant__.

[*Semantics]: Returns the distance between iterators of types `I` and `J`.

[heading Header]
    #include <boost/fusion/iterator/distance.hpp>
    #include <boost/fusion/include/distance.hpp>

[heading Example]
    typedef __vector__<int,double,char> vec;
    typedef __result_of_begin__<vec>::type first;
    typedef __result_of_next__<first>::type second;
    typedef __result_of_next__<second>::type third;
    typedef __result_of_distance__<first,third>::type dist;

    BOOST_MPL_ASSERT_RELATION(dist::value, ==, 2);

[endsect]

[section advance]

[heading Description]
Moves an iterator a specified distance.

[heading Synopsis]
    template<
        typename I,
        typename M
        >
    struct advance
    {
        typedef __unspecified__ type;
    };

[table Parameters
    [[Parameter]    [Requirement]   [Description]]
    [[`I`]          [Model of __forward_iterator__] [Iterator to move relative to]]
    [[`M`]          [Model of __mpl_integral_constant__] [Number of positions to move]]
]

[heading Expression Semantics]
    __result_of_advance__<I,M>::type

[*Return type]: A model of the same iterator concept as `I`.

[*Semantics]: Returns an iterator a distance `M` from `I`. If `I` is a __bidirectional_iterator__ then `M` may be negative.

[heading Header]
    #include <boost/fusion/iterator/advance.hpp>
    #include <boost/fusion/include/advance.hpp>

[heading Example]
    typedef __vector__<int,double,char> vec;
    typedef __result_of_begin__<vec>::type first;
    typedef __result_of_next__<first>::type second;
    typedef __result_of_next__<second>::type third;

    BOOST_MPL_ASSERT((__result_of_equal_to__<__result_of_advance__<first, boost::mpl::int_<2> >::type, third>));

[endsect]

[section advance_c]

[heading Description]
Moves an iterator by a specified distance.

[heading Synopsis]
    template<
        typename I,
        int N
        >
    struct advance_c
    {
        typedef __unspecified__ type;
    };

[table Parameters
    [[Parameter]    [Requirement]   [Description]]
    [[`I`]          [Model of __forward_iterator__] [Iterator to move relative to]]
    [[`N`]          [Integer constant] [Number of positions to move]]
]

[heading Expression Semantics]
    __result_of_advance_c__<I, N>::type

[*Return type]: A model of the same iterator concept as `I`.

[*Semantics]: Returns an iterator a distance `N` from `I`. If `I` is a __bidirectional_iterator__ then `N` may be negative. Equivalent to `__result_of_advance__<I, boost::mpl::int_<N> >::type`.

[heading Header]
    #include <boost/fusion/iterator/advance.hpp>
    #include <boost/fusion/include/advance.hpp>

[heading Example]
    typedef __vector__<int,double,char> vec;
    typedef __result_of_begin__<vec>::type first;
    typedef __result_of_next__<first>::type second;
    typedef __result_of_next__<second>::type third;

    BOOST_MPL_ASSERT((__result_of_equal_to__<__result_of_advance_c__<first, 2>::type, third>));

[endsect]

[endsect]

[endsect]