1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
<HTML>
<!--
-- 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_category</Title>
<!-- Generated by htmldoc -->
</HEAD>
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b"
ALINK="#ff0000">
<IMG SRC="CorpID.gif"
ALT="SGI" HEIGHT="43" WIDTH="151">
<!--end header-->
<BR Clear>
<H1>iterator_category</H1>
<Table CellPadding=0 CellSpacing=0 width=100%>
<TR>
<TD Align=left><Img src = "iterators.gif" Alt="" WIDTH = "194" HEIGHT = "38" ></TD>
<TD Align=right><Img src = "function.gif" Alt="" WIDTH = "194" HEIGHT = "38" ></TD>
</TR>
<TR>
<TD Align=left VAlign=top><b>Category</b>: iterators</TD>
<TD Align=right VAlign=top><b>Component type</b>: function</TD>
</TR>
</Table>
<h3>Prototype</h3>
<tt>Iterator_category</tt> is overloaded; it is in fact six different functions.
<pre>
inline output_iterator_tag iterator_category(const output_iterator&);
template <class T, class Distance>
inline <A href="input_iterator_tag.html">input_iterator_tag</A>
iterator_category(const <A href="input_iterator.html">input_iterator</A><T, Distance>&);
template <class T, class Distance>
inline <A href="forward_iterator_tag.html">forward_iterator_tag</A>
iterator_category(const <A href="forward_iterator.html">forward_iterator</A><T, Distance>&);
template <class T, class Distance>
inline <A href="bidirectional_iterator_tag.html">bidirectional_iterator_tag</A>
iterator_category(const <A href="bidirectional_iterator.html">bidirectional_iterator</A><T, Distance>&);
template <class T, class Distance>
inline <A href="random_access_iterator_tag.html">random_access_iterator_tag</A>
iterator_category(const <A href="random_access_iterator.html">random_access_iterator</A><T, Distance>&);
template <class T>
inline <A href="random_access_iterator_tag.html">random_access_iterator_tag</A> iterator_category(const T*);
</pre>
<h3>Description</h3>
<tt>Iterator_category</tt> is an <A href="iterator_tags.html">iterator tag</A> function: it is used to
determine the category to which an iterator belongs. Specifically,
every iterator must belong to a type that is a model of the concept
<A href="OutputIterator.html">Output Iterator</A>, <A href="InputIterator.html">Input Iterator</A>, <A href="ForwardIterator.html">Forward Iterator</A>,
<A href="BidirectionalIterator.html">Bidirectional Iterator</A>, or <A href="RandomAccessIterator.html">Random Access Iterator</A>. <A href="#1">[1]</A>
<tt>Iterator_category</tt> returns an object of class
<tt><A href="output_iterator_tag.html">output_iterator_tag</A></tt>, <tt><A href="input_iterator_tag.html">input_iterator_tag</A></tt>,
<tt><A href="forward_iterator_tag.html">forward_iterator_tag</A></tt>, or <tt><A href="random_access_iterator_tag.html">random_access_iterator_tag</A></tt>,
depending on which concept the type of <tt>iterator_category</tt>'s
argument is a model of. <A href="#2">[2]</A> This information is useful in the case of
an algorithm that has a sensible definition for more than one category
of iterator, but whose definition is different depending on the category.
<P>
Although <tt>iterator_category</tt> looks like a single function whose
return type depends on its argument type, in reality it is a set
of functions; the name <tt>iterator_category</tt> is overloaded.
The function <tt>iterator_category</tt> must
be overloaded for every iterator type.
<P>
In practice, ensuring that <tt>iterator_category</tt> is defined requires
essentially no work at all. It is already defined for pointers, and
for the base classes <tt><A href="input_iterator.html">input_iterator</A></tt>, <tt><A href="output_iterator.html">output_iterator</A></tt>,
<tt><A href="forward_iterator.html">forward_iterator</A></tt>, <tt><A href="bidirectional_iterator.html">bidirectional_iterator</A></tt>, and
<tt><A href="random_access_iterator.html">random_access_iterator</A></tt>. If you are implementing a new type of
forward iterator, for example, you can simply derive it from the base
class <tt><A href="forward_iterator.html">forward_iterator</A></tt>; this means that <tt>iterator_category</tt>
(along with <tt><A href="distance_type.html">distance_type</A></tt> and <tt><A href="value_type.html">value_type</A></tt>) will
automatically be defined for your iterator. These base classes are
empty: they contain no member functions or member variables, but
only type information. Using them should therefore incur no overhead.
<P>
Note that, while the function <tt>iterator_category</tt> was present in the
original STL, it is no longer present in the most recent draft C++
standard: it has been replaced by the <tt><A href="iterator_traits.html">iterator_traits</A></tt> class.
At present both mechanisms are supported <A href="#3">[3]</A>, but eventually
<tt>iterator_category</tt> will be removed.
<h3>Definition</h3>
Defined in the standard header <A href="iterator">iterator</A>, and in the
nonstandard backward-compatibility header <A href="iterator.h">iterator.h</A>.
This function is no longer part of the C++ standard, although
it was present in early drafts of the standard. It is retained
in this implementation for backward compatibility.
<h3>Requirements on types</h3>
The argument of <tt>iterator_category</tt> must be an iterator.
<h3>Preconditions</h3>
None. <tt>Iterator_category</tt>'s argument is even permitted to be
a singular iterator.
<h3>Complexity</h3>
At most amortized constant time. In many cases, a compiler should be
able to optimize away <tt>iterator_category</tt> entirely.
<h3>Example</h3>
<tt><A href="reverse.html">Reverse</A></tt> can be implemented for either
<A href="BidirectionalIterator.html">Bidirectional Iterators</A> or for <A href="RandomAccessIterator.html">Random Access Iterators</A>,
but the algorithm for <A href="RandomAccessIterator.html">Random Access Iterators</A> is more efficient.
Consequently, <tt><A href="reverse.html">reverse</A></tt> uses <tt>iterator_category</tt> to select
whichever algorithm is appropriate for the iterator type.
This dispatch takes place at compile time, and should not
incur any run-time penalty.
<pre>
template <class <A href="BidirectionalIterator.html">BidirectionalIterator</A>>
void __reverse(BidirectionalIterator first, BidirectionalIterator last,
<A href="bidirectional_iterator_tag.html">bidirectional_iterator_tag</A>) {
while (true)
if (first == last || first == --last)
return;
else
iter_swap(first++, last);
}
template <class <A href="RandomAccessIterator.html">RandomAccessIterator</A>>
void __reverse(RandomAccessIterator first, RandomAccessIterator last,
<A href="random_access_iterator_tag.html">random_access_iterator_tag</A>) {
while (first < last) iter_swap(first++, --last);
}
template <class <A href="BidirectionalIterator.html">BidirectionalIterator</A>>
inline void <A href="reverse.html">reverse</A>(BidirectionalIterator first, BidirectionalIterator last) {
__reverse(first, last, iterator_category(first));
}
</pre>
<h3>Notes</h3>
<P><A name="1">[1]</A>
The STL also defines one other concept, <A href="trivial.html">Trivial Iterator</A>.
This concept is introduced only for conceptual clarity, however,
in order to separate the axioms related to an object that refers
to another object from those related to iteration over a range.
In fact, the STL does not define any types that are <A href="trivial.html">Trivial Iterators</A>.
Although built-in C pointers may be <A href="trivial.html">Trivial Iterators</A>, the C
type system does not allow a distinction between pointers that are
<A href="trivial.html">Trivial Iterators</A> and pointers that are <A href="RandomAccessIterator.html">Random Access Iterators</A>
into C arrays. Consequently, there is no <A href="trivial.html">Trivial Iterator</A> category
tag.
<P><A name="2">[2]</A>
Any type that is a model of <A href="ForwardIterator.html">Forward Iterator</A> is also a model
of <A href="InputIterator.html">Input Iterator</A>, any type that is a model of
<A href="BidirectionalIterator.html">Bidirectional Iterator</A> is also a model of <A href="ForwardIterator.html">Forward Iterator</A>,
and any type that is a model of <A href="RandomAccessIterator.html">Random Access Iterator</A> is also
a model of <A href="BidirectionalIterator.html">Bidirectional Iterator</A>. <tt>Iterator_category</tt> must
return a tag representing the <i>most specific</i> concept that its
argument is a model of. If its argument is a <tt><A href="Vector.html">vector</A>::iterator</tt>,
for example, then it must return <tt><A href="random_access_iterator_tag.html">random_access_iterator_tag</A></tt>.
<P><A name="3">[3]</A>
The <tt><A href="iterator_traits.html">iterator_traits</A></tt> class
relies on a C++ feature known as <i>partial specialization</i>. Many of
today's compilers don't implement the complete standard; in
particular, many compilers do not support partial specialization. If
your compiler does not support partial specialization, then you will
not be able to use <tt><A href="iterator_traits.html">iterator_traits</A></tt>, and you will have to
continue using the functions <tt>iterator_category</tt>, <tt><A href="distance_type.html">distance_type</A></tt>,
and <tt><A href="value_type.html">value_type</A></tt>. This is one reason that those functions have
not yet been removed.
<h3>See also</h3>
The <A href="iterator_tags.html">Iterator Tags</A> overview, <tt><A href="iterator_traits.html">iterator_traits</A></tt>,
<tt><A href="distance_type.html">distance_type</A></tt>, <tt><A href="value_type.html">value_type</A></tt>,
<tt><A href="output_iterator_tag.html">output_iterator_tag</A></tt>, <tt><A href="input_iterator_tag.html">input_iterator_tag</A></tt>,
<tt><A href="forward_iterator_tag.html">forward_iterator_tag</A></tt>, <tt><A href="bidirectional_iterator_tag.html">bidirectional_iterator_tag</A></tt>,
<tt><A href="random_access_iterator_tag.html">random_access_iterator_tag</A></tt>
<!--start footer-->
<HR SIZE="6">
<A href="http://www.sgi.com/"><IMG SRC="surf.gif" HEIGHT="54" WIDTH="54"
ALT="[Silicon Surf]"></A>
<A HREF="index.html"><IMG SRC="stl_home.gif"
HEIGHT="54" WIDTH="54" ALT="[STL Home]"></A>
<BR>
<FONT SIZE="-2">
<A href="http://www.sgi.com/Misc/sgi_info.html" TARGET="_top">Copyright ©
1999 Silicon Graphics, Inc.</A> All Rights Reserved.</FONT>
<FONT SIZE="-3"><a href="http://www.sgi.com/Misc/external.list.html" TARGET="_top">TrademarkInformation</A>
</FONT>
<P>
</BODY>
</HTML>
|
