[ceph.git] / ceph / src / boost / libs / iterator / doc / counting_iterator.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Counting Iterator</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
<meta name="date" content="2006-09-11" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="counting-iterator">
<h1 class="title">Counting Iterator</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>David Abrahams, Jeremy Siek, Thomas Witt</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
<tr><th class="docinfo-name">Organization:</th>
<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport
Railway Operation and Construction</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2006-09-11</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
</tbody>
</table>
<!-- 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) -->
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">abstract:</th><td class="field-body"><p class="first">How would you fill up a vector with the numbers zero
through one hundred using <tt class="docutils literal"><span class="pre">std::copy()</span></tt>?  The only iterator
operation missing from builtin integer types is an
<tt class="docutils literal"><span class="pre">operator*()</span></tt> that returns the current value of the integer.
The counting iterator adaptor adds this crucial piece of
functionality to whatever type it wraps.  One can use the
counting iterator adaptor not only with integer types, but with
any incrementable type.</p>
<!-- Copyright David Abrahams 2006. 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) -->
<p class="last"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> adapts an object by adding an <tt class="docutils literal"><span class="pre">operator*</span></tt> that
returns the current value of the object. All other iterator operations
are forwarded to the adapted object.</p>
</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#counting-iterator-synopsis" id="id2"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> synopsis</a></li>
<li><a class="reference internal" href="#counting-iterator-requirements" id="id3"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>
<li><a class="reference internal" href="#counting-iterator-models" id="id4"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models</a></li>
<li><a class="reference internal" href="#counting-iterator-operations" id="id5"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> operations</a></li>
<li><a class="reference internal" href="#example" id="id6">Example</a></li>
</ul>
</div>
<div class="section" id="counting-iterator-synopsis">
<h1><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> synopsis</a></h1>
<!-- Copyright David Abrahams 2006. 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) -->
<pre class="literal-block">
template &lt;
    class Incrementable
  , class CategoryOrTraversal = use_default
  , class Difference = use_default
&gt;
class counting_iterator
{
public:
    typedef Incrementable value_type;
    typedef const Incrementable&amp; reference;
    typedef const Incrementable* pointer;
    typedef /* see below */ difference_type;
    typedef /* see below */ iterator_category;

    counting_iterator();
    counting_iterator(counting_iterator const&amp; rhs);
    explicit counting_iterator(Incrementable x);
    Incrementable const&amp; base() const;
    reference operator*() const;
    counting_iterator&amp; operator++();
    counting_iterator&amp; operator--();
private:
    Incrementable m_inc; // exposition
};
</pre>
<p>If the <tt class="docutils literal"><span class="pre">Difference</span></tt> argument is <tt class="docutils literal"><span class="pre">use_default</span></tt> then
<tt class="docutils literal"><span class="pre">difference_type</span></tt> is an unspecified signed integral
type. Otherwise <tt class="docutils literal"><span class="pre">difference_type</span></tt> is <tt class="docutils literal"><span class="pre">Difference</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">iterator_category</span></tt> is determined according to the following
algorithm:</p>
<pre class="literal-block">
if (CategoryOrTraversal is not use_default)
    return CategoryOrTraversal
else if (numeric_limits&lt;Incrementable&gt;::is_specialized)
    return <a class="reference external" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
        random_access_traversal_tag, Incrementable, const Incrementable&amp;)
else
    return <a class="reference external" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
         iterator_traversal&lt;Incrementable&gt;::type,
         Incrementable, const Incrementable&amp;)
</pre>
<dl class="docutils">
<dt>[<em>Note:</em> implementers are encouraged to provide an implementation of</dt>
<dd><tt class="docutils literal"><span class="pre">operator-</span></tt> and a <tt class="docutils literal"><span class="pre">difference_type</span></tt> that avoids overflows in
the cases where <tt class="docutils literal"><span class="pre">std::numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>
is true.]</dd>
</dl>
</div>
<div class="section" id="counting-iterator-requirements">
<h1><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> requirements</a></h1>
<p>The <tt class="docutils literal"><span class="pre">Incrementable</span></tt> argument shall be Copy Constructible and Assignable.</p>
<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to <tt class="docutils literal"><span class="pre">forward_iterator_tag</span></tt>
or <tt class="docutils literal"><span class="pre">forward_traversal_tag</span></tt>, the following must be well-formed:</p>
<pre class="literal-block">
Incrementable i, j;
++i;         // pre-increment
i == j;      // operator equal
</pre>
<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">bidirectional_iterator_tag</span></tt> or <tt class="docutils literal"><span class="pre">bidirectional_traversal_tag</span></tt>,
the following expression must also be well-formed:</p>
<pre class="literal-block">
--i
</pre>
<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
<tt class="docutils literal"><span class="pre">random_access_iterator_tag</span></tt> or <tt class="docutils literal"><span class="pre">random_access_traversal_tag</span></tt>,
the following must must also be valid:</p>
<pre class="literal-block">
counting_iterator::difference_type n;
i += n;
n = i - j;
i &lt; j;
</pre>
</div>
<div class="section" id="counting-iterator-models">
<h1><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models</a></h1>
<p>Specializations of <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> model Readable Lvalue
Iterator. In addition, they model the concepts corresponding to the
iterator tags to which their <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible.
Also, if <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt> is not <tt class="docutils literal"><span class="pre">use_default</span></tt> then
<tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models the concept corresponding to the iterator
tag <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt>.  Otherwise, if
<tt class="docutils literal"><span class="pre">numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>, then
<tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models Random Access Traversal Iterator.
Otherwise, <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models the same iterator traversal
concepts modeled by <tt class="docutils literal"><span class="pre">Incrementable</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">counting_iterator&lt;X,C1,D1&gt;</span></tt> is interoperable with
<tt class="docutils literal"><span class="pre">counting_iterator&lt;Y,C2,D2&gt;</span></tt> if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is
interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
</div>
<div class="section" id="counting-iterator-operations">
<h1><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> operations</a></h1>
<p>In addition to the operations required by the concepts modeled by
<tt class="docutils literal"><span class="pre">counting_iterator</span></tt>, <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> provides the following
operations.</p>
<p><tt class="docutils literal"><span class="pre">counting_iterator();</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Incrementable</span></tt> is Default Constructible.</td>
</tr>
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Default construct the member <tt class="docutils literal"><span class="pre">m_inc</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">counting_iterator(counting_iterator</span> <span class="pre">const&amp;</span> <span class="pre">rhs);</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Construct member <tt class="docutils literal"><span class="pre">m_inc</span></tt> from <tt class="docutils literal"><span class="pre">rhs.m_inc</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">counting_iterator(Incrementable</span> <span class="pre">x);</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Construct member <tt class="docutils literal"><span class="pre">m_inc</span></tt> from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_inc</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">counting_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">++m_inc</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">counting_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">--m_inc</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">Incrementable</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_inc</span></tt></td>
</tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. 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) -->
<pre class="literal-block">
template &lt;class Incrementable&gt;
counting_iterator&lt;Incrementable&gt; make_counting_iterator(Incrementable x);
</pre>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">counting_iterator&lt;Incrementable&gt;</span></tt>
with <tt class="docutils literal"><span class="pre">current</span></tt> constructed from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
</tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. 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) -->
</div>
<div class="section" id="example">
<h1><a class="toc-backref" href="#id6">Example</a></h1>
<p>This example fills an array with numbers and a second array with
pointers into the first array, using <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> for both
tasks. Finally <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> is used to print out the numbers
into the first array via indirection through the second array.</p>
<pre class="literal-block">
int N = 7;
std::vector&lt;int&gt; numbers;
typedef std::vector&lt;int&gt;::iterator n_iter;
std::copy(boost::counting_iterator&lt;int&gt;(0),
         boost::counting_iterator&lt;int&gt;(N),
         std::back_inserter(numbers));

std::vector&lt;std::vector&lt;int&gt;::iterator&gt; pointers;
std::copy(boost::make_counting_iterator(numbers.begin()),
          boost::make_counting_iterator(numbers.end()),
          std::back_inserter(pointers));

std::cout &lt;&lt; &quot;indirectly printing out the numbers from 0 to &quot;
          &lt;&lt; N &lt;&lt; std::endl;
std::copy(boost::make_indirect_iterator(pointers.begin()),
          boost::make_indirect_iterator(pointers.end()),
          std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;));
std::cout &lt;&lt; std::endl;
</pre>
<p>The output is:</p>
<pre class="literal-block">
indirectly printing out the numbers from 0 to 7
0 1 2 3 4 5 6
</pre>
<p>The source code for this example can be found <a class="reference external" href="../example/counting_iterator_example.cpp">here</a>.</p>
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="counting_iterator.rst">View document source</a>.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.

</div>
</body>
</html>
Commit	Line	Data
7c673cae FG	1	<?xml version="1.0" encoding="utf-8" ?>
	2	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	3	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	4	<head>
	5	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	6	<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
	7	<title>Counting Iterator</title>
	8	<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
	9	<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
	10	<meta name="date" content="2006-09-11" />
	11	<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
	12	<link rel="stylesheet" href="../../../rst.css" type="text/css" />
	13	</head>
	14	<body>
	15	<div class="document" id="counting-iterator">
	16	<h1 class="title">Counting Iterator</h1>
	17	<table class="docinfo" frame="void" rules="none">
	18	<col class="docinfo-name" />
	19	<col class="docinfo-content" />
	20	<tbody valign="top">
	21	<tr><th class="docinfo-name">Author:</th>
	22	<td>David Abrahams, Jeremy Siek, Thomas Witt</td></tr>
	23	<tr><th class="docinfo-name">Contact:</th>
	24	<td><a class="first reference external" href="mailto:dave@boost-consulting.com">dave@boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</a>, <a class="last reference external" href="mailto:witt@ive.uni-hannover.de">witt@ive.uni-hannover.de</a></td></tr>
	25	<tr><th class="docinfo-name">Organization:</th>
	26	<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
	27	Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport
	28	Railway Operation and Construction</a></td></tr>
	29	<tr><th class="docinfo-name">Date:</th>
	30	<td>2006-09-11</td></tr>
	31	<tr><th class="docinfo-name">Copyright:</th>
	32	<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
	33	</tbody>
	34	</table>
	35	<!-- Distributed under the Boost -->
	36	<!-- Software License, Version 1.0. (See accompanying -->
	37	<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
	38	<table class="docutils field-list" frame="void" rules="none">
	39	<col class="field-name" />
	40	<col class="field-body" />
	41	<tbody valign="top">
	42	<tr class="field"><th class="field-name">abstract:</th><td class="field-body"><p class="first">How would you fill up a vector with the numbers zero
	43	through one hundred using <tt class="docutils literal"><span class="pre">std::copy()</span></tt>? The only iterator
	44	operation missing from builtin integer types is an
	45	<tt class="docutils literal"><span class="pre">operator*()</span></tt> that returns the current value of the integer.
	46	The counting iterator adaptor adds this crucial piece of
	47	functionality to whatever type it wraps. One can use the
	48	counting iterator adaptor not only with integer types, but with
	49	any incrementable type.</p>
	50	<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
	51	<!-- Software License, Version 1.0. (See accompanying -->
	52	<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
	53	<p class="last"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> adapts an object by adding an <tt class="docutils literal"><span class="pre">operator*</span></tt> that
	54	returns the current value of the object. All other iterator operations
	55	are forwarded to the adapted object.</p>
	56	</td>
	57	</tr>
	58	</tbody>
	59	</table>
	60	<div class="contents topic" id="table-of-contents">
	61	<p class="topic-title first">Table of Contents</p>
	62	<ul class="simple">
	63	<li><a class="reference internal" href="#counting-iterator-synopsis" id="id2"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> synopsis</a></li>
	64	<li><a class="reference internal" href="#counting-iterator-requirements" id="id3"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>
65	<li><a class="reference internal" href="#counting-iterator-models" id="id4"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models</a></li>
66	<li><a class="reference internal" href="#counting-iterator-operations" id="id5"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> operations</a></li>
67	<li><a class="reference internal" href="#example" id="id6">Example</a></li>
68	</ul>
69	</div>
70	<div class="section" id="counting-iterator-synopsis">
71	<h1><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> synopsis</a></h1>
72	<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
73	<!-- Software License, Version 1.0. (See accompanying -->
74	<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
75	<pre class="literal-block">
76	template <
77	class Incrementable
78	, class CategoryOrTraversal = use_default
79	, class Difference = use_default
80	>
81	class counting_iterator
82	{
83	public:
84	typedef Incrementable value_type;
85	typedef const Incrementable& reference;
86	typedef const Incrementable* pointer;
87	typedef /* see below */ difference_type;
88	typedef /* see below */ iterator_category;
89
90	counting_iterator();
91	counting_iterator(counting_iterator const& rhs);
92	explicit counting_iterator(Incrementable x);
93	Incrementable const& base() const;
94	reference operator*() const;
95	counting_iterator& operator++();
96	counting_iterator& operator--();
97	private:
98	Incrementable m_inc; // exposition
99	};
100	</pre>
101	<p>If the <tt class="docutils literal"><span class="pre">Difference</span></tt> argument is <tt class="docutils literal"><span class="pre">use_default</span></tt> then
102	<tt class="docutils literal"><span class="pre">difference_type</span></tt> is an unspecified signed integral
103	type. Otherwise <tt class="docutils literal"><span class="pre">difference_type</span></tt> is <tt class="docutils literal"><span class="pre">Difference</span></tt>.</p>
104	<p><tt class="docutils literal"><span class="pre">iterator_category</span></tt> is determined according to the following
105	algorithm:</p>
106	<pre class="literal-block">
107	if (CategoryOrTraversal is not use_default)
108	return CategoryOrTraversal
109	else if (numeric_limits<Incrementable>::is_specialized)
110	return <a class="reference external" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
111	random_access_traversal_tag, Incrementable, const Incrementable&)
112	else
113	return <a class="reference external" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
114	iterator_traversal<Incrementable>::type,
115	Incrementable, const Incrementable&)
116	</pre>
117	<dl class="docutils">
118	<dt>[<em>Note:</em> implementers are encouraged to provide an implementation of</dt>
119	<dd><tt class="docutils literal"><span class="pre">operator-</span></tt> and a <tt class="docutils literal"><span class="pre">difference_type</span></tt> that avoids overflows in
120	the cases where <tt class="docutils literal"><span class="pre">std::numeric_limits<Incrementable>::is_specialized</span></tt>
121	is true.]</dd>
122	</dl>
123	</div>
124	<div class="section" id="counting-iterator-requirements">
125	<h1><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> requirements</a></h1>
126	<p>The <tt class="docutils literal"><span class="pre">Incrementable</span></tt> argument shall be Copy Constructible and Assignable.</p>
127	<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to <tt class="docutils literal"><span class="pre">forward_iterator_tag</span></tt>
128	or <tt class="docutils literal"><span class="pre">forward_traversal_tag</span></tt>, the following must be well-formed:</p>
129	<pre class="literal-block">
130	Incrementable i, j;
131	++i; // pre-increment
132	i == j; // operator equal
133	</pre>
134	<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
135	<tt class="docutils literal"><span class="pre">bidirectional_iterator_tag</span></tt> or <tt class="docutils literal"><span class="pre">bidirectional_traversal_tag</span></tt>,
136	the following expression must also be well-formed:</p>
137	<pre class="literal-block">
138	--i
139	</pre>
140	<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
141	<tt class="docutils literal"><span class="pre">random_access_iterator_tag</span></tt> or <tt class="docutils literal"><span class="pre">random_access_traversal_tag</span></tt>,
142	the following must must also be valid:</p>
143	<pre class="literal-block">
144	counting_iterator::difference_type n;
145	i += n;
146	n = i - j;
147	i < j;
148	</pre>
149	</div>
150	<div class="section" id="counting-iterator-models">
151	<h1><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models</a></h1>
152	<p>Specializations of <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> model Readable Lvalue
153	Iterator. In addition, they model the concepts corresponding to the
154	iterator tags to which their <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible.
155	Also, if <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt> is not <tt class="docutils literal"><span class="pre">use_default</span></tt> then
156	<tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models the concept corresponding to the iterator
157	tag <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt>. Otherwise, if
158	<tt class="docutils literal"><span class="pre">numeric_limits<Incrementable>::is_specialized</span></tt>, then
159	<tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models Random Access Traversal Iterator.
160	Otherwise, <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models the same iterator traversal
161	concepts modeled by <tt class="docutils literal"><span class="pre">Incrementable</span></tt>.</p>
162	<p><tt class="docutils literal"><span class="pre">counting_iterator<X,C1,D1></span></tt> is interoperable with
163	<tt class="docutils literal"><span class="pre">counting_iterator<Y,C2,D2></span></tt> if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is
164	interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
165	</div>
166	<div class="section" id="counting-iterator-operations">
167	<h1><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> operations</a></h1>
168	<p>In addition to the operations required by the concepts modeled by
169	<tt class="docutils literal"><span class="pre">counting_iterator</span></tt>, <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> provides the following
170	operations.</p>
171	<p><tt class="docutils literal"><span class="pre">counting_iterator();</span></tt></p>
172	<table class="docutils field-list" frame="void" rules="none">
173	<col class="field-name" />
174	<col class="field-body" />
175	<tbody valign="top">
176	<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Incrementable</span></tt> is Default Constructible.</td>
177	</tr>
178	<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Default construct the member <tt class="docutils literal"><span class="pre">m_inc</span></tt>.</td>
179	</tr>
180	</tbody>
181	</table>
182	<p><tt class="docutils literal"><span class="pre">counting_iterator(counting_iterator</span> <span class="pre">const&</span> <span class="pre">rhs);</span></tt></p>
183	<table class="docutils field-list" frame="void" rules="none">
184	<col class="field-name" />
185	<col class="field-body" />
186	<tbody valign="top">
187	<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Construct member <tt class="docutils literal"><span class="pre">m_inc</span></tt> from <tt class="docutils literal"><span class="pre">rhs.m_inc</span></tt>.</td>
188	</tr>
189	</tbody>
190	</table>
191	<p><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">counting_iterator(Incrementable</span> <span class="pre">x);</span></tt></p>
192	<table class="docutils field-list" frame="void" rules="none">
193	<col class="field-name" />
194	<col class="field-body" />
195	<tbody valign="top">
196	<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Construct member <tt class="docutils literal"><span class="pre">m_inc</span></tt> from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
197	</tr>
198	</tbody>
199	</table>
200	<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
201	<table class="docutils field-list" frame="void" rules="none">
202	<col class="field-name" />
203	<col class="field-body" />
204	<tbody valign="top">
205	<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_inc</span></tt></td>
206	</tr>
207	</tbody>
208	</table>
209	<p><tt class="docutils literal"><span class="pre">counting_iterator&</span> <span class="pre">operator++();</span></tt></p>
210	<table class="docutils field-list" frame="void" rules="none">
211	<col class="field-name" />
212	<col class="field-body" />
213	<tbody valign="top">
214	<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">++m_inc</span></tt></td>
215	</tr>
216	<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
217	</tr>
218	</tbody>
219	</table>
220	<p><tt class="docutils literal"><span class="pre">counting_iterator&</span> <span class="pre">operator--();</span></tt></p>
221	<table class="docutils field-list" frame="void" rules="none">
222	<col class="field-name" />
223	<col class="field-body" />
224	<tbody valign="top">
225	<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">--m_inc</span></tt></td>
226	</tr>
227	<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
228	</tr>
229	</tbody>
230	</table>
231	<p><tt class="docutils literal"><span class="pre">Incrementable</span> <span class="pre">const&</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
232	<table class="docutils field-list" frame="void" rules="none">
233	<col class="field-name" />
234	<col class="field-body" />
235	<tbody valign="top">
236	<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_inc</span></tt></td>
237	</tr>
238	</tbody>
239	</table>
240	<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
241	<!-- Software License, Version 1.0. (See accompanying -->
242	<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
243	<pre class="literal-block">
244	template <class Incrementable>
245	counting_iterator<Incrementable> make_counting_iterator(Incrementable x);
246	</pre>
247	<table class="docutils field-list" frame="void" rules="none">
248	<col class="field-name" />
249	<col class="field-body" />
250	<tbody valign="top">
251	<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">counting_iterator<Incrementable></span></tt>
252	with <tt class="docutils literal"><span class="pre">current</span></tt> constructed from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
253	</tr>
254	</tbody>
255	</table>
256	<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
257	<!-- Software License, Version 1.0. (See accompanying -->
258	<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
259	</div>
260	<div class="section" id="example">
261	<h1><a class="toc-backref" href="#id6">Example</a></h1>
262	<p>This example fills an array with numbers and a second array with
263	pointers into the first array, using <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> for both
264	tasks. Finally <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> is used to print out the numbers
265	into the first array via indirection through the second array.</p>
266	<pre class="literal-block">
267	int N = 7;
268	std::vector<int> numbers;
269	typedef std::vector<int>::iterator n_iter;
270	std::copy(boost::counting_iterator<int>(0),
271	boost::counting_iterator<int>(N),
272	std::back_inserter(numbers));
273
274	std::vector<std::vector<int>::iterator> pointers;
275	std::copy(boost::make_counting_iterator(numbers.begin()),
276	boost::make_counting_iterator(numbers.end()),
277	std::back_inserter(pointers));
278
279	std::cout << "indirectly printing out the numbers from 0 to "
280	<< N << std::endl;
281	std::copy(boost::make_indirect_iterator(pointers.begin()),
282	boost::make_indirect_iterator(pointers.end()),
283	std::ostream_iterator<int>(std::cout, " "));
284	std::cout << std::endl;
285	</pre>
286	<p>The output is:</p>
287	<pre class="literal-block">
288	indirectly printing out the numbers from 0 to 7
289	0 1 2 3 4 5 6
290	</pre>
291	<p>The source code for this example can be found <a class="reference external" href="../example/counting_iterator_example.cpp">here</a>.</p>
292	</div>
293	</div>
294	<div class="footer">
295	<hr class="footer" />
296	<a class="reference external" href="counting_iterator.rst">View document source</a>.
297	Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
298
299	</div>
300	</body>
301	</html>