1<?xml version="1.0"?> 2<concept name="OutputIterator" 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 <param name="ValueType" role="value-type"/> 18 19 <use-header name="iterator"/> 20 21 <models-sentence>The iterator type <arg num="1"/> (with value type <arg num="2"/>) must be a model of <self/>.</models-sentence> 22 23 <description> 24 <para>An output iterator is an iterator that can write a sequence of 25 values. It is single-pass (old values of the iterator cannot be 26 re-used), and write-only.</para> 27 28 <para>An output iterator represents a position in a (possibly infinite) 29 sequence. Therefore, the iterator can point into the sequence (returning 30 a value when dereferenced and being incrementable), or be off-the-end 31 (and not dereferenceable or incrementable).</para> 32 </description> 33 34 <models const="no" testable="yes" concept="Assignable"> 35 <type name="Iter"/> 36 </models> 37 38 <models const="no" testable="yes" concept="Assignable"> 39 <type name="ValueType"/> 40 </models> 41 42 <models const="no" testable="yes" concept="DefaultConstructible"> 43 <type name="Iter"/> 44 </models> 45 46 <models const="no" testable="yes" concept="EqualityComparable"> 47 <type name="Iter"/> 48 </models> 49 50 <associated-type name="value_type"> 51 <get-member-type name="value_type"> 52 <apply-template name="std::iterator_traits"> 53 <type name="Iter"/> 54 </apply-template> 55 </get-member-type> 56 <description><simpara>The stated value type of the iterator (should be 57 <code>void</code> for an output iterator that does not model some other 58 iterator concept).</simpara></description> 59 </associated-type> 60 61 <associated-type name="difference_type"> 62 <get-member-type name="difference_type"> 63 <apply-template name="std::iterator_traits"> 64 <type name="Iter"/> 65 </apply-template> 66 </get-member-type> 67 <description><simpara>The difference type of the iterator</simpara></description> 68 </associated-type> 69 70 <associated-type name="category"> 71 <get-member-type name="iterator_category"> 72 <apply-template name="std::iterator_traits"> 73 <type name="Iter"/> 74 </apply-template> 75 </get-member-type> 76 <description><simpara>The category of the iterator</simpara></description> 77 </associated-type> 78 79 <notation variables="i j"> 80 <sample-value> 81 <type name="Iter"/> 82 </sample-value> 83 </notation> 84 85 <notation variables="x"> 86 <sample-value> 87 <type name="ValueType"/> 88 </sample-value> 89 </notation> 90 91 <valid-type-expression name="Category tag"> 92 <description/> 93 <type name="category"/> 94 <return-type> 95 <derived-from testable="yes"> 96 <type name="std::output_iterator_tag"/> 97 </derived-from> 98 <models-as-first-arg const="no" testable="yes" concept="DefaultConstructible"/> 99 <models-as-first-arg const="no" testable="yes" concept="CopyConstructible"/> 100 </return-type> 101 </valid-type-expression> 102 103 <valid-type-expression name="Difference type properties"> 104 <description/> 105 <type name="difference_type"/> 106 <return-type> 107 <models-as-first-arg const="no" testable="yes" concept="SignedInteger"/> 108 </return-type> 109 </valid-type-expression> 110 111 <valid-expression name="Dereference"> 112 <dereference> 113 <sample-value><type name="Iter"/></sample-value> 114 </dereference> 115 <return-type/> 116 <precondition><code>i</code> is incrementable (not 117 off-the-end)</precondition> 118 </valid-expression> 119 120 <valid-expression name="Dereference and assign"> 121 <assign> 122 <dereference> 123 <sample-value><type name="Iter"/></sample-value> 124 </dereference> 125 <sample-value><const><reference-to><type name="ValueType"/></reference-to></const></sample-value> 126 </assign> 127 <return-type/> 128 <precondition><code>i</code> is incrementable (not 129 off-the-end)</precondition> 130 <postcondition><code>*i</code> may not be written to again until it has 131 been incremented.</postcondition> 132 </valid-expression> 133 134 <valid-expression name="Preincrement"> 135 <preincrement> 136 <sample-value><reference-to><type name="Iter"/></reference-to></sample-value> 137 </preincrement> 138 <return-type> 139 <require-same-type testable="yes"> 140 <reference-to><type name="Iter"/></reference-to> 141 </require-same-type> 142 </return-type> 143 <precondition><code>i</code> is incrementable (not 144 off-the-end)</precondition> 145 </valid-expression> 146 147 <valid-expression name="Postincrement"> 148 <postincrement> 149 <sample-value><reference-to><type name="Iter"/></reference-to></sample-value> 150 </postincrement> 151 <return-type/> 152 <precondition><code>i</code> is incrementable (not 153 off-the-end)</precondition> 154 <semantics>Equivalent to <code>(void)(++i)</code></semantics> 155 <postcondition><code>i</code> is dereferenceable or 156 off-the-end</postcondition> 157 </valid-expression> 158 159 <valid-expression name="Postincrement, dereference, and assign"> 160 <assign> 161 <dereference> 162 <postincrement> 163 <sample-value><reference-to><type name="Iter"/></reference-to></sample-value> 164 </postincrement> 165 </dereference> 166 <sample-value><const><reference-to><type name="ValueType"/></reference-to></const></sample-value> 167 </assign> 168 <return-type/> 169 <precondition><code>i</code> is incrementable (not 170 off-the-end)</precondition> 171 <semantics>Equivalent to <code>{*i = t; ++i;}</code></semantics> 172 <postcondition><code>i</code> is dereferenceable or 173 off-the-end</postcondition> 174 </valid-expression> 175 176 <complexity> 177 All iterator operations must take amortized constant time. 178 </complexity> 179 180 <example-model> 181 <type name="std::ostream_iterator"/> 182 <type name="..."/> 183 </example-model> 184 185 <example-model> 186 <type name="std::insert_iterator"/> 187 <type name="..."/> 188 </example-model> 189 190 <example-model> 191 <type name="std::front_insert_iterator"/> 192 <type name="..."/> 193 </example-model> 194 195 <example-model> 196 <type name="std::back_insert_iterator"/> 197 <type name="..."/> 198 </example-model> 199 200 <see-also concept="InputIterator"/> 201 <see-also concept="ForwardIterator"/> 202 203</concept> 204