ceph/src/boost/libs/icl/doc/html/boost_icl/function_reference/element_iteration.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Element iteration</title>
   5 <link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
   7 <link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Icl">
   8 <link rel="up" href="../function_reference.html" title="Function Reference">
   9 <link rel="prev" href="iterator_related.html" title="Iterator related">
  10 <link rel="next" href="streaming__conversion.html" title="Streaming, conversion">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="iterator_related.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_reference.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="streaming__conversion.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section boost_icl_function_reference_element_iteration" lang="en">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="boost_icl.function_reference.element_iteration"></a><a class="link" href="element_iteration.html" title="Element iteration">Element
  28       iteration</a>
  29 </h3></div></div></div>
  30 <p>
  31         This section refers to <span class="emphasis"><em><span class="bold"><strong>element iteration</strong></span></em></span>
  32         over <span class="emphasis"><em><span class="bold"><strong>interval containers</strong></span></em></span>.
  33         Element iterators are available as associated types on interval sets and
  34         interval maps.
  35       </p>
  36 <div class="informaltable"><table class="table">
  37 <colgroup>
  38 <col>
  39 <col>
  40 </colgroup>
  41 <thead><tr>
  42 <th>
  43               <p>
  44                 Variant
  45               </p>
  46               </th>
  47 <th>
  48               <p>
  49                 Associated element iterator type for interval container <code class="computeroutput"><span class="identifier">T</span></code>
  50               </p>
  51               </th>
  52 </tr></thead>
  53 <tbody>
  54 <tr>
  55 <td>
  56               <p>
  57                 forward
  58               </p>
  59               </td>
  60 <td>
  61               <p>
  62                 <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">element_iterator</span></code>
  63               </p>
  64               </td>
  65 </tr>
  66 <tr>
  67 <td>
  68               <p>
  69                 const forward
  70               </p>
  71               </td>
  72 <td>
  73               <p>
  74                 <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">element_const_iterator</span></code>
  75               </p>
  76               </td>
  77 </tr>
  78 <tr>
  79 <td>
  80               <p>
  81                 reverse
  82               </p>
  83               </td>
  84 <td>
  85               <p>
  86                 <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">element_reverse_iterator</span></code>
  87               </p>
  88               </td>
  89 </tr>
  90 <tr>
  91 <td>
  92               <p>
  93                 const reverse
  94               </p>
  95               </td>
  96 <td>
  97               <p>
  98                 <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">element_const_reverse_iterator</span></code>
  99               </p>
 100               </td>
 101 </tr>
 102 </tbody>
 103 </table></div>
 104 <p>
 105         There are also associated iterators types <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">iterator</span></code>,
 106         <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">const_iterator</span></code>, <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">reverse_iterator</span></code>
 107         and <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">reverse_const_iterator</span></code> on interval containers.
 108         These are <span class="emphasis"><em><span class="bold"><strong>segment iterators</strong></span></em></span>.
 109         Segment iterators are "first citizen iterators". Iteration over
 110         segments is fast, compared to an iteration over elements, particularly if
 111         intervals are large. But if we want to view our interval containers as containers
 112         of elements that are usable with std::algoritms, we need to iterate over
 113         elements.
 114       </p>
 115 <p>
 116         Iteration over elements . . .
 117       </p>
 118 <div class="itemizedlist"><ul type="disc">
 119 <li>
 120           is possible only for integral or discrete <code class="computeroutput"><span class="identifier">domain_types</span></code>
 121 </li>
 122 <li>
 123           can be very <span class="emphasis"><em><span class="bold"><strong>slow</strong></span></em></span>
 124           if the intervals are very large.
 125         </li>
 126 <li>
 127           and is therefore <span class="emphasis"><em><span class="bold"><strong>depreciated</strong></span></em></span>
 128 </li>
 129 </ul></div>
 130 <p>
 131         On the other hand, sometimes iteration over interval containers on the element
 132         level might be desired, if you have some interface that works for <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">SortedAssociativeContainers</span></code>
 133         of elements and you need to quickly use it with an interval container. Accepting
 134         the poorer performance might be less bothersome at times than adjusting your
 135         whole interface for segment iteration.
 136       </p>
 137 <div class="caution"><table border="0" summary="Caution">
 138 <tr>
 139 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../doc/src/images/caution.png"></td>
 140 <th align="left">Caution</th>
 141 </tr>
 142 <tr><td align="left" valign="top"><p>
 143           So we advice you to choose element iteration over interval containers
 144           <span class="emphasis"><em><span class="bold"><strong>judiciously</strong></span></em></span>. Do not
 145           use element iteration <span class="emphasis"><em><span class="bold"><strong>by default or habitual</strong></span></em></span>.
 146           Always try to achieve results using member functions, global functions
 147           or operators (preferably inplace versions) or iteration over segments first.
 148         </p></td></tr>
 149 </table></div>
 150 <div class="informaltable"><table class="table">
 151 <colgroup>
 152 <col>
 153 <col>
 154 <col>
 155 </colgroup>
 156 <thead><tr>
 157 <th>
 158               <p>
 159                 <span class="emphasis"><em><span class="bold"><strong>Synopsis Complexities</strong></span></em></span>
 160               </p>
 161               </th>
 162 <th>
 163               <p>
 164                 interval<br> sets
 165               </p>
 166               </th>
 167 <th>
 168               <p>
 169                 interval<br> maps
 170               </p>
 171               </th>
 172 </tr></thead>
 173 <tbody>
 174 <tr>
 175 <td>
 176               <p>
 177                 <code class="computeroutput"><span class="identifier">J</span> <span class="identifier">elements_begin</span><span class="special">(</span><span class="identifier">T</span><span class="special">&amp;)</span></code>
 178               </p>
 179               </td>
 180 <td>
 181               <p>
 182                 <span class="emphasis"><em>O(1)</em></span>
 183               </p>
 184               </td>
 185 <td>
 186               <p>
 187                 <span class="emphasis"><em>O(1)</em></span>
 188               </p>
 189               </td>
 190 </tr>
 191 <tr>
 192 <td>
 193               <p>
 194                 <code class="computeroutput"><span class="identifier">J</span> <span class="identifier">elements_end</span><span class="special">(</span><span class="identifier">T</span><span class="special">&amp;)</span></code>
 195               </p>
 196               </td>
 197 <td>
 198               <p>
 199                 <span class="emphasis"><em>O(1)</em></span>
 200               </p>
 201               </td>
 202 <td>
 203               <p>
 204                 <span class="emphasis"><em>O(1)</em></span>
 205               </p>
 206               </td>
 207 </tr>
 208 <tr>
 209 <td>
 210               <p>
 211                 <code class="computeroutput"><span class="identifier">J</span> <span class="identifier">elements_rbegin</span><span class="special">(</span><span class="identifier">T</span><span class="special">&amp;)</span></code>
 212               </p>
 213               </td>
 214 <td>
 215               <p>
 216                 <span class="emphasis"><em>O(1)</em></span>
 217               </p>
 218               </td>
 219 <td>
 220               <p>
 221                 <span class="emphasis"><em>O(1)</em></span>
 222               </p>
 223               </td>
 224 </tr>
 225 <tr>
 226 <td>
 227               <p>
 228                 <code class="computeroutput"><span class="identifier">J</span> <span class="identifier">elements_rend</span><span class="special">(</span><span class="identifier">T</span><span class="special">&amp;)</span></code>
 229               </p>
 230               </td>
 231 <td>
 232               <p>
 233                 <span class="emphasis"><em>O(1)</em></span>
 234               </p>
 235               </td>
 236 <td>
 237               <p>
 238                 <span class="emphasis"><em>O(1)</em></span>
 239               </p>
 240               </td>
 241 </tr>
 242 </tbody>
 243 </table></div>
 244 <div class="informaltable"><table class="table">
 245 <colgroup>
 246 <col>
 247 <col>
 248 </colgroup>
 249 <thead><tr>
 250 <th>
 251               <p>
 252                 <span class="emphasis"><em><span class="bold"><strong>Element iteration</strong></span></em></span>
 253               </p>
 254               </th>
 255 <th>
 256               <p>
 257                 Description
 258               </p>
 259               </th>
 260 </tr></thead>
 261 <tbody>
 262 <tr>
 263 <td>
 264               <p>
 265
 266 </p>
 267 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">      <span class="identifier">element_iterator</span> <span class="identifier">elements_begin</span><span class="special">(</span><span class="identifier">T</span><span class="special">&amp;)</span>
 268 <span class="identifier">element_const_iterator</span> <span class="identifier">elements_begin</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;)</span></pre>
 269 <p>
 270               </p>
 271               </td>
 272 <td>
 273               <p>
 274                 Returns an element iterator to the first element of the container.
 275               </p>
 276               </td>
 277 </tr>
 278 <tr>
 279 <td>
 280               <p>
 281
 282 </p>
 283 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">      <span class="identifier">element_iterator</span> <span class="identifier">elements_end</span><span class="special">(</span><span class="identifier">T</span><span class="special">&amp;)</span>
 284 <span class="identifier">element_const_iterator</span> <span class="identifier">elements_end</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;)</span></pre>
 285 <p>
 286               </p>
 287               </td>
 288 <td>
 289               <p>
 290                 Returns an element iterator to a position <code class="computeroutput"><span class="identifier">elements_end</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span></code> after the last element of the container.
 291               </p>
 292               </td>
 293 </tr>
 294 <tr>
 295 <td>
 296               <p>
 297
 298 </p>
 299 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">      <span class="identifier">element_reverse_iterator</span> <span class="identifier">elements_rbegin</span><span class="special">(</span><span class="identifier">T</span><span class="special">&amp;)</span>
 300 <span class="identifier">element_const_reverse_iterator</span> <span class="identifier">elements_rbegin</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;)</span></pre>
 301 <p>
 302               </p>
 303               </td>
 304 <td>
 305               <p>
 306                 Returns a reverse element iterator to the last element of the container.
 307               </p>
 308               </td>
 309 </tr>
 310 <tr>
 311 <td>
 312               <p>
 313
 314 </p>
 315 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">      <span class="identifier">element_reverse_iterator</span> <span class="identifier">elements_rend</span><span class="special">(</span><span class="identifier">T</span><span class="special">&amp;)</span>
 316 <span class="identifier">element_const_reverse_iterator</span> <span class="identifier">elements_rend</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;)</span></pre>
 317 <p>
 318               </p>
 319               </td>
 320 <td>
 321               <p>
 322                 Returns a reverse element iterator to a position <code class="computeroutput"><span class="identifier">elements_rend</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span></code> before the first element of the
 323                 container.
 324               </p>
 325               </td>
 326 </tr>
 327 </tbody>
 328 </table></div>
 329 <p>
 330         <span class="emphasis"><em><span class="bold"><strong>Example</strong></span></em></span>
 331       </p>
 332 <p>
 333
 334 </p>
 335 <pre class="programlisting"><span class="identifier">interval_set</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">inter_set</span><span class="special">;</span>
 336 <span class="identifier">inter_set</span><span class="special">.</span><span class="identifier">add</span><span class="special">(</span><span class="identifier">interval</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;::</span><span class="identifier">right_open</span><span class="special">(</span><span class="number">0</span><span class="special">,</span><span class="number">3</span><span class="special">))</span>
 337          <span class="special">.</span><span class="identifier">add</span><span class="special">(</span><span class="identifier">interval</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;::</span><span class="identifier">right_open</span><span class="special">(</span><span class="number">7</span><span class="special">,</span><span class="number">9</span><span class="special">));</span>
 338
 339 <span class="keyword">for</span><span class="special">(</span><span class="identifier">interval_set</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;::</span><span class="identifier">element_const_iterator</span> <span class="identifier">creeper</span> <span class="special">=</span> <span class="identifier">elements_begin</span><span class="special">(</span><span class="identifier">inter_set</span><span class="special">);</span>
 340     <span class="identifier">creeper</span> <span class="special">!=</span> <span class="identifier">elements_end</span><span class="special">(</span><span class="identifier">inter_set</span><span class="special">);</span> <span class="special">++</span><span class="identifier">creeper</span><span class="special">)</span>
 341     <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="special">*</span><span class="identifier">creeper</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span><span class="special">;</span>
 342 <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
 343 <span class="comment">//Program output: 0 1 2 7 8
 344 </span>
 345 <span class="keyword">for</span><span class="special">(</span><span class="identifier">interval_set</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;::</span><span class="identifier">element_reverse_iterator</span> <span class="identifier">repeerc</span> <span class="special">=</span> <span class="identifier">elements_rbegin</span><span class="special">(</span><span class="identifier">inter_set</span><span class="special">);</span>
 346     <span class="identifier">repeerc</span> <span class="special">!=</span> <span class="identifier">elements_rend</span><span class="special">(</span><span class="identifier">inter_set</span><span class="special">);</span> <span class="special">++</span><span class="identifier">repeerc</span><span class="special">)</span>
 347     <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="special">*</span><span class="identifier">repeerc</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span><span class="special">;</span>
 348 <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
 349 <span class="comment">//Program output: 8 7 2 1 0
 350 </span></pre>
 351 <p>
 352       </p>
 353 <p>
 354         <span class="emphasis"><em><span class="bold"><strong>See also . . .</strong></span></em></span>
 355       </p>
 356 <div class="informaltable"><table class="table">
 357 <colgroup><col></colgroup>
 358 <thead><tr></tr></thead>
 359 <tbody><tr><td>
 360               <p>
 361                 <a class="link" href="iterator_related.html" title="Iterator related"><span class="emphasis"><em><span class="bold"><strong>Segment iteration</strong></span></em></span></a>
 362               </p>
 363               </td></tr></tbody>
 364 </table></div>
 365 <p>
 366         <span class="emphasis"><em><span class="bold"><strong>Back to section . . .</strong></span></em></span>
 367       </p>
 368 <div class="informaltable"><table class="table">
 369 <colgroup><col></colgroup>
 370 <thead><tr></tr></thead>
 371 <tbody>
 372 <tr><td>
 373               <p>
 374                 <a class="link" href="../interface/function_synopsis.html#function_synopsis_table"><span class="emphasis"><em><span class="bold"><strong>Function
 375                 Synopsis</strong></span></em></span></a>
 376               </p>
 377               </td></tr>
 378 <tr><td>
 379               <p>
 380                 <a class="link" href="../interface.html" title="Interface"><span class="emphasis"><em><span class="bold"><strong>Interface</strong></span></em></span></a>
 381               </p>
 382               </td></tr>
 383 </tbody>
 384 </table></div>
 385 </div>
 386 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 387 <td align="left"></td>
 388 <td align="right"><div class="copyright-footer">Copyright &#169; 2007 -2010 Joachim Faulhaber<br>Copyright &#169; 1999 -2006 Cortex Software GmbH<p>
 389         Distributed under the Boost Software License, Version 1.0. (See accompanying
 390         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 391       </p>
 392 </div></td>
 393 </tr></table>
 394 <hr>
 395 <div class="spirit-nav">
 396 <a accesskey="p" href="iterator_related.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_reference.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="streaming__conversion.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 397 </div>
 398 </body>
 399 </html>