algorithm.qbk

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

[heading Header]

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

[endsect]

[endsect]

[endsect]

[section Transformation]
The transformation algorithms create new sequences out of existing sequences by performing some sort of transformation. In reality the new sequences are views onto the data in the original sequences.

[note As the transformation algorithms return views onto their input arguments,
it is important that the lifetime of the input arguments is greater than the
period during which you wish to use the results.]

[heading Header]

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

[section Functions]

[section filter]

[heading Description]
For a given sequence, filter returns a new sequences containing only the elements of a specified type.

[heading Synopsis]
    template<
        typename T,
        typename Sequence
        >
    typename __result_of_filter__<Sequence const, T>::type filter(Sequence const& seq);

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

[heading Expression Semantics]
    __filter__<T>(seq);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a sequence containing all the elements of `seq` of type `T`.
Equivalent to `__filter_if__<boost::same_type<_, T> >(seq)`.

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

[heading Header]

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

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

[endsect]

[section filter_if]

[heading Description]
For a given sequence, __filter_if__ returns a new sequences containing
only the elements with types for which a given __mpl_lambda_expression__ evaluates to `boost::mpl::true_`.

[heading Synopsis]
    template<
        typename Pred,
        typename Sequence
        >
    typename __result_of_filter_if__<Sequence const, Pred>::type filter_if(Sequence const& seq);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq`][A model of __forward_sequence__][Operation's argument]]
    [[`Pred`][A unary __mpl_lambda_expression__][The predicate to filter by]]
]

[heading Expression Semantics]
    __filter_if__<Pred>(seq);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a sequence containing all the elements of `seq` with types for which `Pred` evaluates
to `boost::mpl::true_`. The order of the retained elements is the same as in the original sequence.

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

[heading Header]

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

[heading Example]
    const __vector__<int,int,double,double> vec(1,2,3.0,4.0);
    assert(__filter_if__<is_integral<mpl::_> >(vec) == __make_vector__(1,2));

[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]
    __transform__(seq, f);

[*Return type]: A model of __forward_sequence__

[*Semantics]: Returns a new sequence, containing the return values of `f(e)` for each element `e` within `seq`.

[heading Binary version synopsis]
    template<
        typename Sequence1,
        typename Sequence2,
        typename F
        >
    typename __result_of_transform__<Sequence1 const, Sequence2 const, F>::type transform(
        Sequence1 const& seq1, Sequence2 const& seq2, F f);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq1`][A model of __forward_sequence__][Operation's argument]]
    [[`seq2`][A model of __forward_sequence__][Operation's argument]]
    [[`f`][`f(e1,e2)` is a valid expression for each pair of elements `e1` of `seq1` and `e2` of `seq2`. `__boost_result_of_call__<F(E1,E2)>::type` is the return type of `f` when called with elements of type `E1` and `E2`][Transformation function]]
]

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence, containing the return values of `f(e1, e2)` for each pair of elements `e1` and `e2` within `seq1` and `seq2` respectively.

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

[heading Header]

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

[heading Example]
    struct triple
    {
        typedef int result_type;

        int operator()(int t) const
        {
            return t * 3;
        };
    };
    ...
    assert(__transform__(__make_vector__(1,2,3), triple()) == __make_vector__(3,6,9));

[endsect]

[section replace]

[heading Description]
Replaces each value within a sequence of a given type and value with a new value.

[heading Synopsis]
    template<
        typename Sequence,
        typename T
        >
    typename __result_of_replace__<Sequence const, T>::type replace(
        Sequence const& seq, T const& old_value, T const& new_value);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq`][A model of __forward_sequence__, `e == old_value` is a valid expression, convertible to `bool`, for each element `e` in `seq` with type convertible to `T`][Operation's argument]]
    [[`old_value`][Any type][Value to replace]]
    [[`new_value`][Any type][Replacement value]]
]

[heading Expression Semantics]
    __replace__(seq, old_value, new_value);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence with all the values of `seq` with `new_value` assigned to elements with the same type and equal to `old_value`.

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

[heading Header]

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

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

[endsect]

[section replace_if]

[heading Description]
Replaces each element of a given sequence for which an unary function object evaluates to `true` replaced with
a new value.

[heading Synopsis]
    template<
        typename Sequence,
        typename F,
        typename T>
    typename __result_of_replace_if__<Sequence const, F, T>::type replace_if(
        Sequence const& seq, F f, T const& new_value);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq`][A model of __forward_sequence__][Operation's argument]]
    [[`f`][A function object for which `f(e)` is a valid expression, convertible to `bool`, for each element `e` in `seq`][Operation's argument]]
    [[`new_value`][Any type][Replacement value]]
]

[heading Expression Semantics]
    __replace_if__(seq, f, new_value);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence with all the elements of `seq`,
with `new_value` assigned to each element for which `f` evaluates to `true`.

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

[heading Header]

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

[heading Example]
    struct odd
    {
        template<typename T>
        bool operator()(T t) const
        {
            return t % 2;
        }
    };
    ...
    assert(__replace_if__(__make_vector__(1,2), odd(), 3) == __make_vector__(3,2));

[endsect]

[section remove]

[heading Description]
Returns a new sequence, with all the elements of the original sequence, except those of a given type.

[heading Synopsis]
    template<
        typename T,
        typename Sequence
        >
    typename __result_of_remove__<Sequence const, T>::type replace(Sequence const& seq);

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

[heading Expression Semantics]
    __remove__<T>(seq);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence, containing all the elements of `seq`, in their original order, except
those of type `T`. Equivalent to `__remove_if__<boost::is_same<_,T> >(seq)`.

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

[heading Header]

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

[heading Example]
    const __vector__<int,double> vec(1,2.0);
    assert(__remove__<double>(vec) == __make_vector__(1));

[endsect]

[section remove_if]

[heading Description]
Returns a new sequence, containing all the elements of the original except those where a given unary
function object evaluates to `true`.

[heading Synopsis]
    template<
        typename Pred,
        typename Sequence
        >
    typename __result_of_remove_if__<Sequence const, Pred>::type remove_if(Sequence const& seq);

[table Parameters
    [[Parameter][Requirement][Description]]
    [[`seq`][A model of __forward_sequence__][Operation's argument]]
    [[`Pred`][A model of unary __mpl_lambda_expression__][Removal predicate]]
]

[heading Expression Semantics]
    __remove_if__<Pred>(seq);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence, containing all the elements of `seq`, in their original order, except
those elements with types for which `Pred` evaluates to `boost::mpl::true_`.
Equivalent to `__filter__<boost::mpl::not_<Pred> >(seq)`.

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

[heading Header]

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

[heading Example]
    const __vector__<int,double> vec(1,2.0);
    assert(__remove_if__<is_floating_point<mpl::_> >(vec) == __make_vector__(1));

[endsect]

[section reverse]

[heading Description]
Returns a new sequence with the elements of the original in reverse order.

[heading Synposis]
    template<
        typename Sequence
        >
    typename __result_of_reverse__<Sequence const>::type reverse(Sequence const& seq);

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

[heading Expression Semantics]
    __reverse__(seq);

[*Return type]: A model of __bidirectional_sequence__.

[*Semantics]: Returns a new sequence containing all the elements of `seq` in reverse order.

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

[heading Header]

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

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

[endsect]

[section clear]

[heading Description]
__clear__ returns an empty sequence.

[heading Synposis]
    template<
        typename Sequence
        >
    typename __result_of_clear__<Sequence const>::type clear(Sequence const& seq);

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

[heading Expression Semantics]
    __clear__(seq);

[*Return type]: A model of __forward_sequence__.

[*Expression Semantics]: Returns a sequence with no elements.

[heading Complexity]
Constant.

[heading Header]

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

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

[endsect]

[section erase]

[heading Description]
Returns a new sequence, containing all the elements of the original except those at a specified iterator, or
between two iterators.

[heading Synposis]
    template<
        typename Sequence,
        typename First
        >
    typename __result_of_erase__<Sequence const, First>::type erase(
        Sequence const& seq, First const& it1);

    template<
        typename Sequence,
        typename First,
        typename Last
        >
    typename __result_of_erase__<Sequence const, First, Last>::type erase(
        Sequence const& seq, First const& it1, Last const& it2);

[table Parameters
    [[Parameters][Requirement][Description]]
    [[`seq`][A model of __forward_sequence__][Operation's argument]]
    [[`it1`][A model of __forward_iterator__][Iterator into `seq`]]
    [[`it2`][A model of __forward_iterator__][Iterator into `seq` after `it1`]]
]

[heading Expression Semantics]
    __erase__(seq, pos);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence, containing all the elements of `seq` except the element at `pos`.

    __erase__(seq, first, last);

[*Return type]: A model of __forward_sequence__.

[*Semantics]: Returns a new sequence, with all the elements of `seq`, in their original order, except those
in the range [`first`,`last`).

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

[heading Header]