libs/range/doc/reference/adaptors/indexed.qbk
[/
Copyright 2010 Neil Groves
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
[section:indexed indexed]
[table
[[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)`]]
]
[heading 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)`.
[section:indexed_example indexed example]
[import ../../../test/adaptor_test/indexed_example.cpp]
[indexed_example]
[endsect]
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
``
[endsect]
