• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<?xml version="1.0"?>
2<concept name="ForwardIterator" category="Iterator"><!--
3Based on concepts from the SGI Standard Template Library documentation:
4Copyright (c) 1996-1999
5Silicon Graphics Computer Systems, Inc.
6
7Copyright (c) 1994
8Hewlett-Packard Company
9--><!--
10Copyright 2000-2001 University of Notre Dame du Lac.
11Copyright 2001-2002 Indiana University.
12Some concepts based on versions from the MTL draft manual and Boost Graph
13and Property Map documentation:
14Copyright (c) Jeremy Siek, Lie-Quan Lee, and Andrew Lumsdaine 2000
15-->
16  <param name="Iter" role="iterator-type"/>
17
18  <use-header name="iterator"/>
19
20  <models-sentence>The iterator type <arg num="1"/> must be a model of <self/>.</models-sentence>
21
22  <description>
23  <para>A forward iterator is an iterator that can read through a sequence of
24  values.  It is multi-pass (old values of the iterator can be
25  re-used), and can be either mutable (data pointed to by it can be
26  changed) or not mutable.</para>
27
28  <para>An iterator represents a position in a sequence.  Therefore, the
29  iterator can point into the sequence (returning a value when dereferenced
30  and being incrementable), or be off-the-end (and not dereferenceable or
31  incrementable).</para>
32  </description>
33
34  <associated-type name="value_type">
35    <get-member-type name="value_type">
36      <apply-template name="std::iterator_traits">
37	<type name="Iter"/>
38      </apply-template>
39    </get-member-type>
40    <description><simpara>The value type of the iterator</simpara></description>
41  </associated-type>
42
43  <refines const="no" concept="InputIterator"/>
44  <refines const="no" concept="OutputIterator"/>
45
46<!-- DPG doesn't understand this
47  <models const="no" testable="yes" concept="Input Iterator">
48    <type name="Iter"/>
49  </models>
50-->
51<!--
52  <models-when-mutable concept="Output Iterator">
53    <type name="Iter"/>
54    <type name="value_type"/>
55  </models-when-mutable>
56-->
57
58  <notation variables="i j">
59    <sample-value>
60      <type name="Iter"/>
61    </sample-value>
62  </notation>
63
64  <associated-type name="category">
65    <get-member-type name="iterator_category">
66      <apply-template name="std::iterator_traits">
67	<type name="Iter"/>
68      </apply-template>
69    </get-member-type>
70    <description><simpara>The category of the iterator</simpara></description>
71  </associated-type>
72
73  <notation variables="x">
74    <sample-value>
75      <type name="value_type"/>
76    </sample-value>
77  </notation>
78
79  <valid-type-expression name="Category tag">
80    <description/>
81    <type name="category"/>
82    <return-type>
83      <derived-from testable="yes">
84	<type name="std::forward_iterator_tag"/>
85      </derived-from>
86    </return-type>
87  </valid-type-expression>
88
89  <valid-expression name="Dereference">
90    <dereference>
91      <sample-value><type name="Iter"/></sample-value>
92    </dereference>
93    <return-type>
94      <require-same-type testable="yes">
95	<const-if-not-mutable>
96	  <reference-to><type name="value_type"/></reference-to>
97	</const-if-not-mutable>
98      </require-same-type>
99    </return-type>
100    <precondition><code>i</code> is incrementable (not
101    off-the-end)</precondition>
102  </valid-expression>
103
104  <valid-expression name="Member access">
105    <pointer-member>
106      <sample-value><type name="Iter"/></sample-value>
107    </pointer-member>
108    <return-type>
109      <require-same-type testable="yes">
110	<const-if-not-mutable>
111	  <pointer-to><type name="value_type"/></pointer-to>
112	</const-if-not-mutable>
113      </require-same-type>
114    </return-type>
115    <precondition><code>i</code> is incrementable (not
116    off-the-end)</precondition>
117  </valid-expression>
118
119  <valid-expression name="Preincrement">
120    <preincrement>
121      <sample-value><reference-to><type name="Iter"/></reference-to></sample-value>
122    </preincrement>
123    <return-type>
124      <require-same-type testable="yes">
125	<reference-to><type name="Iter"/></reference-to>
126      </require-same-type>
127    </return-type>
128    <precondition><code>i</code> is incrementable (not
129    off-the-end)</precondition>
130  </valid-expression>
131
132  <valid-expression name="Postincrement">
133    <postincrement>
134      <sample-value><reference-to><type name="Iter"/></reference-to></sample-value>
135    </postincrement>
136    <return-type>
137      <require-same-type testable="yes"><type name="Iter"/></require-same-type>
138    </return-type>
139    <precondition><code>i</code> is incrementable (not
140    off-the-end)</precondition>
141    <semantics>Equivalent to <code>{Iter j = i; ++i; return j;}</code></semantics>
142    <postcondition><code>i</code> is dereferenceable or
143    off-the-end</postcondition>
144  </valid-expression>
145
146  <complexity>
147  All iterator operations must take amortized constant time.
148  </complexity>
149
150  <invariant name="Predecrement must return object">
151  <code>&amp;i = &amp;(++i)</code>
152  </invariant>
153
154  <invariant name="Unique path through sequence">
155  <code>i == j</code> implies <code>++i == ++j</code>
156  </invariant>
157
158  <example-model>
159    <pointer-to>
160      <type name="T"/>
161    </pointer-to>
162  </example-model>
163
164  <example-model>
165    <get-member-type name="iterator">
166      <apply-template name="std::hash_set">
167	<type name="T"/>
168      </apply-template>
169    </get-member-type>
170  </example-model>
171
172  <see-also concept="BidirectionalIterator"/>
173
174</concept>
175