algorithm.qbk

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

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

[heading Example]
    const __vector__<int, double, char> vec(1, 2.0, 'c');
    assert(__erase__(vec, __next__(__begin__(vec))) == __make_vector__(1, 'c'));
    assert(__erase__(vec, __next__(__begin__(vec)), __end__(vec)) == __make_vector__(1));

[endsect]

[section erase_key]

[heading Description]
For an __associative_sequence__ `seq`, returns a __forward_sequence__ containing all the
elements of the original except those with a given key.

[heading Synposis]
    template<
        typename Key,
        typename Sequence
        >
    typename result_of::erase_key<Sequence const, Key>::type erase_key(Sequence const& seq);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq`][A model of __associative_sequence__][Operation's argument]]
    [[`Key`][Any type][Key to erase]]
]

[heading Expression Semantics]
    __erase_key__<Key>(seq);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence, containing all the elements of `seq`, except those with key `Key`.

[heading Complexity]
Constant. Returns a view which is lazily evaluated.

[heading Header]

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

[heading Example]
    assert(__erase_key__<int>(__make_map__<int, long>('a', 'b')) == __make_map__<long>('b'));

[endsect]

[section insert]

[heading Description]
Returns a new sequence with all the elements of the original, an a new element inserted the
position described by a given iterator.

[heading Synposis]
    template<
        typename Sequence,
        typename Pos,
        typename T
        >
    __unspecified__ insert(Sequence const& seq, Pos const& pos, T const& t);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq`][A model of __forward_sequence__][Operation's argument]]
    [[`pos`][A model of __forward_iterator__][The position to insert at]]
    [[`t`][Any type][The value to insert]]
]

[heading Expression Semantics]
    __insert__(seq, p, t);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence, containing all the elements of `seq`, in their original order, and a new element with the
type and value of `t` inserted at iterator `pos`.

[heading Complexity]
Constant. Returns a view which is lazily evaluated.

[heading Header]

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

[heading Example]
    const __vector__<int,int> vec(1,2);
    assert(__insert__(vec, __next__(__begin__(vec)), 3) == __make_vector__(1,3,2));

[endsect]

[section insert_range]

[heading Description]
Returns a new sequence with another sequence inserted at a specified iterator.

[heading Synposis]
    template<
        typename Sequence,
        typename Pos,
        typename Range
        >
    typename __result_of_insert_range__<Sequence const, Pos, Range>::type insert_range(
        Sequence const& seq, Pos const& pos, Range const& range);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq`][A model of __forward_sequence__][Operation's argument]]
    [[`pos`][A model of __forward_iterator__][The position to insert at]]
    [[`range`][A model of __forward_sequence__][Range to insert]]
]

[heading Expression Semantics]
    __insert__(seq, pos, range);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence, containing all the elements of `seq`, and the elements of
`range` inserted at iterator `pos`. All elements retaining their ordering from the orignal sequences.

[heading Complexity]
Constant. Returns a view which is lazily evaluated.

[heading Header]

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

[heading Example]
    const __vector__<int,int> vec(1,2);
    assert(__insert_range__(vec, __next__(__begin__(vec)), __make_vector__(3,4)) == __make_vector__(1,3,4,2));

[endsect]

[section join]

[heading Description]
Takes 2 sequences and returns a sequence containing the elements of the first followed by the elements of the second.

[heading Synopsis]
    template<
        typename LhSequence,
        typename RhSequence>
    typename __result_of_join__<LhSequence, RhSequence>::type join(LhSequence const& lhs, RhSequence const& rhs);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`lhs`][A model of __forward_sequence__][Operation's argument]]
    [[`rhs`][A model of __forward_sequence__][Operation's argument]]
]

[heading Expression Semantics]
    __join__(lhs, rhs);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a sequence containing all the elements of `lhs` followed by all the elements of `rhs`. The order of th elements is preserved.

[heading Complexity]
Constant. Returns a view which is lazily evaluated.

[heading Header]

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

[heading Example]
    __vector__<int,char> v1(1, 'a');
    __vector__<int,char> v2(2, 'b');
    assert(__join__(v1, v2) == __make_vector__(1,'a',2,'b'));

[endsect]

[section zip]

[heading Description]
Zips sequences together to form a single sequence, whos members are tuples of the members of the component sequences.

[heading Synopsis]
    template<
        typename Sequence1,
        typename Sequence2,
        ...
        typename SequenceN
        >
    typename __result_of_zip__<Sequence1, Sequence2, ... SequenceN>::type
    zip(Sequence1 const& seq1, Sequence2 const& seq2, ... SequenceN const& seqN);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq1` to `seqN`][Each sequence is a model of __forward_sequence__.][Operation's argument]]
]

[heading Expression Semantics]
    __zip__(seq1, seq2, ... seqN);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a sequence containing tuples of elements from sequences `seq1` to `seqN`. For example, applying zip to tuples `(1, 2, 3)` and `('a', 'b', 'c')` would return `((1, 'a'),(2, 'b'),(3, 'c'))`

[heading Complexity]
Constant. Returns a view which is lazily evaluated.

[heading Header]

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

[heading Example]
    __vector__<int,char> v1(1, 'a');
    __vector__<int,char> v2(2, 'b');
    assert(__zip__(v1, v2) == __make_vector__(__make_vector__(1, 2),__make_vector__('a', 'b'));

[endsect]

[section pop_back]

[heading Description]
Returns a new sequence, with the last element of the original removed.

[heading Synopsis]
    template<
        typename Sequence
        >
    typename __result_of_pop_back__<Sequence const>::type pop_back(Sequence const& seq);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq`][A model of __forward_sequence__][Operation's argument]]
]

[heading Expression Semantics]
    __pop_back__(seq);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence containing all the elements of `seq`, except the last element. The elements in the new sequence are in the same order as they were in `seq`.

[heading Complexity]
Constant. Returns a view which is lazily evaluated.

[heading Header]

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

[heading Example]
    assert(___pop_back__(__make_vector__(1,2,3)) == __make_vector__(1,2));

[endsect]

[section pop_front]

[heading Description]
Returns a new sequence, with the first element of the original removed.

[heading Synopsis]
    template<
        typename Sequence
        >
    typename __result_of_pop_front__<Sequence const>::type pop_front(Sequence const& seq);


[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq`][A model of __forward_sequence__][Operation's argument]]
]

[heading Expression Semantics]
    __pop_front__(seq);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence containing all the elements of `seq`, except the first element. The elements in the new sequence are in the same order as they were in `seq`.

[heading Complexity]
Constant. Returns a view which is lazily evaluated.

[heading Header]

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

[heading Example]
    assert(__pop_front__(__make_vector__(1,2,3)) == __make_vector__(2,3));

[endsect]

[section push_back]

[heading Description]
Returns a new sequence with an element added at the end.

[heading Synopsis]
    template<
        typename Sequence,
        typename T
        >
    typename __result_of_push_back__<Sequence, T>::type push_back(
        Sequence const& seq, T const& t);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq`][A model of __forward_sequence__][Operation's argument]]
    [[`t`][Any type][The value to add to the end]]
]

[heading Expression Semantics]
    __push_back__(seq, t);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence, containing all the elements of `seq`, and new element `t` appended to the end. The elements are in the same order as they were in `seq`.

[heading Complexity]
Constant. Returns a view which is lazily evaluated.

[heading Header]

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

[heading Example]
    assert(__push_back__(__make_vector__(1,2,3),4) == __make_vector__(1,2,3,4));

[endsect]

[section push_front]

[heading Description]
Returns a new sequence with an element added at the beginning.

[heading Synopsis]
    template<
        typename Sequence,
        typename T
        >
    typename __result_of_push_front__<Sequence, T>::type push_front(
        Sequence const& seq, T const& t);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq`][A model of __forward_sequence__][Operation's argument]]
    [[`t`][Any type][The value to add to the beginning]]
]

[heading Expression Semantics]
    __push_back__(seq, t);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence, containing all the elements of `seq`, and new element `t` appended to the beginning. The elements are in the same order as they were in `seq`.

[heading Complexity]
Constant. Returns a view which is lazily evaluated.

[heading Header]

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

[heading Example]
    assert(__push_front__(__make_vector__(1,2,3),0) == __make_vector__(0,1,2,3));

[endsect]

[endsect]

[section Metafunctions]

[section filter]

[heading Description]
Returns the result type of __filter__ given the sequence type and type to retain.

[heading Synopsis]
    template<
        typename Sequence,
        typename T
        >
    struct filter
    {
        typedef __unspecified__ type;
    };

[table Parameter
    [[Parameter] [Requirement] [Description]]
    [[`Sequence`][A model of __forward_sequence__] [Operation's argument]]
    [[`T`][Any type][Type to retain]]
]

[heading Expression Semantics]
    __result_of_filter__<Sequence, T>::type

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a sequence containing the elements of `Sequence` that are of type `T`. Equivalent to `__result_of_filter_if__<Sequence, boost::is_same<mpl::_, T> >::type`.

[heading Complexity]
Constant.

[heading Header]

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

[endsect]

[section filter_if]

[heading Description]
Returns the result type of __filter_if__ given the sequence and unary __mpl_lambda_expression__ predicate type.

[heading Synopsis]
    template<
        typename Sequence,
        typename Pred
        >
    struct filter_if
    {
        typedef __unspecified__ type;
    };

[table Parameter
    [[Parameter] [Requirement] [Description]]
    [[`Sequence`][A model of __forward_sequence__] [Operation's argument]]
    [[`Pred`][A unary __mpl_lambda_expression__][Type to retain]]
]

[heading Expression Semantics]
    __result_of_filter_if__<Sequence, Pred>::type

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a sequence containing the elements of `Sequence` for which `Pred` evaluates to `boost::mpl::true_`.

[heading Complexity]
Constant.

[heading Header]

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

[endsect]

[section transform]

[heading Description]
For a sequence `seq` and function object or function pointer `f`, `transform` returns a new sequence
with elements created by applying `f(e)` to each element of `e` of `seq`.

[heading Unary version synopsis]
    template<
        typename Sequence,
        typename F
        >
    typename __result_of_transform__<Sequence const, F>::type transform(
        Sequence const& seq, F f);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq`][A model of __forward_sequence__][Operation's argument]]
    [[`f`][`f(e)` is a valid expression for each element `e` of `seq`. `__boost_result_of_call__<F(E)>::type` is the return type of `f` when called with a value of each element type `E`.][Transformation function]]
]

[heading Expression Semantics]