1<?xml version="1.0"?> 2<concept name="InputIterator" 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>An input iterator is an iterator that can read through a sequence of 24 values. It is single-pass (old values of the iterator cannot be 25 re-used), and read-only.</para> 26 27 <para>An input iterator represents a position in a sequence. Therefore, the 28 iterator can point into the sequence (returning a value when dereferenced 29 and being incrementable), or be off-the-end (and not dereferenceable or 30 incrementable).</para> 31 </description> 32 33 <refines const="no" concept="Assignable"/> 34 <refines const="no" concept="DefaultConstructible"/> 35 <refines const="no" concept="EqualityComparable"/> 36 37 <notation variables="i j"> 38 <sample-value> 39 <type name="Iter"/> 40 </sample-value> 41 </notation> 42 43 <associated-type name="value_type"> 44 <get-member-type name="value_type"> 45 <apply-template name="std::iterator_traits"> 46 <type name="Iter"/> 47 </apply-template> 48 </get-member-type> 49 <description><simpara>The value type of the iterator (not necessarily what 50 <code>*i</code> returns)</simpara></description> 51 </associated-type> 52 53 <associated-type name="difference_type"> 54 <get-member-type name="difference_type"> 55 <apply-template name="std::iterator_traits"> 56 <type name="Iter"/> 57 </apply-template> 58 </get-member-type> 59 <description><simpara>The difference type of the iterator</simpara></description> 60 </associated-type> 61 62 <associated-type name="category"> 63 <get-member-type name="iterator_category"> 64 <apply-template name="std::iterator_traits"> 65 <type name="Iter"/> 66 </apply-template> 67 </get-member-type> 68 <description><simpara>The category of the iterator</simpara></description> 69 </associated-type> 70 71 <notation variables="x"> 72 <sample-value> 73 <type name="value_type"/> 74 </sample-value> 75 </notation> 76 77 <valid-type-expression name="Category tag"> 78 <description/> 79 <type name="category"/> 80 <return-type> 81 <derived-from testable="yes"> 82 <type name="std::input_iterator_tag"/> 83 </derived-from> 84 <models-as-first-arg const="no" testable="yes" concept="DefaultConstructible"/> 85 <models-as-first-arg const="no" testable="yes" concept="CopyConstructible"/> 86 </return-type> 87 </valid-type-expression> 88 89 <valid-type-expression name="Value type copy constructibility"> 90 <description/> 91 <type name="value_type"/> 92 <return-type> 93 <models-as-first-arg const="no" testable="yes" concept="CopyConstructible"/> 94 </return-type> 95 </valid-type-expression> 96 97 <valid-type-expression name="Difference type properties"> 98 <description/> 99 <type name="difference_type"/> 100 <return-type> 101 <models-as-first-arg const="no" testable="yes" concept="SignedInteger"/> 102 </return-type> 103 </valid-type-expression> 104 105 <valid-expression name="Dereference"> 106 <dereference> 107 <sample-value><type name="Iter"/></sample-value> 108 </dereference> 109 <return-type> 110 <convertible-to testable="yes"><type name="value_type"/></convertible-to> 111 </return-type> 112 <precondition><code>i</code> is incrementable (not 113 off-the-end)</precondition> 114 </valid-expression> 115 116 <valid-expression name="Preincrement"> 117 <preincrement> 118 <sample-value><reference-to><type name="Iter"/></reference-to></sample-value> 119 </preincrement> 120 <return-type> 121 <require-same-type testable="yes"> 122 <reference-to><type name="Iter"/></reference-to> 123 </require-same-type> 124 </return-type> 125 <precondition><code>i</code> is incrementable (not 126 off-the-end)</precondition> 127 </valid-expression> 128 129 <valid-expression name="Postincrement"> 130 <postincrement> 131 <sample-value><reference-to><type name="Iter"/></reference-to></sample-value> 132 </postincrement> 133 <return-type/> 134 <precondition><code>i</code> is incrementable (not 135 off-the-end)</precondition> 136 <semantics>Equivalent to <code>(void)(++i)</code></semantics> 137 <postcondition><code>i</code> is dereferenceable or 138 off-the-end</postcondition> 139 </valid-expression> 140 141 <valid-expression name="Postincrement and dereference"> 142 <dereference> 143 <postincrement> 144 <sample-value><reference-to><type name="Iter"/></reference-to></sample-value> 145 </postincrement> 146 </dereference> 147 <return-type> 148 <convertible-to testable="yes"><type name="value_type"/></convertible-to> 149 </return-type> 150 <precondition><code>i</code> is incrementable (not 151 off-the-end)</precondition> 152 <semantics>Equivalent to <code>{value_type t = *i; ++i; return t;}</code></semantics> 153 <postcondition><code>i</code> is dereferenceable or 154 off-the-end</postcondition> 155 </valid-expression> 156 157 <complexity> 158 All iterator operations must take amortized constant time. 159 </complexity> 160 161 <example-model> 162 <type name="std::istream_iterator"/> 163 </example-model> 164 165 <see-also concept="OutputIterator"/> 166 <see-also concept="ForwardIterator"/> 167 168</concept> 169