ceph/src/boost/libs/range/doc/reference/adaptors/indexed.qbk

   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]
  17 The 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
  19 the versions of the functions that omit `start_index` the starting index is
  20 taken to be `0`.
  21
  22 * [*Purpose:] Adapt `rng` to return elements that have the corresponding value
  23 from `rng` and a numeric index.
  24 * [*Returns:] A range adapted to return both the element and the associated
  25 index. The returned range has elements of type:
  26
  27 ``
  28 boost::range::index_value<
  29     typename boost::range_reference<decltype(rng)>::type,
  30     typename boost::range_difference<decltype(rng)>::type
  31 >
  32 ``
  33
  34 The synopsis of index_value is as follows:
  35 ``
  36 template<class T, class Indexable=std::ptrdiff_t>
  37 class index_value : public boost::tuple<Indexable, T>
  38 {
  39 public:
  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`
  60 is not a __bidirectional_range__. If `rng` is a __bidirectional_range__ then the
  61 returned range category is __forward_range__. The rationale for the demotion of
  62 __bidirectional_range__ inputs to __forward_range__ is to avoid slow calculation
  63 of 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
  70 This would produce the output:
  71 ``
  72 Element = 10 Index = 0
  73 Element = 20 Index = 1
  74 Element = 30 Index = 2
  75 Element = 40 Index = 3
  76 Element = 50 Index = 4
  77 Element = 60 Index = 5
  78 Element = 70 Index = 6
  79 Element = 80 Index = 7
  80 Element = 90 Index = 8
  81 ``
  82 [endsect]
  83
  84