indexed

| Home | Libraries | People | FAQ | More

##### indexed

Syntax | Code
--- | ---
Pipe | `rng | boost::adaptors::indexed()`
Pipe | `rng | boost::adaptors::indexed(start_index)`
Function | `boost::adaptors::index(rng)`
Function | `boost::adaptors::index(rng, start_index)`

###### Description

The index within each returned `boost::range::index_value` is equal to `start_index` + the offset of the element from the beginning of the range. In the versions of the functions that omit `start_index` the starting index is taken to be `0`.

- Purpose: Adapt `rng` to return elements that have the corresponding value from `rng` and a numeric index.
- Returns: A range adapted to return both the element and the associated index. The returned range has elements of type:

    boost::range::index_value<
        typename boost::range_reference<decltype(rng)>::type,
        typename boost::range_difference<decltype(rng)>::type
    >

The synopsis of index_value is as follows:

    template<class T, class Indexable=std::ptrdiff_t>
    class index_value : public boost::tuple<Indexable, T>
    {
    public:

        typedef ...unspecified...       index_type;
        typedef ...unspecified...       const_index_type;

        typedef ...unspecified...       value_type;
        typedef ...unspecified...       const_value_type;

        // ...unspecified... constructors

        index_type index();
        const_index_type index() const;

        value_type value();
        const_value_type value() const;
    };

- Range Category: Single Pass Range
- Range Return Type: `boost::indexed_range<decltype(rng)>`
- Returned Range Category: The range category of `rng` if and only if `rng` is not a Bidirectional Range. If `rng` is a Bidirectional Range then the returned range category is Forward Range. The rationale for the demotion of Bidirectional Range inputs to Forward Range is to avoid slow calculation of indices for `boost::end(rng)`.

###### indexed example

    #include <boost/range/adaptor/indexed.hpp>
    #include <boost/assign.hpp>
    #include <iterator>
    #include <iostream>
    #include <vector>

    int main(int argc, const char* argv[])
    {
        using namespace boost::assign;
        using namespace boost::adaptors;

        std::vector<int> input;
        input += 10,20,30,40,50,60,70,80,90;

        for (const auto& element : input | indexed(0))
        {
            std::cout << "Element = " << element.value()
                      << " Index = " << element.index()
                      << std::endl;
        }

        return 0;
    }

This would produce the output:

    Element = 10 Index = 0
    Element = 20 Index = 1
    Element = 30 Index = 2
    Element = 40 Index = 3
    Element = 50 Index = 4
    Element = 60 Index = 5
    Element = 70 Index = 6
    Element = 80 Index = 7
    Element = 90 Index = 8