mirror of
https://github.com/boostorg/iterator.git
synced 2025-07-29 12:27:33 +02:00
moved to this branch from development directory
[SVN r10460]
This commit is contained in:
Jeremy Siek
73
concept_tests.cpp
Normal file
73
concept_tests.cpp
Normal file
@ -0,0 +1,73 @@
|
||||
#include <boost/iterator_concepts.hpp>
|
||||
#include <boost/operators.hpp>
|
||||
|
||||
struct new_iterator
|
||||
: public boost::iterator<std::random_access_iterator_tag, int>,
|
||||
public boost::new_iterator_base
|
||||
{
|
||||
typedef boost::random_access_traversal_tag traversal_category;
|
||||
typedef boost::mutable_lvalue_iterator_tag return_category;
|
||||
|
||||
int& operator*() const { return *m_x; }
|
||||
new_iterator& operator++() { return *this; }
|
||||
new_iterator operator++(int) { return *this; }
|
||||
new_iterator& operator--() { return *this; }
|
||||
new_iterator operator--(int) { return *this; }
|
||||
new_iterator& operator+=(std::ptrdiff_t) { return *this; }
|
||||
new_iterator operator+(std::ptrdiff_t) { return *this; }
|
||||
new_iterator& operator-=(std::ptrdiff_t) { return *this; }
|
||||
std::ptrdiff_t operator-(const new_iterator&) const { return 0; }
|
||||
new_iterator operator-(std::ptrdiff_t) const { return *this; }
|
||||
bool operator==(const new_iterator&) const { return false; }
|
||||
bool operator!=(const new_iterator&) const { return false; }
|
||||
bool operator<(const new_iterator&) const { return false; }
|
||||
int* m_x;
|
||||
};
|
||||
new_iterator operator+(std::ptrdiff_t, new_iterator x) { return x; }
|
||||
|
||||
struct old_iterator
|
||||
: public boost::iterator<std::random_access_iterator_tag, int>
|
||||
{
|
||||
int& operator*() const { return *m_x; }
|
||||
old_iterator& operator++() { return *this; }
|
||||
old_iterator operator++(int) { return *this; }
|
||||
old_iterator& operator--() { return *this; }
|
||||
old_iterator operator--(int) { return *this; }
|
||||
old_iterator& operator+=(std::ptrdiff_t) { return *this; }
|
||||
old_iterator operator+(std::ptrdiff_t) { return *this; }
|
||||
old_iterator& operator-=(std::ptrdiff_t) { return *this; }
|
||||
old_iterator operator-(std::ptrdiff_t) const { return *this; }
|
||||
std::ptrdiff_t operator-(const old_iterator&) const { return 0; }
|
||||
bool operator==(const old_iterator&) const { return false; }
|
||||
bool operator!=(const old_iterator&) const { return false; }
|
||||
bool operator<(const old_iterator&) const { return false; }
|
||||
int* m_x;
|
||||
};
|
||||
old_iterator operator+(std::ptrdiff_t, old_iterator x) { return x; }
|
||||
|
||||
int
|
||||
main()
|
||||
{
|
||||
#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
|
||||
boost::function_requires<
|
||||
boost_concepts::MutableLvalueIteratorConcept<int*> >();
|
||||
boost::function_requires<
|
||||
boost_concepts::RandomAccessIteratorConcept<int*> >();
|
||||
|
||||
boost::function_requires<
|
||||
boost_concepts::ConstantLvalueIteratorConcept<const int*> >();
|
||||
boost::function_requires<
|
||||
boost_concepts::RandomAccessIteratorConcept<const int*> >();
|
||||
#endif
|
||||
|
||||
boost::function_requires<
|
||||
boost_concepts::MutableLvalueIteratorConcept<new_iterator> >();
|
||||
boost::function_requires<
|
||||
boost_concepts::RandomAccessIteratorConcept<new_iterator> >();
|
||||
|
||||
boost::function_requires<
|
||||
boost_concepts::MutableLvalueIteratorConcept<old_iterator> >();
|
||||
boost::function_requires<
|
||||
boost_concepts::RandomAccessIteratorConcept<old_iterator> >();
|
||||
return 0;
|
||||
}
|
||||
160
iterator_categories.htm
Normal file
160
iterator_categories.htm
Normal file
@ -0,0 +1,160 @@
|
||||
<html>
|
||||
<!--
|
||||
-- Copyright (c) Jeremy Siek 2000,2001
|
||||
--
|
||||
-- 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.
|
||||
-->
|
||||
<head>
|
||||
<title>Boost Iterator Traits</title>
|
||||
</head>
|
||||
|
||||
<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>Boost Iterator Category Traits</h1>
|
||||
Header <tt><a href="../../boost/iterator_categories.hpp">boost/iterator_categories.hpp</a></tt>
|
||||
|
||||
<p>
|
||||
The <tt>boost::traversal_category</tt> and
|
||||
<tt>boost::return_category</tt> traits classes provides access to the
|
||||
category tags for iterators that model the Boost <a
|
||||
href="./iterator_concepts.htm">Iterator Concepts</a>, which are a
|
||||
replacement for the iterator requirements in the C++ standard. The
|
||||
other associated types of the Boost iterator concepts are accessed
|
||||
through the <tt>std::iterator_traits</tt> class.
|
||||
|
||||
<ul>
|
||||
<li><tt>traversal_category<Iter>::type</tt> Can the iterator go forward, backward, etc.?
|
||||
<li><tt>return_category<Iter>::type</tt> Is the iterator read or write only?
|
||||
Is the dereferenced type an lvalue?
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
An important feature of the <tt>boost::traversal_category</tt> and
|
||||
<tt>boost::return_category</tt> classes is that they are <b>backwards
|
||||
compatible</b>, i.e., they automatically work for iterators for which
|
||||
there are valid definitions of <tt>std::iterator_traits</tt>. The old
|
||||
<tt>iterator_category</tt> is mapped to the appropriate traversal and
|
||||
return categories.
|
||||
|
||||
<p>
|
||||
When creating a new iterator type that is meant to work with
|
||||
<tt>boost::traversal_category</tt> and
|
||||
<tt>boost::return_category</tt>, you can either create a
|
||||
specialization of these classes for your iterator type, or you can
|
||||
provide all the necessary associated types as nested typedefs. In
|
||||
this case, your iterator class will need to inherit from
|
||||
<tt>new_iterator_base</tt> to let the category traits know
|
||||
that it will be able to find typedefs for <tt>traversal_category</tt>
|
||||
and <tt>return_category</tt> in you iterator class.
|
||||
|
||||
|
||||
Each of the new iterator requirements will need a category tag.
|
||||
|
||||
<pre>
|
||||
namespace boost {
|
||||
|
||||
// Return Type Categories
|
||||
struct readable_iterator_tag { };
|
||||
struct writable_iterator_tag { };
|
||||
struct swappable_iterator_tag { };
|
||||
struct mutable_lvalue_iterator_tag : virtual public writable_iterator_tag,
|
||||
virtual public readable_iterator_tag { };
|
||||
struct constant_lvalue_iterator_tag : public readable_iterator_tag { };
|
||||
|
||||
// Traversal Categories
|
||||
struct forward_traversal_tag { };
|
||||
struct bidirectional_traversal_tag : public forward_traversal_tag { };
|
||||
struct random_access_traversal_tag : public bidirectional_traversal_tag { };
|
||||
|
||||
}
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
The following is pseudo-code for the iterator category traits classes.
|
||||
|
||||
<pre>
|
||||
namespace boost {
|
||||
|
||||
<i>// Inherit from iterator_base if your iterator defines its own
|
||||
// return_category and traversal_category. Otherwise, the "old style"
|
||||
// iterator category will be mapped to the return_category and
|
||||
// traversal_category.</i>
|
||||
struct new_iterator_base { };
|
||||
|
||||
template <typename Iterator>
|
||||
struct return_category
|
||||
{
|
||||
<b><i>// Pseudo-code</i></b>
|
||||
if (Iterator inherits from new_iterator_base) {
|
||||
typedef typename Iterator::return_category type;
|
||||
} else {
|
||||
typedef std::iterator_traits<Iterator> OldTraits;
|
||||
typedef typename OldTraits::iterator_category Cat;
|
||||
if (Cat inherits from std::forward_iterator_tag)
|
||||
if (is-const(T))
|
||||
typedef boost::constant_lvalue_iterator_tag type;
|
||||
else
|
||||
typedef boost::mutable_lvalue_iterator_tag type;
|
||||
else if (Cat inherits from std::input_iterator_tag)
|
||||
typedef boost::readable_iterator_tag type;
|
||||
else if (Cat inherits from std::output_iterator_tag)
|
||||
typedef boost::writable_iterator_tag type;
|
||||
}
|
||||
};
|
||||
|
||||
template <typename T>
|
||||
struct return_category<T*>
|
||||
{
|
||||
<b><i>// Pseudo-code</i></b>
|
||||
if (is-const(T))
|
||||
typedef boost::constant_lvalue_iterator_tag type;
|
||||
else
|
||||
typedef boost::mutable_lvalue_iterator_tag type;
|
||||
};
|
||||
|
||||
template <typename Iterator>
|
||||
struct traversal_category
|
||||
{
|
||||
<b><i>// Pseudo-code</i></b>
|
||||
if (Iterator inherits from new_iterator_base) {
|
||||
typedef typename Iterator::traversal_category type;
|
||||
} else {
|
||||
typedef std::iterator_traits<Iterator> OldTraits;
|
||||
typedef typename OldTraits::iterator_category Cat;
|
||||
|
||||
if (Cat inherits from std::random_access_iterator_tag)
|
||||
typedef boost::random_access_traversal_tag type;
|
||||
else if (Cat inherits from std::bidirectional_iterator_tag)
|
||||
typedef boost::bidirectional_traversal_tag type;
|
||||
else if (Cat inherits from std::forward_iterator_tag)
|
||||
typedef boost::forward_traversal_tag type;
|
||||
}
|
||||
};
|
||||
|
||||
template <typename T>
|
||||
struct traversal_category<T*>
|
||||
{
|
||||
typedef boost::random_access_traversal_tag type;
|
||||
};
|
||||
|
||||
}
|
||||
</pre>
|
||||
|
||||
<hr>
|
||||
<address><a href="mailto:jsiek@lsc.nd.edu">jeremy siek</a></address>
|
||||
<!-- Created: Sun Mar 18 14:06:57 EST 2001 -->
|
||||
<!-- hhmts start -->
|
||||
Last modified: Mon Mar 19 12:59:30 EST 2001
|
||||
<!-- hhmts end -->
|
||||
</body>
|
||||
</html>
|
||||
37
iterator_concepts.fig
Normal file
37
iterator_concepts.fig
Normal file
@ -0,0 +1,37 @@
|
||||
#FIG 3.2
|
||||
Landscape
|
||||
Center
|
||||
Inches
|
||||
Letter
|
||||
100.00
|
||||
Single
|
||||
-2
|
||||
1200 2
|
||||
6 150 2325 4275 4350
|
||||
2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 1 0 2
|
||||
1 1 1.00 60.00 120.00
|
||||
1725 4050 1725 3450
|
||||
2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 1 0 2
|
||||
1 1 1.00 60.00 120.00
|
||||
1725 3150 1725 2550
|
||||
4 0 0 100 0 19 18 0.0000 4 210 3180 375 2550 ForwardTraversalIterator\001
|
||||
4 0 0 100 0 19 18 0.0000 4 210 3765 225 3450 BidirectionalTraversalIterator\001
|
||||
4 0 0 100 0 19 18 0.0000 4 210 4125 150 4350 RandomAccessTraversalIterator\001
|
||||
-6
|
||||
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
|
||||
1 1 1.00 60.00 120.00
|
||||
4800 3600 4800 2400
|
||||
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
|
||||
1 1 1.00 60.00 120.00
|
||||
6900 3000 5400 2400
|
||||
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
|
||||
1 1 1.00 60.00 120.00
|
||||
6900 3000 7500 2400
|
||||
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
|
||||
1 1 1.00 60.00 120.00
|
||||
6900 3000 9075 2475
|
||||
4 0 0 100 0 19 18 0.0000 4 210 2040 6600 2400 WritableIterator\001
|
||||
4 0 0 100 0 19 18 0.0000 4 210 2145 3900 2400 ReadableIterator\001
|
||||
4 0 0 50 0 19 18 0.0000 4 210 2835 5700 3300 MutableLvalueIterator\001
|
||||
4 0 0 50 0 19 18 0.0000 4 270 2355 9075 2400 SwappableIterator\001
|
||||
4 0 0 50 0 19 18 0.0000 4 210 2970 3825 3900 ConstantLvalueIterator\001
|
||||
BIN
iterator_concepts.gif
Normal file
BIN
iterator_concepts.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.2 KiB |
663
iterator_concepts.htm
Normal file
663
iterator_concepts.htm
Normal file
@ -0,0 +1,663 @@
|
||||
<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 categories and requirements are flawed because
|
||||
they use a single hierarchy of requirements to address two orthogonal
|
||||
issues: <b><i>iterator traversal</i></b> and <b><i>dereference return
|
||||
type</i></b>. The current iterator requirement hierarchy is mainly
|
||||
geared towards iterator traversal (hence the category names), while
|
||||
requirements that address dereference return type sneak in at various
|
||||
places.
|
||||
|
||||
<p>
|
||||
The iterator requirements should be separated into two hierarchies.
|
||||
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:SwappableIterator">Swappable Iterator</a></li>
|
||||
<li><a href="#concept:ConstantLvalueIterator">Constant Lvalue Iterator</a></li>
|
||||
<li><a href="#concept:MutableLvalueIterator">Mutable Lvalue Iterator</a></li>
|
||||
</ul>
|
||||
|
||||
The other set of concepts handles iterator traversal:
|
||||
|
||||
<ul>
|
||||
<li><a href="#concept:ForwardTraversalIterator">Forward Traversal Iterator</a></li>
|
||||
<li><a href="#concept:BidirectionalTraversalIterator">Bidirectional Traversal Iterator</a></li>
|
||||
<li><a href="#concept:RandomAccessTraversalIterator">Random Access Traversal Iterator</a></li>
|
||||
</ul>
|
||||
|
||||
The current Input Iterator and Output Iterator requirements will
|
||||
continue to be used as is. Note that Input Iterator implies Readable
|
||||
Iterator and Output Iterator implies Writable Iterator.
|
||||
|
||||
<p>
|
||||
Note: we considered defining a Single-Pass Iterator, which could be
|
||||
combined with Readable or Writable Iterator to replace the Input and
|
||||
Output Iterator requirements. We rejected this idea because there are
|
||||
some differences between Input and Output Iterators that make it hard
|
||||
to merge them: for example Input Iterator requires Equality Comparable
|
||||
while Output Iterator does not.
|
||||
|
||||
|
||||
<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 implies boost::ReadableIterator.
|
||||
|
||||
<p>
|
||||
std::Output Iterator implies 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>, i.e., <tt>std::iterator_traits<X>::value_type</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>
|
||||
<!--------------------------------------------------------------------------->
|
||||
|
||||
<H3><A NAME="concept:ReadableIterator"></A>
|
||||
Readable Iterator
|
||||
</H3>
|
||||
|
||||
A Readable Iterator is an iterator that dereferences to produce an
|
||||
rvalue that is convertible to the <tt>value_type</tt> of the
|
||||
iterator.
|
||||
|
||||
<h3>Associated Types</h3>
|
||||
|
||||
<Table border>
|
||||
|
||||
<tr>
|
||||
<td>Value type</td>
|
||||
<td><tt>std::iterator_traits<X>::value_type</tt></td>
|
||||
<td>The type of the objects pointed to by the iterator.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Reference type</td>
|
||||
<td><tt>std::iterator_traits<X>::reference</tt></td>
|
||||
<td>
|
||||
The return type of dereferencing the iterator. This
|
||||
type must be convertible to <tt>T</tt>.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Return Category</td>
|
||||
<td><tt>std::return_category<X>::type</tt></td>
|
||||
<td>
|
||||
A type convertible to <tt>std::readable_iterator_tag</tt>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
</Table>
|
||||
|
||||
<h3>Refinement of</h3>
|
||||
|
||||
<A href="http://www.boost.org/libs/utility/CopyConstructible.html">Copy 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><tt>std::iterator_traits<X>::reference</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>
|
||||
If <tt>m</tt> is a data member, the type of <tt>m</tt>.
|
||||
If <tt>m</tt> is a member function, the return type of <tt>m</tt>.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>
|
||||
|
||||
<hr>
|
||||
<!--------------------------------------------------------------------------->
|
||||
|
||||
<H3><A NAME="concept:WritableIterator"></A>
|
||||
Writable Iterator
|
||||
</H3>
|
||||
|
||||
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>std::return_category<X>::type</tt></td>
|
||||
<td>
|
||||
A type convertible to <tt>std::writable_iterator_tag</tt>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
</Table>
|
||||
|
||||
|
||||
|
||||
<h3>Refinement of</h3>
|
||||
|
||||
<A href="http://www.boost.org/libs/utility/CopyConstructible.html">Copy 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>
|
||||
<!--------------------------------------------------------------------------->
|
||||
|
||||
<H3><A NAME="concept:SwappableIterator"></A>
|
||||
Swappable Iterator
|
||||
</H3>
|
||||
|
||||
A Swappable Iterator is an iterator whose dereferenced values can be
|
||||
swapped.
|
||||
|
||||
<p>
|
||||
Note: the requirements for Swappable Iterator are dependent on the
|
||||
issues surrounding <tt>std::swap()</tt> being resolved. Here we assume
|
||||
that the issue will be resolved by allowing the overload of
|
||||
<tt>std::swap()</tt> for user-defined types.
|
||||
|
||||
<p>
|
||||
Note: Readable Iterator and Writable Iterator combined implies
|
||||
Swappable Iterator because of the fully templated
|
||||
<tt>std::swap()</tt>. However, Swappable Iterator does not imply
|
||||
Readable Iterator nor Writable Iterator.
|
||||
|
||||
<h3>Associated Types</h3>
|
||||
|
||||
<Table border>
|
||||
|
||||
<tr>
|
||||
<td>Return Category</td>
|
||||
<td><tt>std::return_category<X>::type</tt></td>
|
||||
<td>
|
||||
A type convertible to <tt>std::swappable_iterator_tag</tt>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
</Table>
|
||||
|
||||
|
||||
<h3>Valid expressions</h3>
|
||||
|
||||
Of the two valid expressions listed below, only one <b>OR</b> the
|
||||
other is required. If <tt>std::iter_swap()</tt> is overloaded for
|
||||
<tt>X</tt> then <tt>std::swap()</tt> is not required. If
|
||||
<tt>std::iter_swap()</tt> is not overloaded for <tt>X</tt> then the
|
||||
default (fully templated) version is used, which will call
|
||||
<tt>std::swap()</tt> (this means changing the current requirements for
|
||||
<tt>std::iter_swap()</tt>).
|
||||
|
||||
<p>
|
||||
<Table border>
|
||||
<tr>
|
||||
<TH>Name</TH><TH>Expression</TH><TH>Return type</TH>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Iterator Swap</td>
|
||||
<td><tt>std::iter_swap(x, y)</tt></td>
|
||||
<td>void</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Dereference and Swap</td>
|
||||
<td><tt>std::swap(*x, *y)</tt></td>
|
||||
<td>void</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
<hr>
|
||||
<!--------------------------------------------------------------------------->
|
||||
|
||||
<H3><A NAME="concept:ConstantLvalueIterator"></A>
|
||||
Constant Lvalue Iterator
|
||||
</H3>
|
||||
|
||||
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:ReadableIterator">Readable Iterator</a>
|
||||
|
||||
<h3>Associated Types</h3>
|
||||
|
||||
<Table border>
|
||||
|
||||
<tr>
|
||||
<td>Reference type</td>
|
||||
<td><tt>std::iterator_traits<X>::reference</tt></td>
|
||||
<td>
|
||||
The return type of dereferencing the iterator, which must be
|
||||
<tt>const T&</tt>.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<!-- I don't think this is needed
|
||||
<tr>
|
||||
<td>Pointer type</td>
|
||||
<td><tt>std::iterator_traits<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>std::return_category<X>::type</tt></td>
|
||||
<td>
|
||||
A type convertible to <tt>std::constant_lvalue_iterator_tag</tt>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
<!-- these are not necessary now that we use reference as operator* return type
|
||||
<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>std::iterator_traits<X>::reference</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>
|
||||
<!--------------------------------------------------------------------------->
|
||||
|
||||
<H3><A NAME="concept:MutableLvalueIterator"></A>
|
||||
Mutable Lvalue Iterator
|
||||
</H3>
|
||||
|
||||
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:ReadableIterator">Readable Iterator</a>,
|
||||
<a href="#concept:WritableIterator">Writable Iterator</a>,
|
||||
and <a href="#concept:SwappableIterator">Swappable Iterator</a>.
|
||||
|
||||
|
||||
|
||||
<h3>Associated Types</h3>
|
||||
|
||||
<Table border>
|
||||
|
||||
<tr>
|
||||
<td>Reference type</td>
|
||||
<td><tt>std::iterator_traits<X>::reference</tt></td>
|
||||
<td>The return type of dereferencing the iterator, which must be
|
||||
<tt>T&</tt>.</td>
|
||||
</tr>
|
||||
|
||||
<!-- I don't think this is necessary
|
||||
<tr>
|
||||
<td>Pointer type</td>
|
||||
<td><tt>std::iterator_traits<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>std::return_category<X>::type</tt></td>
|
||||
<td>
|
||||
A type convertible to <tt>std::mutable_lvalue_iterator_tag</tt>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
<!-- no longer needed since the return type is specified as reference in the readable iterator
|
||||
<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>std::iterator_traits<X>::reference</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>
|
||||
<!--------------------------------------------------------------------------->
|
||||
|
||||
<H3><A NAME="concept:ForwardTraversalIterator"></A>
|
||||
Forward Traversal Iterator
|
||||
</H3>
|
||||
|
||||
The Forward Iterator is an iterator that can be incremented. Also, it
|
||||
is permissible to make multiple passes through the iterator's range.
|
||||
|
||||
<h3>Refinement of</h3>
|
||||
|
||||
<A href="http://www.boost.org/libs/utility/CopyConstructible.html">Copy Constructible</A>,
|
||||
<A href="http://www.boost.org/libs/utility/Assignable.html">Assignable</A>,
|
||||
<A href="http://www.sgi.com/tech/stl/DefaultConstructible.html">Default Constructible</A>, and
|
||||
<A href="http://www.sgi.com/tech/stl/EqualityComparable.html">Equality Comparable</A>
|
||||
|
||||
|
||||
<h3>Associated types</h3>
|
||||
|
||||
<Table border>
|
||||
|
||||
<tr>
|
||||
<td>Difference Type</td>
|
||||
<td><tt>std::iterator_traits<X>::difference_type</tt></td>
|
||||
<td>
|
||||
A signed integral type used for representing distances
|
||||
between iterators that point into the same range.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Traversal Category</td>
|
||||
<td><tt>std::traversal_category<X>::type</tt></td>
|
||||
<td>
|
||||
A type convertible to <tt>std::forward_traversal_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>i++</tt></td><td> </td><td>convertible to <tt>const X&</tt></td>
|
||||
</tr>
|
||||
</Table>
|
||||
|
||||
<p>
|
||||
<hr>
|
||||
<!--------------------------------------------------------------------------->
|
||||
|
||||
<H3><A NAME="concept:BidirectionalTraversalIterator"></A>
|
||||
Bidirectional Traversal Iterator
|
||||
</H3>
|
||||
|
||||
An iterator that can be incremented and decremented.
|
||||
|
||||
<h3>Refinement of</h3>
|
||||
|
||||
<a href="#concept:ForwardTraversalIterator">Forward Traversal Iterator</a>
|
||||
|
||||
<h3>Associated types</h3>
|
||||
|
||||
<Table border>
|
||||
<tr>
|
||||
<td>Traversal Category</td>
|
||||
<td><tt>std::traversal_category<X>::type</tt></td>
|
||||
<td>
|
||||
A type convertible to <tt>std::bidirectional_traversal_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>convertible to <tt>const X&</tt></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>
|
||||
<hr>
|
||||
<!--------------------------------------------------------------------------->
|
||||
|
||||
<H3><A NAME="concept:RandomAccessTraversalIterator"></A>
|
||||
Random Access Traversal Iterator
|
||||
</H3>
|
||||
|
||||
An iterator that provides constant-time methods for moving forward and
|
||||
backward in arbitrary-sized steps.
|
||||
|
||||
<h3>Refinement of</h3>
|
||||
|
||||
<a href="#concept:BidirectionalTraversalIterator">Bidirectional Traversal Iterator</a> and
|
||||
<A href="http://www.sgi.com/tech/stl/LessThanComparable.html">Less Than Comparable</A> where <tt><</tt> is a total ordering
|
||||
|
||||
<h3>Associated types</h3>
|
||||
|
||||
<Table border>
|
||||
<tr>
|
||||
<td>Traversal Category</td>
|
||||
<td><tt>std::traversal_category<X>::type</tt></td>
|
||||
<td>
|
||||
A type convertible to <tt>std::random_access_traversal_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>std::iterator_traits<X>::difference_type</tt></td>
|
||||
</tr>
|
||||
<tr><td>Element operator</td>
|
||||
<td><tt>i[n]</tt></td>
|
||||
<td><tt>X</tt> must also be a model of
|
||||
<a href="#concept:ReadableIterator">Readable Iterator</a>. </td>
|
||||
<td><tt>std::iterator_traits<X>::reference</tt></td>
|
||||
</tr>
|
||||
<tr><td>Element assignment</td>
|
||||
<td><tt>i[n] = t</tt></td>
|
||||
<td><tt>X</tt> must also be a model of
|
||||
<a href="#concept:WritableIterator">Writable Iterator</a>.</td>
|
||||
<td>unspecified</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>
|
||||
|
||||
<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>
|
||||
Reference in New Issue
Block a user