ceph/src/boost/libs/property_map/doc/vector_property_map.html

   1 <HTML>
   2 <!--
   3      Copyright (c) Jeremy Siek, Lie-Quan Lee, and Andrew Lumsdaine 2000
   4
   5      Distributed under the Boost Software License, Version 1.0.
   6      (See accompanying file LICENSE_1_0.txt or copy at
   7      http://www.boost.org/LICENSE_1_0.txt)
   8   -->
   9 <Head>
  10 <Title>Vector Property Map</Title>
  11 <BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b"
  12         ALINK="#ff0000">
  13 <IMG SRC="../../../boost.png"
  14      ALT="C++ Boost" width="277" height="86">
  15
  16 <BR Clear>
  17
  18
  19 <H2><A NAME="sec:vector-property-map"></A>
  20 </h2>
  21 <PRE>
  22 template&lt;typename T, typename IndexMap = identity_property_map&gt;
  23 class vector_property_map;
  24 </PRE>
  25
  26 <P>
  27 This property map is used to efficiently store properties for a variable
  28 number of elements. It's somewhere between <a
  29 href="associative_property_map.html">associative_property_map</a> and
  30 <a href="iterator_property_map.html">iterator_property_map</a>. The latter
  31 is very fast, but requires that the number of stored elements is known
  32 when creating property map. The former does not have this requirement, but
  33 is slower, and requires stored elements to be comparable.
  34
  35 <p>
  36 The <tt>vector_property_map</tt> uses mapping from key to indices,
  37 and allows to add new elements. It accoplishes this by storing values
  38 in a vector, which is resized on demand.
  39
  40 <p>
  41 Note that <tt>vector_property_map</tt> does not provide reference/pointer
  42 stability for stored values.
  43
  44 <h3>Example</h3>
  45
  46 <a href="../example/example3.cpp">example3.cpp</a>:
  47
  48 <p>
  49 <pre>
  50 #include &lt;boost/property_map/vector_property_map.hpp&gt;
  51 #include &lt;string&gt;
  52 #include &lt;iostream&gt;
  53
  54 int main()
  55 {
  56     boost::vector_property_map&lt;std::string&gt; m;
  57
  58     // Assign string to '4'.
  59     m[4] = &quot;e&quot;;
  60     std::cout &lt;&lt; &quot;'&quot; &lt;&lt; m[4] &lt;&lt; &quot;'\n&quot;;
  61
  62     // Grab string from '10'. Since none is associated,
  63     // &quot;&quot; will be returned.
  64     std::cout &lt;&lt; &quot;'&quot; &lt;&lt; m[10] &lt;&lt; &quot;'\n&quot;;
  65 }
  66 </pre>
  67
  68 <H3>Where Defined</H3>
  69
  70 <P>
  71 <a href="../../../boost/property_map/vector_property_map.hpp"><TT>boost/property_map/vector_property_map.hpp</TT></a>
  72
  73 <p>
  74 <H3>Model Of</H3>
  75
  76 <a href="./LvaluePropertyMap.html">Lvalue Property Map</a>
  77
  78 <P>
  79
  80 <H3>Template Parameters</H3>
  81
  82 <P>
  83
  84 <TABLE border>
  85 <TR>
  86 <th>Parameter</th><th>Description</th><th>Default</th>
  87 </tr>
  88
  89
  90 <TR>
  91 <TD><TT>T</TT></TD>
  92 <TD>The type of property value. Must be both <a
  93 href="http://www.sgi.com/tech/stl/Assignable.html">Assignable</a>
  94 and <a
  95 href="http://www.sgi.com/tech/stl/DefaultConstructible.html">DefaultConstructible</a>.
  96 </TD>
  97 <TD>&nbsp;</td>
  98 </tr>
  99
 100 <TR>
 101 <TD><TT>IndexMap</TT></TD> <TD>Must be a model of <a
 102 href="./ReadablePropertyMap.html">Readable Property Map</a>
 103 and the value type must be convertible to
 104 <tt>std::vector&lt;T&gt;::size_type</tt>.</TD>
 105 <TD><a href="identity_property_map.html">identity_property_map</a></TD>
 106 </TR>
 107
 108 </TABLE>
 109 <P>
 110
 111 <H3>Members</H3>
 112
 113 <P>
 114 In addition to the methods and functions required by <a
 115 href="./LvaluePropertyMap.html">Lvalue Property Map</a>, this
 116 class has the following members.
 117
 118 <hr>
 119
 120 <pre>
 121 vector_property_map(const IndexMap& index = IndexMap())
 122 </pre>
 123 Constructor which takes an index map.
 124
 125 <hr>
 126
 127 <pre>
 128 vector_property_map(unsigned initial_size, const IndexMap& index = IndexMap())
 129 </pre>
 130 This constructor version allows to specify maximum index of element
 131 that will be stored. Correct number will improve performance, but semantic
 132 is always the same.
 133
 134 <hr>
 135
 136 <pre>
 137 vector_property_map(const vector_property_map&amp;)
 138 </pre>
 139 Copy constructor. The copy will share the same data and changes
 140 made to it will affect original property map.
 141
 142 <hr>
 143
 144 <pre>
 145 vector_property_map&amp; operator=(const vector_property_map&amp;)
 146 </pre>
 147 Assignment operator. The semantic is the same as for copy constructor.
 148
 149 <hr>
 150
 151 <pre>
 152 reference operator[](const key_type&amp; v) const
 153 </pre>
 154 The operator bracket for property access.
 155
 156 <hr>
 157
 158 <pre>
 159 std::vector&lt;T&gt;::iterator storage_begin()
 160 std::vector&lt;T&gt;::iterator storage_end()
 161 std::vector&lt;T&gt;::const_iterator storage_begin()
 162 std::vector&lt;T&gt;::const_iterator storage_end()
 163 </pre>
 164
 165 <p>This group of methods gives access to begin and end iterators of the
 166 underlying vector.</p>
 167
 168 <p><b>Rationale:</b> The methods are handy, for example, when it's needed to
 169 specify a single value for all elements in a freshly created property map. The
 170 methods are not called simply &quot;begin&quot; and &quot;end&quot; since
 171 conceptually, <tt>vector_property_map</tt> is unbounded map, and has no end
 172 iterator. The direct access to the underlying method is not provided, since
 173 it would decrease encapsulation and make future performance tuning dangerous.
 174
 175 <p><b>Acknolegements:</b> Matthias Troyer suggested adding those functions.
 176
 177 <hr>
 178
 179 <pre>
 180 void reserve(unsigned size)
 181 </pre>
 182 Reserve the space for storing elements with maximum index of 'size'. Unless
 183 element with greater index is accesses, all accesses will be take O(1) time.
 184
 185
 186 <hr>
 187
 188 <h3>Non-Member functions</h3>
 189
 190 <hr>
 191
 192 <pre>
 193 template<typename T, typename IndexMap>
 194 vector_property_map<T, IndexMap>
 195 make_vector_property_map(IndexMap index)
 196 {
 197   return vector_property_map<T, IndexMap>(index);
 198 }
 199 </pre>
 200 A function for conveniently creating a vector property map.
 201
 202 <br>
 203 <HR>
 204 <TABLE>
 205 <TR valign=top>
 206 <TD nowrap>Copyright &copy 2002</TD><TD>
 207 <a HREF="http://www.boost.org/people/jeremy_siek.htm">Jeremy Siek</a>,
 208 Indiana University (<A
 209 HREF="mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</A>)<br>
 210 <A HREF="http://www.boost.org/people/liequan_lee.htm">Lie-Quan Lee</A>, Indiana University (<A HREF="mailto:llee1@osl.iu.edu">llee1@osl.iu.edu</A>)<br>
 211 <A HREF="http://www.osl.iu.edu/~lums">Andrew Lumsdaine</A>,
 212 Indiana University (<A
 213 HREF="mailto:lums@osl.iu.edu">lums@osl.iu.edu</A>)
 214 </TD></TR>
 215 <tr>
 216 <td nowrap>Copyright &copy; 2003</td><td>Vladimir Prus</td>
 217 </tr>
 218 </TABLE>
 219
 220 </BODY>
 221 </HTML>