ceph/src/boost/libs/bimap/doc/html/boost_bimap/the_tutorial/useful_functions.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Useful functions</title>
   5 <link rel="stylesheet" href="../../boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
   7 <link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Bimap">
   8 <link rel="up" href="../the_tutorial.html" title="The tutorial">
   9 <link rel="prev" href="differences_with_standard_maps.html" title="Differences with standard maps">
  10 <link rel="next" href="bimaps_with_user_defined_names.html" title="Bimaps with user defined names">
  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="../../../../../../libs/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="differences_with_standard_maps.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.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="bimaps_with_user_defined_names.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section boost_bimap_the_tutorial_useful_functions">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="boost_bimap.the_tutorial.useful_functions"></a><a class="link" href="useful_functions.html" title="Useful functions">Useful functions</a>
  28 </h3></div></div></div>
  29 <div class="toc"><dl>
  30 <dt><span class="section"><a href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.projection_of_iterators">Projection
  31         of iterators</a></span></dt>
  32 <dt><span class="section"><a href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.replace_and_modify">replace
  33         and modify</a></span></dt>
  34 <dt><span class="section"><a href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges">Retrieval
  35         of ranges</a></span></dt>
  36 </dl></div>
  37 <div class="section boost_bimap_the_tutorial_useful_functions_projection_of_iterators">
  38 <div class="titlepage"><div><div><h4 class="title">
  39 <a name="boost_bimap.the_tutorial.useful_functions.projection_of_iterators"></a><a class="link" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.projection_of_iterators" title="Projection of iterators">Projection
  40         of iterators</a>
  41 </h4></div></div></div>
  42 <p>
  43           Iterators can be projected to any of the three views of the bimap. A bimap
  44           provides three member functions to cope with projection: <code class="computeroutput"><span class="identifier">project_left</span></code>, <code class="computeroutput"><span class="identifier">project_right</span></code>
  45           and <code class="computeroutput"><span class="identifier">project_up</span></code>, with projects
  46           iterators to the <span class="emphasis"><em>left map view</em></span>, the <span class="emphasis"><em>right
  47           map view</em></span> and the <span class="emphasis"><em>collection of relations view</em></span>.
  48           These functions take any iterator from the bimap and retrieve an iterator
  49           over the projected view pointing to the same element.
  50         </p>
  51 <p>
  52           Here is an example that uses projection:
  53         </p>
  54 <p>
  55           <a href="../../../../example/projection.cpp" target="_top">Go to source code</a>
  56         </p>
  57 <p>
  58 </p>
  59 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span><span class="identifier">multiset_of</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">greater</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
  60
  61 <span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
  62 <span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="string">"John"</span> <span class="special">,</span><span class="number">34</span><span class="special">)</span> <span class="special">);</span>
  63 <span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="string">"Peter"</span><span class="special">,</span><span class="number">24</span><span class="special">)</span> <span class="special">);</span>
  64 <span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="string">"Mary"</span> <span class="special">,</span><span class="number">12</span><span class="special">)</span> <span class="special">);</span>
  65
  66 <span class="comment">// Find the name of the next younger person after Peter</span>
  67
  68 <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_const_iterator</span> <span class="identifier">name_iter</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="string">"Peter"</span><span class="special">);</span>
  69
  70 <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">right_const_iterator</span> <span class="identifier">years_iter</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">project_right</span><span class="special">(</span><span class="identifier">name_iter</span><span class="special">);</span>
  71
  72 <span class="special">++</span><span class="identifier">years_iter</span><span class="special">;</span>
  73
  74 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The next younger person after Peter is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">years_iter</span><span class="special">-&gt;</span><span class="identifier">second</span><span class="special">;</span>
  75 </pre>
  76 <p>
  77         </p>
  78 </div>
  79 <div class="section boost_bimap_the_tutorial_useful_functions_replace_and_modify">
  80 <div class="titlepage"><div><div><h4 class="title">
  81 <a name="boost_bimap.the_tutorial.useful_functions.replace_and_modify"></a><a class="link" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.replace_and_modify" title="replace and modify">replace
  82         and modify</a>
  83 </h4></div></div></div>
  84 <p>
  85           These functions are members of the views of a bimap that are not founded
  86           in their standard counterparts.
  87         </p>
  88 <p>
  89           The <code class="computeroutput"><span class="identifier">replace</span></code> family member
  90           functions performs in-place replacement of a given element as the following
  91           example shows:
  92         </p>
  93 <p>
  94           <a href="../../../../example/tutorial_modify_and_replace.cpp" target="_top">Go to source
  95           code</a>
  96         </p>
  97 <p>
  98 </p>
  99 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
 100 <span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
 101
 102 <span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="string">"one"</span><span class="special">)</span> <span class="special">);</span>
 103
 104 <span class="comment">// Replace (1,"one") with (1,"1") using the right map view</span>
 105 <span class="special">{</span>
 106     <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">right_iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="string">"one"</span><span class="special">);</span>
 107
 108     <span class="keyword">bool</span> <span class="identifier">successful_replace</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">replace_key</span><span class="special">(</span> <span class="identifier">it</span><span class="special">,</span> <span class="string">"1"</span> <span class="special">);</span>
 109
 110     <span class="identifier">assert</span><span class="special">(</span> <span class="identifier">successful_replace</span> <span class="special">);</span>
 111 <span class="special">}</span>
 112
 113 <span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="number">2</span><span class="special">,</span><span class="string">"two"</span><span class="special">)</span> <span class="special">);</span>
 114
 115 <span class="comment">// Fail to replace (1,"1") with (1,"two") using the left map view</span>
 116 <span class="special">{</span>
 117     <span class="identifier">assert</span><span class="special">(</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">2</span> <span class="special">);</span>
 118
 119     <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="number">1</span><span class="special">);</span>
 120
 121     <span class="keyword">bool</span> <span class="identifier">successful_replace</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">replace_data</span><span class="special">(</span> <span class="identifier">it</span><span class="special">,</span> <span class="string">"two"</span> <span class="special">);</span>
 122
 123     <a class="co" name="boost_bimap.the_tutorial.useful_functions.replace_and_modify.c0" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.replace_and_modify.c1"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">assert</span><span class="special">(</span> <span class="special">!</span> <span class="identifier">successful_replace</span> <span class="special">);</span>
 124     <span class="identifier">assert</span><span class="special">(</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">2</span> <span class="special">);</span>
 125 <span class="special">}</span>
 126 </pre>
 127 <p>
 128         </p>
 129 <div class="calloutlist"><table border="0" summary="Callout list"><tr>
 130 <td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.useful_functions.replace_and_modify.c1"></a><a href="#boost_bimap.the_tutorial.useful_functions.replace_and_modify.c0"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
 131 <td valign="top" align="left"><p>
 132               <code class="computeroutput"><span class="identifier">it</span></code> is still valid here,
 133               and the bimap was left unchanged
 134             </p></td>
 135 </tr></table></div>
 136 <p>
 137           <code class="computeroutput"><span class="identifier">replace</span></code> functions performs
 138           this substitution in such a manner that:
 139         </p>
 140 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 141 <li class="listitem">
 142               The complexity is constant time if the changed element retains its
 143               original order with respect to all views; it is logarithmic otherwise.
 144             </li>
 145 <li class="listitem">
 146               Iterator and reference validity are preserved.
 147             </li>
 148 <li class="listitem">
 149               The operation is strongly exception-safe, i.e. the <code class="computeroutput"><span class="identifier">bimap</span></code>
 150               remains unchanged if some exception (originated by the system or the
 151               user's data types) is thrown.
 152             </li>
 153 </ul></div>
 154 <p>
 155           <code class="computeroutput"><span class="identifier">replace</span></code> functions are powerful
 156           operations not provided by standard STL containers, and one that is specially
 157           handy when strong exception-safety is required.
 158         </p>
 159 <p>
 160           The observant reader might have noticed that the convenience of replace
 161           comes at a cost: namely the whole element has to be copied <span class="emphasis"><em>twice</em></span>
 162           to do the updating (when retrieving it and inside <code class="computeroutput"><span class="identifier">replace</span></code>).
 163           If elements are expensive to copy, this may be quite a computational cost
 164           for the modification of just a tiny part of the object. To cope with this
 165           situation, Boost.Bimap provides an alternative updating mechanism: <code class="computeroutput"><span class="identifier">modify</span></code> functions.
 166         </p>
 167 <p>
 168           <code class="computeroutput"><span class="identifier">modify</span></code> functions accepts
 169           a functor (or pointer to function) taking a reference to the data to be
 170           changed, thus eliminating the need for spurious copies. Like <code class="computeroutput"><span class="identifier">replace</span></code> functions, <code class="computeroutput"><span class="identifier">modify</span></code>
 171           functions does preserve the internal orderings of all the indices of the
 172           <code class="computeroutput"><span class="identifier">bimap</span></code>. However, the semantics
 173           of modify functions are not entirely equivalent to replace functions. Consider
 174           what happens if a collision occurs as a result of modifying the element,
 175           i.e. the modified element clashes with another with respect to some unique
 176           view. In the case of <code class="computeroutput"><span class="identifier">replace</span></code>
 177           functions, the original value is kept and the method returns without altering
 178           the container, but <code class="computeroutput"><span class="identifier">modify</span></code>
 179           functions cannot afford such an approach, since the modifying functor leaves
 180           no trace of the previous value of the element. Integrity constraints thus
 181           lead to the following policy: when a collision happens in the process of
 182           calling a modify functions, the element is erased and the method returns
 183           false. This difference in behavior between <code class="computeroutput"><span class="identifier">replace</span></code>
 184           and <code class="computeroutput"><span class="identifier">modify</span></code> functions has
 185           to be considered by the programmer on a case-by-case basis.
 186         </p>
 187 <p>
 188           Boost.Bimap defines new placeholders named <code class="computeroutput"><span class="identifier">_key</span></code>
 189           and <code class="computeroutput"><span class="identifier">_data</span></code> to allow a sounder
 190           solution. You have to include <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bimap</span><span class="special">/</span><span class="identifier">support</span><span class="special">/</span><span class="identifier">lambda</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
 191           to use them.
 192         </p>
 193 <p>
 194           <a href="../../../../example/tutorial_modify_and_replace.cpp" target="_top">Go to source
 195           code</a>
 196         </p>
 197 <p>
 198 </p>
 199 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
 200 <span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
 201 <span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="string">"one"</span><span class="special">)</span> <span class="special">);</span>
 202
 203 <span class="comment">// Modify (1,"one") to (1,"1") using the right map view</span>
 204 <span class="special">{</span>
 205     <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">right_iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="string">"one"</span><span class="special">);</span>
 206
 207     <span class="keyword">bool</span> <span class="identifier">successful_modify</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">modify_key</span><span class="special">(</span> <span class="identifier">it</span> <span class="special">,</span> <span class="identifier">_key</span> <span class="special">=</span> <span class="string">"1"</span> <span class="special">);</span>
 208
 209     <span class="identifier">assert</span><span class="special">(</span> <span class="identifier">successful_modify</span> <span class="special">);</span>
 210 <span class="special">}</span>
 211
 212 <span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="number">2</span><span class="special">,</span><span class="string">"two"</span><span class="special">)</span> <span class="special">);</span>
 213
 214 <span class="comment">// Fail to modify (1,"1") to (1,"two") using the left map view</span>
 215 <span class="special">{</span>
 216     <span class="identifier">assert</span><span class="special">(</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">2</span> <span class="special">);</span>
 217
 218     <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="number">1</span><span class="special">);</span>
 219
 220     <span class="keyword">bool</span> <span class="identifier">successful_modify</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">modify_data</span><span class="special">(</span> <span class="identifier">it</span><span class="special">,</span> <span class="identifier">_data</span> <span class="special">=</span> <span class="string">"two"</span> <span class="special">);</span>
 221
 222     <a class="co" name="boost_bimap.the_tutorial.useful_functions.replace_and_modify.c2" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.replace_and_modify.c3"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">assert</span><span class="special">(</span> <span class="special">!</span> <span class="identifier">successful_modify</span> <span class="special">);</span>
 223     <span class="identifier">assert</span><span class="special">(</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">1</span> <span class="special">);</span>
 224 <span class="special">}</span>
 225 </pre>
 226 <p>
 227         </p>
 228 <div class="calloutlist"><table border="0" summary="Callout list"><tr>
 229 <td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.useful_functions.replace_and_modify.c3"></a><a href="#boost_bimap.the_tutorial.useful_functions.replace_and_modify.c2"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
 230 <td valign="top" align="left"><p>
 231               <code class="computeroutput"><span class="identifier">it</span></code> is not longer valid
 232               and <code class="computeroutput"><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="string">"1"</span><span class="special">)</span></code> is removed from the bimap
 233             </p></td>
 234 </tr></table></div>
 235 </div>
 236 <div class="section boost_bimap_the_tutorial_useful_functions_retrieval_of_ranges">
 237 <div class="titlepage"><div><div><h4 class="title">
 238 <a name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges"></a><a class="link" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges" title="Retrieval of ranges">Retrieval
 239         of ranges</a>
 240 </h4></div></div></div>
 241 <p>
 242           Standard <code class="computeroutput"><span class="identifier">lower_bound</span></code> and
 243           <code class="computeroutput"><span class="identifier">upper_bound</span></code> functions can
 244           be used to lookup for all the elements in a given range.
 245         </p>
 246 <p>
 247           Suppose we want to retrieve the elements from a <code class="computeroutput"><span class="identifier">bimap</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span></code> where the left value is in the range
 248           <code class="computeroutput"><span class="special">[</span><span class="number">20</span><span class="special">,</span><span class="number">50</span><span class="special">]</span></code>
 249         </p>
 250 <p>
 251 </p>
 252 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
 253 <span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
 254
 255 <span class="comment">// ...</span>
 256
 257 <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span> <span class="identifier">iter_first</span>  <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">lower_bound</span><span class="special">(</span><span class="number">20</span><span class="special">);</span>
 258 <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span> <span class="identifier">iter_second</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">upper_bound</span><span class="special">(</span><span class="number">50</span><span class="special">);</span>
 259
 260 <span class="comment">// range [iter_first,iter_second) contains the elements in [20,50]</span>
 261 </pre>
 262 <p>
 263         </p>
 264 <p>
 265           Subtle changes to the code are required when strict inequalities are considered.
 266           To retrieve the elements greater than 20 and less than 50, the code has
 267           to be rewritten as
 268         </p>
 269 <p>
 270 </p>
 271 <pre class="programlisting"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span> <span class="identifier">iter_first</span>  <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">upper_bound</span><span class="special">(</span><span class="number">20</span><span class="special">);</span>
 272 <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span> <span class="identifier">iter_second</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">lower_bound</span><span class="special">(</span><span class="number">50</span><span class="special">);</span>
 273
 274 <span class="comment">// range [iter_first,iter_second) contains the elements in (20,50)</span>
 275 </pre>
 276 <p>
 277         </p>
 278 <p>
 279           To add to this complexity, the careful programmer has to take into account
 280           that the lower and upper bounds of the interval searched be compatible:
 281           for instance, if the lower bound is 50 and the upper bound is 20, the iterators
 282           <code class="computeroutput"><span class="identifier">iter_first</span></code> and <code class="computeroutput"><span class="identifier">iter_second</span></code> produced by the code above
 283           will be in reverse order, with possibly catastrophic results if a traversal
 284           from <code class="computeroutput"><span class="identifier">iter_first</span></code> to <code class="computeroutput"><span class="identifier">iter_second</span></code> is tried. All these details
 285           make range searching a tedious and error prone task.
 286         </p>
 287 <p>
 288           The range member function, often in combination with lambda expressions,
 289           can greatly help alleviate this situation:
 290         </p>
 291 <p>
 292 </p>
 293 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
 294 <span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
 295
 296 <span class="comment">// ...</span>
 297
 298 <a class="co" name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c0" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c1"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_range_type</span> <span class="identifier">r</span><span class="special">;</span>
 299
 300 <a class="co" name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c2" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c3"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a><span class="identifier">r</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">range</span><span class="special">(</span> <span class="number">20</span> <span class="special">&lt;=</span> <span class="identifier">_key</span><span class="special">,</span> <span class="identifier">_key</span> <span class="special">&lt;=</span> <span class="number">50</span> <span class="special">);</span> <span class="comment">// [20,50]</span>
 301
 302 <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">range</span><span class="special">(</span> <span class="number">20</span> <span class="special">&lt;</span>  <span class="identifier">_key</span><span class="special">,</span> <span class="identifier">_key</span> <span class="special">&lt;</span>  <span class="number">50</span> <span class="special">);</span> <span class="comment">// (20,50)</span>
 303
 304 <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">range</span><span class="special">(</span> <span class="number">20</span> <span class="special">&lt;=</span> <span class="identifier">_key</span><span class="special">,</span> <span class="identifier">_key</span> <span class="special">&lt;</span>  <span class="number">50</span> <span class="special">);</span> <span class="comment">// [20,50)</span>
 305 </pre>
 306 <p>
 307         </p>
 308 <div class="calloutlist"><table border="0" summary="Callout list">
 309 <tr>
 310 <td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c1"></a><a href="#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c0"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
 311 <td valign="top" align="left"><p>
 312               <code class="computeroutput"><span class="identifier">range_type</span></code> is a handy
 313               typedef equal to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">iterator</span><span class="special">,</span><span class="identifier">iterator</span><span class="special">&gt;</span></code>. <code class="computeroutput"><span class="identifier">const_range_type</span></code>
 314               is provided too, and it is equal to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">const_iterator</span><span class="special">,</span><span class="identifier">const_iterator</span><span class="special">&gt;</span></code>
 315             </p></td>
 316 </tr>
 317 <tr>
 318 <td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c3"></a><a href="#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c2"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
 319 <td valign="top" align="left"><p>
 320               _key is a Boost.Lambda placeholder. To use it you have to include
 321               <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bimap</span><span class="special">/</span><span class="identifier">support</span><span class="special">/</span><span class="identifier">lambda</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
 322             </p></td>
 323 </tr>
 324 </table></div>
 325 <p>
 326           <code class="computeroutput"><span class="identifier">range</span></code> simply accepts predicates
 327           specifying the lower and upper bounds of the interval searched. Please
 328           consult the reference for a detailed explanation of the permissible predicates
 329           passed to range.
 330         </p>
 331 <p>
 332           One or both bounds can be omitted with the special unbounded marker:
 333         </p>
 334 <p>
 335 </p>
 336 <pre class="programlisting"><span class="identifier">r</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">range</span><span class="special">(</span> <span class="number">20</span> <span class="special">&lt;=</span> <span class="identifier">_key</span><span class="special">,</span> <span class="identifier">unbounded</span> <span class="special">);</span> <span class="comment">// [20,inf)</span>
 337
 338 <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">range</span><span class="special">(</span> <span class="identifier">unbounded</span> <span class="special">,</span> <span class="identifier">_key</span> <span class="special">&lt;</span> <span class="number">50</span> <span class="special">);</span> <span class="comment">// (-inf,50)</span>
 339
 340 <a class="co" name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c4" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c5"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">r</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">range</span><span class="special">(</span> <span class="identifier">unbounded</span> <span class="special">,</span> <span class="identifier">unbounded</span> <span class="special">);</span> <span class="comment">// (-inf,inf)</span>
 341 </pre>
 342 <p>
 343         </p>
 344 <div class="calloutlist"><table border="0" summary="Callout list"><tr>
 345 <td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c5"></a><a href="#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c4"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
 346 <td valign="top" align="left"><p>
 347               This is equivalent to std::make_pair(s.begin(),s.end())
 348             </p></td>
 349 </tr></table></div>
 350 <p>
 351           <a href="../../../../example/tutorial_range.cpp" target="_top">Go to source code</a>
 352         </p>
 353 </div>
 354 </div>
 355 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 356 <td align="left"></td>
 357 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2012 Matias Capeletto<p>
 358         Distributed under the Boost Software License, Version 1.0. (See accompanying
 359         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>)
 360       </p>
 361 </div></td>
 362 </tr></table>
 363 <hr>
 364 <div class="spirit-nav">
 365 <a accesskey="p" href="differences_with_standard_maps.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.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="bimaps_with_user_defined_names.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 366 </div>
 367 </body>
 368 </html>