boostorg/iterator
1
0
Fork 1
mirror of https://github.com/boostorg/iterator.git synced 2025-07-29 12:27:33 +02:00
Code Issues Packages Projects Releases Wiki Activity

improvements to the spec

Browse Source 
[SVN r21604]
This commit is contained in:
Jeremy Siek
2004-01-11 17:46:42 +00:00
parent 0db07e9455
commit 2271aceab8
3 changed files with 156 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
doc/reverse_iterator.html
View File

@ -3,13 +3,13 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.1: http://docutils.sourceforge.net/" /> <meta name="generator" content="Docutils 0.3.0: http://docutils.sourceforge.net/" />
<title>Reverse Iterator</title> <title>Reverse Iterator</title>
<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" /> <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="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
<meta name="date" content="2003-09-14" /> <meta name="date" content="2003-09-14" />
<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" /> <meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
<link rel="stylesheet" href="../../../rst.css" type="text/css" /> <link rel="stylesheet" href="default.css" type="text/css" />
</head> </head>
<body> <body>
<div class="document" id="reverse-iterator"> <div class="document" id="reverse-iterator">
@ -47,15 +47,19 @@ invoking <tt class="literal"><span class="pre">operator--()</span></tt> moves th
<div class="contents topic" id="table-of-contents"> <div class="contents topic" id="table-of-contents">
<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p> <p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple"> <ul class="simple">
<li><a class="reference" href="#reverse-iterator-requirements" id="id1" name="id1"><tt class="literal"><span class="pre">reverse_iterator</span></tt> requirements</a></li> <li><a class="reference" href="#reverse-iterator-synopsis" id="id1" name="id1"><tt class="literal"><span class="pre">reverse_iterator</span></tt> synopsis</a></li>
<li><a class="reference" href="#reverse-iterator-requirements" id="id2" name="id2"><tt class="literal"><span class="pre">reverse_iterator</span></tt> requirements</a></li>
<li><a class="reference" href="#reverse-iterator-models" id="id3" name="id3"><tt class="literal"><span class="pre">reverse_iterator</span></tt> models</a></li>
<li><a class="reference" href="#reverse-iterator-operations" id="id4" name="id4"><tt class="literal"><span class="pre">reverse_iterator</span></tt> operations</a></li>
<li><a class="reference" href="#example" id="id5" name="id5">Example</a></li>
</ul> </ul>
</div> </div>
<div class="section" id="reverse-iterator-synopsis">
<h1><a class="toc-backref" href="#id1" name="reverse-iterator-synopsis"><tt class="literal"><span class="pre">reverse_iterator</span></tt> synopsis</a></h1>
<pre class="literal-block"> <pre class="literal-block">
template &lt;class Iterator&gt; template &lt;class Iterator&gt;
class reverse_iterator : class reverse_iterator
public iterator_adaptor&lt; reverse_iterator&lt;Iterator&gt;, Iterator &gt;
{ {
friend class iterator_core_access;
public: public:
reverse_iterator() {} reverse_iterator() {}
explicit reverse_iterator(Iterator x) ; explicit reverse_iterator(Iterator x) ;
@ -65,33 +69,49 @@ public:
reverse_iterator&lt;OtherIterator&gt; const&amp; r reverse_iterator&lt;OtherIterator&gt; const&amp; r
, typename enable_if_convertible&lt;OtherIterator, Iterator&gt;::type* = 0 // exposition , typename enable_if_convertible&lt;OtherIterator, Iterator&gt;::type* = 0 // exposition
); );
reference operator*() const;
private: // as-if specification reverse_iterator&amp; operator++();
typename reverse_iterator::reference dereference() const { return *prior(this-&gt;base()); } private:
Iterator current; // exposition
void increment() { --this-&gt;base_reference(); }
void decrement() { ++this-&gt;base_reference(); }
void advance(typename reverse_iterator::difference_type n)
{
this-&gt;base_reference() += -n;
}
template &lt;class OtherIterator&gt;
typename reverse_iterator::difference_type
distance_to(reverse_iterator&lt;OtherIterator&gt; const&amp; y) const
{
return this-&gt;base_reference() - y.base();
}
}; };
</pre> </pre>
</div>
<div class="section" id="reverse-iterator-requirements"> <div class="section" id="reverse-iterator-requirements">
<h1><a class="toc-backref" href="#id1" name="reverse-iterator-requirements"><tt class="literal"><span class="pre">reverse_iterator</span></tt> requirements</a></h1> <h1><a class="toc-backref" href="#id2" name="reverse-iterator-requirements"><tt class="literal"><span class="pre">reverse_iterator</span></tt> requirements</a></h1>
<p>The base <tt class="literal"><span class="pre">Iterator</span></tt> must be a model of Bidirectional Traversal <p>The base <tt class="literal"><span class="pre">Iterator</span></tt> must be a model of Bidirectional Traversal
Iterator. The resulting <tt class="literal"><span class="pre">reverse_iterator</span></tt> will be a model of the Iterator and Readable Iterator.</p>
most refined standard traversal and access concepts that are modeled </div>
by <tt class="literal"><span class="pre">Iterator</span></tt>.</p> <div class="section" id="reverse-iterator-models">
<h1><a class="toc-backref" href="#id3" name="reverse-iterator-models"><tt class="literal"><span class="pre">reverse_iterator</span></tt> models</a></h1>
<p><tt class="literal"><span class="pre">reverse_iterator</span></tt> models Bidirectional Traversal Iterator and
Readable Iterator. In addition, <tt class="literal"><span class="pre">reverse_iterator</span></tt> models the same
standard iterator access concepts (if any) that the <tt class="literal"><span class="pre">Iterator</span></tt>
argument models. Also, <tt class="literal"><span class="pre">reverse_iterator</span></tt> models concepts
according to the following table.</p>
<table border class="table">
<colgroup>
<col width="35%" />
<col width="65%" />
</colgroup>
<thead valign="bottom">
<tr><th>If <tt class="literal"><span class="pre">Iterator</span></tt> models</th>
<th>then <tt class="literal"><span class="pre">reverse_iterator</span></tt> models</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Bidirectional Iterator</td>
<td>Bidirectional Iterator, Readable Lvalue Iterator,
Bidirectional Traversal Iterator</td>
</tr>
<tr><td>Mutable Bidirectional Iterator</td>
<td>Mutable Bidirectional Iterator, Writable Lvalue Iterator,
Bidirectional Traversal Iterator</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="reverse-iterator-operations">
<h1><a class="toc-backref" href="#id4" name="reverse-iterator-operations"><tt class="literal"><span class="pre">reverse_iterator</span></tt> operations</a></h1>
<p><tt class="literal"><span class="pre">reverse_iterator();</span></tt></p> <p><tt class="literal"><span class="pre">reverse_iterator();</span></tt></p>
<table class="field-list" frame="void" rules="none"> <table class="field-list" frame="void" rules="none">
<col class="field-name" /> <col class="field-name" />
@ -99,8 +119,8 @@ by <tt class="literal"><span class="pre">Iterator</span></tt>.</p>
<tbody valign="top"> <tbody valign="top">
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td> <tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>
</tr> </tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">reverse_iterator</span></tt> with a <tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">reverse_iterator</span></tt> with <tt class="literal"><span class="pre">current</span></tt>
default constructed base object.</td> default constructed.</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
@ -110,7 +130,7 @@ default constructed base object.</td>
<col class="field-body" /> <col class="field-body" />
<tbody valign="top"> <tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">reverse_iterator</span></tt> with a <tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">reverse_iterator</span></tt> with a
base object copy constructed from <tt class="literal"><span class="pre">x</span></tt>.</td> <tt class="literal"><span class="pre">current</span></tt> constructed from <tt class="literal"><span class="pre">x</span></tt>.</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
@ -131,13 +151,57 @@ reverse_iterator(
</tr> </tr>
</tbody> </tbody>
</table> </table>
<p><tt class="literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
<table class="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"></td>
</tr>
</tbody>
</table>
<pre class="literal-block">
Iterator tmp = current;
return *--tmp;
</pre>
<p><tt class="literal"><span class="pre">reverse_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
<table class="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="literal"><span class="pre">--current</span></tt></td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
</tr>
</tbody>
</table>
</div> </div>
<div class="section" id="example">
<h1><a class="toc-backref" href="#id5" name="example">Example</a></h1>
<p>The following example prints an array of characters in reverse order
using <tt class="literal"><span class="pre">reverse_iterator</span></tt>.</p>
<pre class="literal-block">
char letters_[] = &quot;hello world!&quot;;
const int N = sizeof(letters_)/sizeof(char) - 1;
typedef char* base_iterator;
base_iterator letters(letters_);
std::cout &lt;&lt; &quot;original sequence of letters:\t&quot; &lt;&lt; letters_ &lt;&lt; std::endl;
boost::reverse_iterator&lt;base_iterator&gt;
reverse_letters_first(letters + N),
reverse_letters_last(letters);
std::cout &lt;&lt; &quot;sequence in reverse order:\t&quot;;
std::copy(reverse_letters_first, reverse_letters_last,
std::ostream_iterator&lt;char&gt;(std::cout));
std::cout &lt;&lt; std::endl;
</pre>
<p>The output is:</p>
<pre class="literal-block">
original sequence of letters: hello world!
sequence in reverse order: !dlrow olleh
</pre>
</div> </div>
<hr class="footer" />
<div class="footer">
<a class="reference" href="reverse_iterator.rst">View document source</a>.
Generated on: 2003-09-21 09:35 UTC.
Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div> </div>
</body> </body>
</html> </html>

5
doc/reverse_iterator.rst
View File

@ -20,4 +20,9 @@
.. contents:: Table of Contents .. contents:: Table of Contents
``reverse_iterator`` synopsis
-----------------------------
.. include:: reverse_iterator_ref.rst .. include:: reverse_iterator_ref.rst
.. include:: reverse_iterator_eg.rst

79
doc/reverse_iterator_ref.rst
View File

@ -1,10 +1,8 @@
:: ::
template <class Iterator> template <class Iterator>
class reverse_iterator : class reverse_iterator
public iterator_adaptor< reverse_iterator<Iterator>, Iterator >
{ {
friend class iterator_core_access;
public: public:
reverse_iterator() {} reverse_iterator() {}
explicit reverse_iterator(Iterator x) ; explicit reverse_iterator(Iterator x) ;
@ -14,47 +12,54 @@
reverse_iterator<OtherIterator> const& r reverse_iterator<OtherIterator> const& r
, typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
); );
reference operator*() const;
private: // as-if specification reverse_iterator& operator++();
typename reverse_iterator::reference dereference() const { return *prior(this->base()); } private:
Iterator current; // exposition
void increment() { --this->base_reference(); }
void decrement() { ++this->base_reference(); }
void advance(typename reverse_iterator::difference_type n)
{
this->base_reference() += -n;
}
template <class OtherIterator>
typename reverse_iterator::difference_type
distance_to(reverse_iterator<OtherIterator> const& y) const
{
return this->base_reference() - y.base();
}
}; };
``reverse_iterator`` requirements ``reverse_iterator`` requirements
................................. ---------------------------------
The base ``Iterator`` must be a model of Bidirectional Traversal The base ``Iterator`` must be a model of Bidirectional Traversal
Iterator. The resulting ``reverse_iterator`` will be a model of the Iterator and Readable Iterator.
most refined standard traversal and access concepts that are modeled
by ``Iterator``.
``reverse_iterator`` models
---------------------------
``reverse_iterator`` models Bidirectional Traversal Iterator and
Readable Iterator. In addition, ``reverse_iterator`` models the same
standard iterator access concepts (if any) that the ``Iterator``
argument models. Also, ``reverse_iterator`` models concepts
according to the following table.
+--------------------------------+-----------------------------------------------------------+
| If ``Iterator`` models | then ``reverse_iterator`` models |
+================================+===========================================================+
| Bidirectional Iterator | Bidirectional Iterator, Readable Lvalue Iterator, |
| | Bidirectional Traversal Iterator |
+--------------------------------+-----------------------------------------------------------+
| Mutable Bidirectional Iterator | Mutable Bidirectional Iterator, Writable Lvalue Iterator, |
| | Bidirectional Traversal Iterator |
+--------------------------------+-----------------------------------------------------------+
``reverse_iterator`` operations
-------------------------------
``reverse_iterator();`` ``reverse_iterator();``
:Requires: ``Iterator`` must be Default Constructible. :Requires: ``Iterator`` must be Default Constructible.
:Returns: An instance of ``reverse_iterator`` with a :Returns: An instance of ``reverse_iterator`` with ``current``
default constructed base object. default constructed.
``explicit reverse_iterator(Iterator x);`` ``explicit reverse_iterator(Iterator x);``
:Returns: An instance of ``reverse_iterator`` with a :Returns: An instance of ``reverse_iterator`` with a
base object copy constructed from ``x``. ``current`` constructed from ``x``.
:: ::
@ -67,3 +72,19 @@ by ``Iterator``.
:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``. :Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
:Returns: An instance of ``reverse_iterator`` that is a copy of ``r``. :Returns: An instance of ``reverse_iterator`` that is a copy of ``r``.
``reference operator*() const;``
:Effects:
::
Iterator tmp = current;
return *--tmp;
``reverse_iterator& operator++();``
:Effects: ``--current``
:Returns: ``*this``