ceph/src/boost/libs/concept_check/doc/reference/OutputIterator.xml

   1 <?xml version="1.0"?>
   2 <concept name="OutputIterator" category="Iterator"><!--
   3 Based on concepts from the SGI Standard Template Library documentation:
   4 Copyright (c) 1996-1999
   5 Silicon Graphics Computer Systems, Inc.
   6
   7 Copyright (c) 1994
   8 Hewlett-Packard Company
   9 --><!--
  10 Copyright 2000-2001 University of Notre Dame du Lac.
  11 Copyright 2001-2002 Indiana University.
  12 Some concepts based on versions from the MTL draft manual and Boost Graph
  13 and Property Map documentation:
  14 Copyright (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>