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

   1 <?xml version="1.0"?>
   2 <concept name="InputIterator" 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
  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>