1[/
2    Copyright 2010 Neil Groves
3    Distributed under the Boost Software License, Version 1.0.
4    (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
5/]
6[section:indexed indexed]
7
8[table
9    [[Syntax] [Code]]
10    [[Pipe] [`rng | boost::adaptors::indexed()`]]
11    [[Pipe] [`rng | boost::adaptors::indexed(start_index)`]]
12    [[Function] [`boost::adaptors::index(rng)`]]
13    [[Function] [`boost::adaptors::index(rng, start_index)`]]
14]
15
16[heading Description]
17The index within each returned `boost::range::index_value` is equal to
18`start_index` + the offset of the element from the beginning of the range. In
19the versions of the functions that omit `start_index` the starting index is
20taken to be `0`.
21
22* [*Purpose:] Adapt `rng` to return elements that have the corresponding value
23from `rng` and a numeric index.
24* [*Returns:] A range adapted to return both the element and the associated
25index. The returned range has elements of type:
26
27``
28boost::range::index_value<
29    typename boost::range_reference<decltype(rng)>::type,
30    typename boost::range_difference<decltype(rng)>::type
31>
32``
33
34The synopsis of index_value is as follows:
35``
36template<class T, class Indexable=std::ptrdiff_t>
37class index_value : public boost::tuple<Indexable, T>
38{
39public:
40
41    typedef ...unspecified...       index_type;
42    typedef ...unspecified...       const_index_type;
43
44    typedef ...unspecified...       value_type;
45    typedef ...unspecified...       const_value_type;
46
47    // ...unspecified... constructors
48
49    index_type index();
50    const_index_type index() const;
51
52    value_type value();
53    const_value_type value() const;
54};
55``
56
57* [*Range Category:] __single_pass_range__
58* [*Range Return Type:] `boost::indexed_range<decltype(rng)>`
59* [*Returned Range Category:] The range category of `rng` if and only if `rng`
60is not a __bidirectional_range__. If `rng` is a __bidirectional_range__ then the
61returned range category is __forward_range__. The rationale for the demotion of
62__bidirectional_range__ inputs to __forward_range__ is to avoid slow calculation
63of indices for `boost::end(rng)`.
64
65[section:indexed_example indexed example]
66[import ../../../test/adaptor_test/indexed_example.cpp]
67[indexed_example]
68[endsect]
69
70This would produce the output:
71``
72Element = 10 Index = 0
73Element = 20 Index = 1
74Element = 30 Index = 2
75Element = 40 Index = 3
76Element = 50 Index = 4
77Element = 60 Index = 5
78Element = 70 Index = 6
79Element = 80 Index = 7
80Element = 90 Index = 8
81``
82[endsect]
83
84
85