forked from boostorg/iterator
607 lines
16 KiB
HTML
607 lines
16 KiB
HTML
<HTML>
|
|
<!--
|
|
-- Copyright (c) Jeremy Siek 2000
|
|
--
|
|
-- Permission to use, copy, modify, distribute and sell this software
|
|
-- and its documentation for any purpose is hereby granted without fee,
|
|
-- provided that the above copyright notice appears in all copies and
|
|
-- that both that copyright notice and this permission notice appear
|
|
-- in supporting documentation. I make no representations about the
|
|
-- suitability of this software for any purpose. It is provided "as is"
|
|
-- without express or implied warranty.
|
|
-->
|
|
<!--
|
|
-- Copyright (c) 1996-1999
|
|
-- Silicon Graphics Computer Systems, Inc.
|
|
--
|
|
-- Permission to use, copy, modify, distribute and sell this software
|
|
-- and its documentation for any purpose is hereby granted without fee,
|
|
-- provided that the above copyright notice appears in all copies and
|
|
-- that both that copyright notice and this permission notice appear
|
|
-- in supporting documentation. Silicon Graphics makes no
|
|
-- representations about the suitability of this software for any
|
|
-- purpose. It is provided "as is" without express or implied warranty.
|
|
--
|
|
-- Copyright (c) 1994
|
|
-- Hewlett-Packard Company
|
|
--
|
|
-- Permission to use, copy, modify, distribute and sell this software
|
|
-- and its documentation for any purpose is hereby granted without fee,
|
|
-- provided that the above copyright notice appears in all copies and
|
|
-- that both that copyright notice and this permission notice appear
|
|
-- in supporting documentation. Hewlett-Packard Company makes no
|
|
-- representations about the suitability of this software for any
|
|
-- purpose. It is provided "as is" without express or implied warranty.
|
|
--
|
|
-->
|
|
<Head>
|
|
<Title>Iterator Concepts</Title>
|
|
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b"
|
|
ALINK="#ff0000">
|
|
<IMG SRC="../../c++boost.gif"
|
|
ALT="C++ Boost" width="277" height="86">
|
|
|
|
<BR Clear>
|
|
|
|
<h1>Iterator Concepts</h1>
|
|
|
|
<p>The standard iterator concepts (the iterator requirements defined
|
|
in the C++ Standard) have a flaw. They glom together two separate
|
|
issues into a single set of concepts. The two issues are iterator
|
|
traversal and dereference return type semantics. These two issues are
|
|
inherently orthogonal and therefore ought to be represented by two
|
|
separate sets of concepts. The concepts described here do just
|
|
that.</p>
|
|
|
|
One set of concepts handles the return type semantics:
|
|
<ul>
|
|
<li><a href="#concept:ReadableIterator">Readable Iterator</a></li>
|
|
<li><a href="#concept:WritableIterator">Writable Iterator</a></li>
|
|
<li><a href="#concept:MutableLvalueIterator">Mutable Lvalue Iterator</a></li>
|
|
<li><a href="#concept:ConstantLvalueIterator">Constant Lvalue Iterator</a></li>
|
|
</ul>
|
|
|
|
The other set of concepts handles iterator traversal:
|
|
|
|
<ul>
|
|
<li><a href="#concept:SinglePassIterator">Single-Pass Iterator</a></li>
|
|
<li><a href="#concept:ForwardIterator">Forward Iterator</a></li>
|
|
<li><a href="#concept:BidirectionalIterator">Bidirectional Iterator</a></li>
|
|
<li><a href="#concept:RandomAccessIterator">Random Access Iterator</a></li>
|
|
</ul>
|
|
|
|
<p></p>
|
|
<DIV ALIGN="CENTER"><A NAME="fig:graph-concepts"></A></A>
|
|
<TABLE>
|
|
<CAPTION ALIGN="TOP"><STRONG>Figure 1:</STRONG>
|
|
The iterator concepts and refinement relationships.
|
|
</CAPTION>
|
|
<TR><TD><IMG SRC="./iterator_concepts.gif"></TD></TR>
|
|
</TABLE>
|
|
</DIV>
|
|
<p></p>
|
|
|
|
<h2>Relationship with the standard iterator concepts</h2>
|
|
|
|
<p>
|
|
std::Input Iterator refines boost::Single-Pass Iterator and
|
|
boost::ReadableIterator.
|
|
|
|
<p>
|
|
std::Output Iterator refines boost::Single-Pass Iterator and
|
|
boost::Writable Iterator.
|
|
|
|
<p>
|
|
std::Forward Iterator refines boost::Forward Iterator and
|
|
boost::Constant Lvalue Iterator or boost::Mutable Lvalue Iterator.
|
|
|
|
<p>
|
|
std::Bidirectional Iterator refines boost::Bidirectional Iterator and
|
|
boost::Constant Lvalue Iterator or boost::Mutable Lvalue Iterator.
|
|
|
|
<p>
|
|
std::Random Access Iterator refines boost::Random Access Iterator and
|
|
boost::Constant Lvalue Iterator or boost::Mutable Lvalue Iterator.
|
|
|
|
|
|
<h3>Notation</h3>
|
|
<Table>
|
|
<TR>
|
|
<TD><tt>X</tt></TD>
|
|
<TD>The iterator type.</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD><tt>T</tt></TD>
|
|
<TD>The value type of <tt>X</tt>.</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD><tt>x</tt>, <tt>y</tt></TD>
|
|
<TD>An object of type <tt>X</tt>.</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD><tt>t</tt></TD>
|
|
<TD>An object of type <tt>T</tt>.</TD>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
|
|
<hr>
|
|
|
|
<H2><A NAME="concept:ReadableIterator"></A>
|
|
Readable Iterator
|
|
</H2>
|
|
|
|
A Readable Iterator is an iterator that dereferences to produce an
|
|
rvalue that is convertible to the <tt>value_type</tt> of the
|
|
iterator. For example, derefencing may return a temporary object and
|
|
therefore it would be a mistake to bind the result to a reference.
|
|
Also, an attempt to assign a value to the result will most likely
|
|
cause an error.
|
|
|
|
<pre>
|
|
template <class Readable Iterator>
|
|
void foo(Readable Iterator x)
|
|
{
|
|
typedef std::iterator_traits<Readable Iterator>::value_type T;
|
|
T t = *x; // Read a value. This is OK.
|
|
T& s = *x; // Bind to a reference. This is a bad idea.
|
|
*x = t; // Try to assign. This is a really bad idea.
|
|
}
|
|
</pre>
|
|
|
|
|
|
<h3>Associated Types</h3>
|
|
|
|
<Table border>
|
|
|
|
<TR>
|
|
<TD>Value type</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::value_type</tt></TD>
|
|
<TD>
|
|
The type of the value obtained by dereferencing a LvalueIterator
|
|
</TD>
|
|
</tr>
|
|
|
|
<TR>
|
|
<TD>Return Category</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::return_category</tt></TD>
|
|
<TD>
|
|
A type convertible to <tt>boost::readable_iterator_tag</tt>
|
|
</TD>
|
|
</tr>
|
|
|
|
</Table>
|
|
|
|
<h3>Refinement of</h3>
|
|
|
|
<A href="http://www.sgi.com/Technology/STL/Assignable.html">Assignable</A>,
|
|
<A href="http://www.sgi.com/Technology/STL/EqualityComparable.html">Equality Comparable</A>,
|
|
<A href="http://www.sgi.com/Technology/STL/DefaultConstructible.html">Default Constructible</A>
|
|
|
|
<h3>Valid expressions</h3>
|
|
|
|
<Table border>
|
|
<TR><TH>Name</TH><TH>Expression</TH><TH>Type requirements</TH><TH>Return type</TH></TR>
|
|
<TR>
|
|
<TD>Dereference</TD>
|
|
<TD><tt>*x</tt></TD>
|
|
<TD> </TD>
|
|
<TD>Convertible to <tt>T</tt>.</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD>Member access</TD>
|
|
<TD><tt>x->m</tt></TD>
|
|
<TD><tt>T</tt> is a type with a member named <tt>m</tt>.</TD>
|
|
<TD>
|
|
|
|
</TD>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
|
|
<hr>
|
|
|
|
<H2><A NAME="concept:WritableIterator"></A>
|
|
Writable Iterator
|
|
</H2>
|
|
|
|
A Writable Iterator is an iterator that can be used to store a value
|
|
using the dereference-assignment expression.
|
|
|
|
<h3>Definitions</h3>
|
|
|
|
If <tt>x</tt> is an Writable Iterator of type <tt>X</tt>, then the
|
|
expression <tt>*x = a;</tt> stores the value <tt>a</tt> into
|
|
<tt>x</tt>. Note that <tt>operator=</tt>, like other C++ functions,
|
|
may be overloaded; it may, in fact, even be a template function. In
|
|
general, then, <tt>a</tt> may be any of several different types. A
|
|
type <tt>A</tt> belongs to the <i>set of value types</i> of <tt>X</tt>
|
|
if, for an object <tt>a</tt> of type <tt>A</tt>, <tt>*x = a;</tt> is
|
|
well-defined and does not require performing any non-trivial
|
|
conversions on <tt>a</tt>.
|
|
|
|
<h3>Associated Types</h3>
|
|
|
|
<Table border>
|
|
|
|
<TR>
|
|
<TD>Return Category</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::return_category</tt></TD>
|
|
<TD>
|
|
A type convertible to <tt>boost::writable_iterator_tag</tt>
|
|
</TD>
|
|
</tr>
|
|
|
|
</Table>
|
|
|
|
|
|
|
|
<h3>Refinement of</h3>
|
|
|
|
<A href="http://www.sgi.com/Technology/STL/Assignable.html">Assignable</A>,
|
|
<A href="http://www.sgi.com/Technology/STL/EqualityComparable.html">Equality Comparable</A>,
|
|
<A href="http://www.sgi.com/Technology/STL/DefaultConstructible.html">Default Constructible</A>
|
|
|
|
<h3>Valid expressions</h3>
|
|
|
|
<Table border>
|
|
<TR>
|
|
<TH>Name</TH><TH>Expression</TH><TH>Return type</TH>
|
|
</TR>
|
|
<TR>
|
|
<TD>Dereference assignment</TD>
|
|
<TD><tt>*x = a</tt></TD>
|
|
<TD>unspecified</TD>
|
|
</TR>
|
|
</table>
|
|
|
|
<p>
|
|
|
|
<hr>
|
|
|
|
<H2><A NAME="concept:ConstantLvalueIterator"></A>
|
|
Constant Lvalue Iterator
|
|
</H2>
|
|
|
|
A Constant Lvalue Iterator is an iterator that dereferences to produce a
|
|
const reference to the pointed-to object, i.e., the associated
|
|
<tt>reference</tt> type is <tt>const T&</tt>. Changing the value
|
|
of or destroying an iterator that models Constant Lvalue Iterator does
|
|
not invalidate pointers and references previously obtained from that
|
|
iterator.
|
|
|
|
|
|
<h3>Refinement of</h3>
|
|
|
|
<a href="#concept:Readable Iterator">Readable Iterator</a>
|
|
|
|
<h3>Associated Types</h3>
|
|
|
|
<Table border>
|
|
|
|
<TR>
|
|
<TD>Value type</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::value_type</tt></TD>
|
|
<TD>
|
|
The type of the value obtained by dereferencing a Constant Lvalue Iterator.
|
|
</TD>
|
|
</tr>
|
|
|
|
<TR>
|
|
<TD>Reference type</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::reference</tt></TD>
|
|
<TD>
|
|
The return type of <tt>operator*()</tt>, which must be
|
|
<tt>const T&</tt>.
|
|
</TD>
|
|
</tr>
|
|
|
|
<TR>
|
|
<TD>POinter type</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::pointer</tt></TD>
|
|
<TD>
|
|
The pointer to the value type, which must be <tt>const T*</tt>.
|
|
</TD>
|
|
</tr>
|
|
|
|
<TR>
|
|
<TD>Return Category</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::return_category</tt></TD>
|
|
<TD>
|
|
A type convertible to <tt>boost::constant_lvalue_iterator_tag</tt>
|
|
</TD>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
|
|
<h3>Valid expressions</h3>
|
|
|
|
<Table border>
|
|
<TR><TH>Name</TH><TH>Expression</TH><TH>Type requirements</TH><TH>Return type</TH></TR>
|
|
<TR>
|
|
<TD>Dereference</TD>
|
|
<TD><tt>*x</tt></TD>
|
|
<TD> </TD>
|
|
<TD><tt>const T&</tt></TD>
|
|
</TR>
|
|
<TR>
|
|
<TD>Member access</TD>
|
|
<TD><tt>x->m</tt></TD>
|
|
<TD><tt>T</tt> is a type with a member named <tt>m</tt>.</TD>
|
|
<TD>
|
|
|
|
</TD>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<H2><A NAME="concept:MutableLvalueIterator"></A>
|
|
Mutable Lvalue Iterator
|
|
</H2>
|
|
|
|
A Mutable Lvalue Iterator is an iterator that dereferences to produce a
|
|
reference to the pointed-to object. The associated <tt>reference</tt>
|
|
type is <tt>T&</tt>. Changing the value of or destroying an
|
|
iterator that models Mutable Lvalue Iterator does not invalidate
|
|
pointers and references previously obtained from that iterator.
|
|
|
|
<h3>Refinement of</h3>
|
|
|
|
<a href="#concept:Readable Iterator">Readable Iterator</a> and
|
|
<a href="#concept:WritableIterator">Writable Iterator</a>.
|
|
|
|
|
|
|
|
<h3>Associated Types</h3>
|
|
|
|
<Table border>
|
|
|
|
<TR>
|
|
<TD>Value type</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::value_type</tt></TD>
|
|
<TD>
|
|
The type of the value obtained by dereferencing a Mutable Lvalue Iterator.
|
|
</TD>
|
|
</tr>
|
|
|
|
<TR>
|
|
<TD>Reference type</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::reference</tt></TD>
|
|
<TD>
|
|
The return type of <tt>operator*()</tt>, which is
|
|
<tt>T&</tt>.
|
|
</TD>
|
|
</tr>
|
|
|
|
<TR>
|
|
<TD>Pointer type</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::pointer</tt></TD>
|
|
<TD>
|
|
The pointer to the value type, which is <tt>T*</tt>.
|
|
</TD>
|
|
</tr>
|
|
|
|
<TR>
|
|
<TD>Return Category</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::return_category</tt></TD>
|
|
<TD>
|
|
A type convertible to <tt>boost::mutable_lvalue_iterator_tag</tt>
|
|
</TD>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
|
|
<h3>Valid expressions</h3>
|
|
|
|
<Table border>
|
|
<TR><TH>Name</TH><TH>Expression</TH><TH>Type requirements</TH><TH>Return type</TH></TR>
|
|
<TR>
|
|
<TD>Dereference</TD>
|
|
<TD><tt>*x</tt></TD>
|
|
<TD> </TD>
|
|
<TD> <tt>T&</tt> </TD>
|
|
</TR>
|
|
<TR>
|
|
<TD>Member access</TD>
|
|
<TD><tt>x->m</tt></TD>
|
|
<TD><tt>T</tt> is a type with a member named <tt>m</tt>.</TD>
|
|
<TD>
|
|
|
|
</TD>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
<hr>
|
|
|
|
<H2><A NAME="concept:SinglePassIterator"></A>
|
|
Single-Pass Iterator
|
|
</H2>
|
|
|
|
A Single-Pass Iterator is an iterator that can be incremented to
|
|
traverse through a sequence of objects, but the sequence can only be
|
|
traversed a single time.
|
|
|
|
<h3>Associated types</h3>
|
|
|
|
<Table border>
|
|
<TR>
|
|
<TD>Difference type</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::difference_type</tt></TD>
|
|
<TD>
|
|
A signed integral type used to represent the distance from one
|
|
iterator to another, or the number of elements in a range.
|
|
</TD>
|
|
</TR>
|
|
|
|
<TR>
|
|
<TD>Traversal Category</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::traversal_category</tt></TD>
|
|
<TD>
|
|
A type convertible to <tt>boost::single_pass_iterator_tag</tt>
|
|
</TD>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<h3>Valid expressions</h3>
|
|
|
|
<Table border>
|
|
<TR>
|
|
<TH>Name</TH><TH>Expression</TH><TH>Type requirements</TH>
|
|
<TH>Return type</TH>
|
|
</TR>
|
|
<TR>
|
|
<TD>Preincrement</TD>
|
|
<TD><tt>++i</tt></TD><TD> </TD><TD><tt>X&</tt></TD>
|
|
</TR>
|
|
<TR>
|
|
<TD>Postincrement</TD>
|
|
<TD><tt>(void)i++</tt></TD><TD> </TD><TD> </TD>
|
|
</TR>
|
|
</Table>
|
|
|
|
<p>
|
|
<hr>
|
|
|
|
<H2><A NAME="concept:ForwardIterator"></A>
|
|
Forward Iterator
|
|
</H2>
|
|
|
|
The Forward Iterator is an iterator that can be incremented. Also, it
|
|
is permissible to make multiple passes through the sequence.
|
|
|
|
<h3>Refinement of</h3>
|
|
|
|
<a href="#concept:SinglePassIterator">Single-Pass Iterator</a>
|
|
|
|
<h3>Associated types</h3>
|
|
|
|
<Table border>
|
|
<TR>
|
|
<TD>Traversal Category</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::traversal_category</tt></TD>
|
|
<TD>
|
|
A type convertible to <tt>boost::forward_iterator_tag</tt>
|
|
</TD>
|
|
</tr>
|
|
</Table>
|
|
|
|
<p>
|
|
<hr>
|
|
|
|
<H2><A NAME="concept:BidirectionalIterator"></A>
|
|
Bidirectional Iterator
|
|
</H2>
|
|
|
|
An iterator that can be incremented and decremented.
|
|
|
|
<h3>Refinement of</h3>
|
|
|
|
<a href="#concept:ForwardIterator">Forward Iterator</a>
|
|
|
|
<h3>Associated types</h3>
|
|
|
|
<Table border>
|
|
<TR>
|
|
<TD>Traversal Category</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::traversal_category</tt></TD>
|
|
<TD>
|
|
A type convertible to <tt>boost::bidirectional_iterator_tag</tt>
|
|
</TD>
|
|
</tr>
|
|
</Table>
|
|
|
|
<h3>Valid expressions</h3>
|
|
|
|
<Table border>
|
|
<TR>
|
|
<TH>Name</TH><TH>Expression</TH><TH>Type requirements</TH>
|
|
<TH>Return type</TH>
|
|
</TR>
|
|
<TR><TD>Predecrement</TD>
|
|
<TD><tt>--i</tt></TD><TD> </TD><TD><tt>X&</tt></TD>
|
|
</TR>
|
|
<TR><TD>Postdecrement</TD>
|
|
<TD><tt>i--</tt></TD><TD> </TD><TD><tt>X</tt></TD>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
<hr>
|
|
|
|
<H2><A NAME="concept:RandomAccessIterator"></A>
|
|
Random Access Iterator
|
|
</H2>
|
|
|
|
An iterator that provides constant-time methods for moving forward and
|
|
backward in arbitrary-sized steps
|
|
|
|
<h3>Refinement of</h3>
|
|
|
|
<a href="#concept:BidirectionalIterator">Bidirectional Iterator</a>
|
|
|
|
<h3>Associated types</h3>
|
|
|
|
<Table border>
|
|
<TR>
|
|
<TD>Traversal Category</TD>
|
|
<TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::traversal_category</tt></TD>
|
|
<TD>
|
|
A type convertible to <tt>boost::random_access_iterator_tag</tt>
|
|
</TD>
|
|
</tr>
|
|
</Table>
|
|
|
|
<h3>Valid expressions</h3>
|
|
|
|
<Table border>
|
|
<TR><TH>Name</TH><TH>Expression</TH><TH>Type requirements</TH>
|
|
<TH>Return type</TH>
|
|
</TR>
|
|
<TR><TD>Iterator addition</TD>
|
|
<TD><tt>i += n</tt></TD><TD> </TD><TD><tt>X&</tt></TD>
|
|
</TR>
|
|
<TR><TD>Iterator addition</TD>
|
|
<TD><tt>i + n</tt> or <tt>n + i</tt></TD><TD> </TD><TD><tt>X</tt></TD>
|
|
</TR>
|
|
<TR><TD>Iterator subtraction</TD>
|
|
<TD><tt>i -= n</tt></TD><TD> </TD><TD><tt>X&</tt></TD>
|
|
</TR>
|
|
<TR><TD>Iterator subtraction</TD>
|
|
<TD><tt>i - n</tt></TD><TD> </TD><TD><tt>X</tt></TD>
|
|
</TR>
|
|
<TR><TD>Difference</TD>
|
|
<TD><tt>i - j</tt></TD><TD> </TD><TD><tt><a href="./iterator_traits.htm">boost::iterator_traits</a><X>::difference_type</tt></TD>
|
|
</TR>
|
|
<TR><TD>Element operator</TD>
|
|
<TD><tt>i[n]</tt></TD>
|
|
<TD><tt>X</tt> must be a model of
|
|
<a href="#concept:Readable Iterator">Readable Iterator</a>. </TD>
|
|
<TD>The same return type as <tt>*i</tt>.</TD>
|
|
</TR>
|
|
<TR><TD>Element assignment</TD>
|
|
<TD><tt>i[n] = t</tt></TD>
|
|
<TD><tt>X</tt> must be a model of
|
|
<a href="#concept:WritableIterator">Writable Iterator</a>.</TD>
|
|
<TD>unspecified</TD>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<hr>
|
|
|
|
<HR>
|
|
<TABLE>
|
|
<TR valign=top>
|
|
<TD nowrap>Copyright © 2000</TD><TD>
|
|
<A HREF="../../../people/jeremy_siek.htm">Jeremy Siek</A>, Univ.of Notre Dame (<A HREF="mailto:jsiek@lsc.nd.edu">jsiek@lsc.nd.edu</A>)
|
|
</TD></TR></TABLE>
|
|
|
|
</body>
|
|
</html>
|