libs/bimap/doc/html/boost_bimap/one_minute_tutorial.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>One minute tutorial</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="../index.html" title="Chapter&#160;1.&#160;Boost.Bimap">
   9 <link rel="prev" href="introduction.html" title="Introduction">
  10 <link rel="next" href="the_tutorial.html" title="The tutorial">
  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="introduction.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="the_tutorial.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section boost_bimap_one_minute_tutorial">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="boost_bimap.one_minute_tutorial"></a><a class="link" href="one_minute_tutorial.html" title="One minute tutorial">One minute tutorial</a>
  28 </h2></div></div></div>
  29 <h4>
  30 <a name="boost_bimap.one_minute_tutorial.h0"></a>
  31       <span class="phrase"><a name="boost_bimap.one_minute_tutorial.what_is_a_bimap_"></a></span><a class="link" href="one_minute_tutorial.html#boost_bimap.one_minute_tutorial.what_is_a_bimap_">What
  32       is a bimap?</a>
  33     </h4>
  34 <p>
  35       A Bimap is a data structure that represents bidirectional relations between
  36       elements of two collections. The container is designed to work as two opposed
  37       STL maps. A bimap between a collection <code class="computeroutput"><span class="identifier">X</span></code>
  38       and a collection <code class="computeroutput"><span class="identifier">Y</span></code> can be viewed
  39       as a map from <code class="computeroutput"><span class="identifier">X</span></code> to <code class="computeroutput"><span class="identifier">Y</span></code> (this view will be called the <span class="emphasis"><em>left
  40       map view</em></span>) or as a map from <code class="computeroutput"><span class="identifier">Y</span></code>
  41       to <code class="computeroutput"><span class="identifier">X</span></code> (known as the <span class="emphasis"><em>right
  42       map view</em></span>). Additionally, the bimap can also be viewed as a set of
  43       relations between <code class="computeroutput"><span class="identifier">X</span></code> and <code class="computeroutput"><span class="identifier">Y</span></code> (named the <span class="emphasis"><em>collection of relations
  44       view</em></span>).
  45     </p>
  46 <p>
  47       The following code creates an empty bimap container:
  48     </p>
  49 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span><span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
  50 <span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
  51 </pre>
  52 <p>
  53       Given this code, the following is the complete description of the resulting
  54       bimap. <a href="#ftn.boost_bimap.one_minute_tutorial.f0" class="footnote"><sup class="footnote"><a name="boost_bimap.one_minute_tutorial.f0"></a>[1]</sup></a>
  55     </p>
  56 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  57 <li class="listitem">
  58           <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span></code> is signature-compatible with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span><span class="special">&gt;</span></code>
  59         </li>
  60 <li class="listitem">
  61           <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span></code> is signature-compatible with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special">&lt;</span><span class="identifier">Y</span><span class="special">,</span><span class="identifier">X</span><span class="special">&gt;</span></code>
  62         </li>
  63 <li class="listitem">
  64           <code class="computeroutput"><span class="identifier">bm</span></code> is signature-compatible
  65           with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">set</span><span class="special">&lt;</span> <span class="identifier">relation</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span><span class="special">&gt;</span> <span class="special">&gt;</span></code>
  66         </li>
  67 </ul></div>
  68 <p>
  69       <span class="inlinemediaobject"><img src="../images/bimap/simple.bimap.png" alt="simple.bimap"></span>
  70     </p>
  71 <p>
  72       You can see how a bimap container offers three views over the same collection
  73       of bidirectional relations.
  74     </p>
  75 <p>
  76       If we have any generic function that work with maps
  77     </p>
  78 <pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">MapType</span> <span class="special">&gt;</span>
  79 <span class="keyword">void</span> <span class="identifier">print_map</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">MapType</span> <span class="special">&amp;</span> <span class="identifier">m</span><span class="special">)</span>
  80 <span class="special">{</span>
  81     <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">MapType</span><span class="special">::</span><span class="identifier">const_iterator</span> <span class="identifier">const_iterator</span><span class="special">;</span>
  82     <span class="keyword">for</span><span class="special">(</span> <span class="identifier">const_iterator</span> <span class="identifier">iter</span> <span class="special">=</span> <span class="identifier">m</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">iend</span> <span class="special">=</span> <span class="identifier">m</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span> <span class="identifier">iter</span> <span class="special">!=</span> <span class="identifier">iend</span><span class="special">;</span> <span class="special">++</span><span class="identifier">iter</span> <span class="special">)</span>
  83     <span class="special">{</span>
  84         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">first</span> <span class="special">&lt;&lt;</span> <span class="string">"--&gt;"</span> <span class="special">&lt;&lt;</span> <span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">second</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
  85     <span class="special">}</span>
  86 <span class="special">}</span>
  87 </pre>
  88 <p>
  89       We can use the <span class="emphasis"><em>left map view</em></span> and the <span class="emphasis"><em>right map
  90       view</em></span> with it
  91     </p>
  92 <pre class="programlisting"><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</span><span class="special">;</span>
  93 <span class="special">...</span>
  94 <span class="identifier">print_map</span><span class="special">(</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span>  <span class="special">);</span>
  95 <span class="identifier">print_map</span><span class="special">(</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span> <span class="special">);</span>
  96 </pre>
  97 <p>
  98       And the output will be
  99     </p>
 100 <pre class="programlisting"><code class="literal">1 --&gt; one</code>
 101 <code class="literal">2 --&gt; two</code>
 102 ...
 103 <code class="literal">one --&gt; 1</code>
 104 <code class="literal">two --&gt; 2</code>
 105 ...
 106 </pre>
 107 <h4>
 108 <a name="boost_bimap.one_minute_tutorial.h1"></a>
 109       <span class="phrase"><a name="boost_bimap.one_minute_tutorial.layout_of_the_relation_and_the_pairs_of_a_bimap"></a></span><a class="link" href="one_minute_tutorial.html#boost_bimap.one_minute_tutorial.layout_of_the_relation_and_the_pairs_of_a_bimap">Layout
 110       of the relation and the pairs of a bimap</a>
 111     </h4>
 112 <p>
 113       The <code class="computeroutput"><span class="identifier">relation</span></code> class represents
 114       two related elements. The two values are named left and right to express the
 115       symmetry of this type. The bimap pair classes are signature-compatible with
 116       <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pairs</span></code>.
 117     </p>
 118 <p>
 119       <span class="inlinemediaobject"><img src="../images/bimap/relation.and.pair.png" alt="relation.and.pair"></span>
 120     </p>
 121 <h4>
 122 <a name="boost_bimap.one_minute_tutorial.h2"></a>
 123       <span class="phrase"><a name="boost_bimap.one_minute_tutorial.step_by_step"></a></span><a class="link" href="one_minute_tutorial.html#boost_bimap.one_minute_tutorial.step_by_step">Step
 124       by step</a>
 125     </h4>
 126 <p>
 127       A convinience header is avaiable in the boost directory:
 128     </p>
 129 <pre class="programlisting"><span class="preprocessor">#include</span> <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">hpp</span><span class="special">&gt;</span>
 130 </pre>
 131 <p>
 132       Lets define a bidirectional map between integers and strings:
 133     </p>
 134 <p>
 135 </p>
 136 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</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>
 137 <span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
 138 </pre>
 139 <p>
 140     </p>
 141 <h4>
 142 <a name="boost_bimap.one_minute_tutorial.h3"></a>
 143       <span class="phrase"><a name="boost_bimap.one_minute_tutorial.the_collection_of_relations_view"></a></span><a class="link" href="one_minute_tutorial.html#boost_bimap.one_minute_tutorial.the_collection_of_relations_view">The
 144       collection of relations view</a>
 145     </h4>
 146 <p>
 147       Remember that <code class="computeroutput"><span class="identifier">bm</span></code> alone can
 148       be used as a set of relations. We can insert elements or iterate over them
 149       using this view.
 150     </p>
 151 <p>
 152 </p>
 153 <pre class="programlisting"><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>
 154 <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>
 155
 156 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"There are "</span> <span class="special">&lt;&lt;</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"relations"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 157
 158 <span class="keyword">for</span><span class="special">(</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">const_iterator</span> <span class="identifier">iter</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">iend</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span>
 159     <span class="identifier">iter</span> <span class="special">!=</span> <span class="identifier">iend</span><span class="special">;</span> <span class="special">++</span><span class="identifier">iter</span> <span class="special">)</span>
 160 <span class="special">{</span>
 161     <span class="comment">// iter-&gt;left  : data : int</span>
 162     <span class="comment">// iter-&gt;right : data : std::string</span>
 163
 164     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">" &lt;--&gt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 165 <span class="special">}</span>
 166 </pre>
 167 <p>
 168     </p>
 169 <h4>
 170 <a name="boost_bimap.one_minute_tutorial.h4"></a>
 171       <span class="phrase"><a name="boost_bimap.one_minute_tutorial.the_left_map_view"></a></span><a class="link" href="one_minute_tutorial.html#boost_bimap.one_minute_tutorial.the_left_map_view">The
 172       left map view</a>
 173     </h4>
 174 <p>
 175       <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span></code> works like a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special">&lt;</span>
 176       <span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span>
 177       <span class="special">&gt;</span></code>. We use it in the same way we will
 178       use a standard map.
 179     </p>
 180 <p>
 181 </p>
 182 <pre class="programlisting"><a class="co" name="boost_bimap.one_minute_tutorial.c0" href="one_minute_tutorial.html#boost_bimap.one_minute_tutorial.c1"><img src="../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="keyword">typedef</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_map</span><span class="special">::</span><span class="identifier">const_iterator</span> <span class="identifier">left_const_iterator</span><span class="special">;</span>
 183
 184 <span class="keyword">for</span><span class="special">(</span> <span class="identifier">left_const_iterator</span> <span class="identifier">left_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">begin</span><span class="special">(),</span> <span class="identifier">iend</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">end</span><span class="special">();</span>
 185      <span class="identifier">left_iter</span> <span class="special">!=</span> <span class="identifier">iend</span><span class="special">;</span> <span class="special">++</span><span class="identifier">left_iter</span> <span class="special">)</span>
 186 <span class="special">{</span>
 187     <span class="comment">// left_iter-&gt;first  : key  : int</span>
 188     <span class="comment">// left_iter-&gt;second : data : std::string</span>
 189
 190     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">left_iter</span><span class="special">-&gt;</span><span class="identifier">first</span> <span class="special">&lt;&lt;</span> <span class="string">" --&gt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">left_iter</span><span class="special">-&gt;</span><span class="identifier">second</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 191 <span class="special">}</span>
 192
 193 <a class="co" name="boost_bimap.one_minute_tutorial.c2" href="one_minute_tutorial.html#boost_bimap.one_minute_tutorial.c3"><img src="../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_const_iterator</span> <span class="identifier">left_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="number">2</span><span class="special">);</span>
 194 <span class="identifier">assert</span><span class="special">(</span> <span class="identifier">left_iter</span><span class="special">-&gt;</span><span class="identifier">second</span> <span class="special">==</span>  <span class="string">"two"</span> <span class="special">);</span>
 195
 196 <a class="co" name="boost_bimap.one_minute_tutorial.c4" href="one_minute_tutorial.html#boost_bimap.one_minute_tutorial.c5"><img src="../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a><span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</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">left_value_type</span><span class="special">(</span> <span class="number">3</span><span class="special">,</span> <span class="string">"three"</span> <span class="special">)</span> <span class="special">);</span>
 197 </pre>
 198 <p>
 199     </p>
 200 <div class="calloutlist"><table border="0" summary="Callout list">
 201 <tr>
 202 <td width="5%" valign="top" align="left"><p><a name="boost_bimap.one_minute_tutorial.c1"></a><a href="#boost_bimap.one_minute_tutorial.c0"><img src="../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
 203 <td valign="top" align="left"><p>
 204           The type of <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span></code> is <code class="computeroutput"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_map</span></code>
 205           and the type of <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span></code> is <code class="computeroutput"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">right_map</span></code>
 206         </p></td>
 207 </tr>
 208 <tr>
 209 <td width="5%" valign="top" align="left"><p><a name="boost_bimap.one_minute_tutorial.c3"></a><a href="#boost_bimap.one_minute_tutorial.c2"><img src="../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
 210 <td valign="top" align="left"><p>
 211           <code class="computeroutput"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_</span></code>-type- can be used as a shortcut
 212           for the more verbose <code class="computeroutput"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_map</span><span class="special">::</span></code>-type-
 213         </p></td>
 214 </tr>
 215 <tr>
 216 <td width="5%" valign="top" align="left"><p><a name="boost_bimap.one_minute_tutorial.c5"></a><a href="#boost_bimap.one_minute_tutorial.c4"><img src="../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a> </p></td>
 217 <td valign="top" align="left"><p>
 218           This line produces the same effect of <code class="computeroutput"><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">3</span><span class="special">,</span><span class="string">"three"</span><span class="special">)</span>
 219           <span class="special">);</span></code>
 220         </p></td>
 221 </tr>
 222 </table></div>
 223 <h4>
 224 <a name="boost_bimap.one_minute_tutorial.h5"></a>
 225       <span class="phrase"><a name="boost_bimap.one_minute_tutorial.the_right_map_view"></a></span><a class="link" href="one_minute_tutorial.html#boost_bimap.one_minute_tutorial.the_right_map_view">The
 226       right map view</a>
 227     </h4>
 228 <p>
 229       <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span></code> works like a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special">&lt;</span>
 230       <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="keyword">int</span> <span class="special">&gt;</span></code>. It
 231       is important to note that the key is the first type and the data is the second
 232       one, exactly as with standard maps.
 233     </p>
 234 <p>
 235 </p>
 236 <pre class="programlisting"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">right_const_iterator</span> <span class="identifier">right_iter</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">"two"</span><span class="special">);</span>
 237
 238 <span class="comment">// right_iter-&gt;first  : key  : std::string</span>
 239 <span class="comment">// right_iter-&gt;second : data : int</span>
 240
 241 <span class="identifier">assert</span><span class="special">(</span> <span class="identifier">right_iter</span><span class="special">-&gt;</span><span class="identifier">second</span> <span class="special">==</span>  <span class="number">2</span> <span class="special">);</span>
 242
 243 <span class="identifier">assert</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">at</span><span class="special">(</span><span class="string">"one"</span><span class="special">)</span> <span class="special">==</span> <span class="number">1</span> <span class="special">);</span>
 244
 245 <span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">erase</span><span class="special">(</span><span class="string">"two"</span><span class="special">);</span>
 246
 247 <a class="co" name="boost_bimap.one_minute_tutorial.c6" href="one_minute_tutorial.html#boost_bimap.one_minute_tutorial.c7"><img src="../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</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">right_value_type</span><span class="special">(</span> <span class="string">"four"</span><span class="special">,</span> <span class="number">4</span> <span class="special">)</span> <span class="special">);</span>
 248 </pre>
 249 <p>
 250     </p>
 251 <div class="calloutlist"><table border="0" summary="Callout list"><tr>
 252 <td width="5%" valign="top" align="left"><p><a name="boost_bimap.one_minute_tutorial.c7"></a><a href="#boost_bimap.one_minute_tutorial.c6"><img src="../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
 253 <td valign="top" align="left"><p>
 254           This line produces the same effect of <code class="computeroutput"><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">4</span><span class="special">,</span><span class="string">"four"</span><span class="special">)</span>
 255           <span class="special">);</span></code>
 256         </p></td>
 257 </tr></table></div>
 258 <h4>
 259 <a name="boost_bimap.one_minute_tutorial.h6"></a>
 260       <span class="phrase"><a name="boost_bimap.one_minute_tutorial.differences_with_std__map"></a></span><a class="link" href="one_minute_tutorial.html#boost_bimap.one_minute_tutorial.differences_with_std__map">Differences
 261       with std::map</a>
 262     </h4>
 263 <p>
 264       The main difference between bimap views and their standard containers counterparts
 265       is that, because of the bidirectional nature of a bimap, the values stored
 266       in it can not be modified directly using iterators. For example, when a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span><span class="special">&gt;</span></code> iterator
 267       is dereferenced the return type is <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="identifier">X</span><span class="special">,</span>
 268       <span class="identifier">Y</span><span class="special">&gt;</span></code>,
 269       so the following code is valid: <code class="computeroutput"><span class="identifier">m</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()-&gt;</span><span class="identifier">second</span> <span class="special">=</span> <span class="identifier">new_value</span><span class="special">;</span></code>.
 270       However dereferencing a <code class="computeroutput"><span class="identifier">bimap</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span><span class="special">&gt;::</span><span class="identifier">left_iterator</span></code>
 271       returns a type that is <span class="emphasis"><em>signature-compatible</em></span> with a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="identifier">X</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Y</span><span class="special">&gt;</span></code>
 272     </p>
 273 <pre class="programlisting"><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">)-&gt;</span><span class="identifier">second</span> <span class="special">=</span> <span class="string">"1"</span><span class="special">;</span> <span class="comment">// Compilation error</span>
 274 </pre>
 275 <p>
 276       If you insert <code class="computeroutput"><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="string">"one"</span><span class="special">)</span></code> 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> in a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</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> the second insertion will have no effect.
 277       In a <code class="computeroutput"><span class="identifier">bimap</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span><span class="special">&gt;</span></code> both keys have to remain unique. The insertion
 278       may fail in other situtions too. Lets see an example
 279     </p>
 280 <pre class="programlisting"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">clear</span><span class="special">();</span>
 281
 282 <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>
 283
 284 <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">"1"</span>   <span class="special">)</span> <span class="special">);</span> <span class="comment">// No effect!</span>
 285 <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">"one"</span> <span class="special">)</span> <span class="special">);</span> <span class="comment">// No effect!</span>
 286
 287 <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>
 288 </pre>
 289 <h4>
 290 <a name="boost_bimap.one_minute_tutorial.h7"></a>
 291       <span class="phrase"><a name="boost_bimap.one_minute_tutorial.a_simple_example"></a></span><a class="link" href="one_minute_tutorial.html#boost_bimap.one_minute_tutorial.a_simple_example">A
 292       simple example</a>
 293     </h4>
 294 <p>
 295       Look how you can reuse code that is intend to be used with std::maps, like
 296       the print_map function in this example.
 297     </p>
 298 <p>
 299       <a href="../../../example/simple_bimap.cpp" target="_top">Go to source code</a>
 300     </p>
 301 <p>
 302 </p>
 303 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
 304 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
 305
 306 <span class="preprocessor">#include</span> <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">hpp</span><span class="special">&gt;</span>
 307
 308 <span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">MapType</span> <span class="special">&gt;</span>
 309 <span class="keyword">void</span> <span class="identifier">print_map</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">MapType</span> <span class="special">&amp;</span> <span class="identifier">map</span><span class="special">,</span>
 310                <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&amp;</span> <span class="identifier">separator</span><span class="special">,</span>
 311                <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span> <span class="special">&amp;</span> <span class="identifier">os</span> <span class="special">)</span>
 312 <span class="special">{</span>
 313     <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">MapType</span><span class="special">::</span><span class="identifier">const_iterator</span> <span class="identifier">const_iterator</span><span class="special">;</span>
 314
 315     <span class="keyword">for</span><span class="special">(</span> <span class="identifier">const_iterator</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">map</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">iend</span> <span class="special">=</span> <span class="identifier">map</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span> <span class="identifier">i</span> <span class="special">!=</span> <span class="identifier">iend</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span> <span class="special">)</span>
 316     <span class="special">{</span>
 317         <span class="identifier">os</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span><span class="special">-&gt;</span><span class="identifier">first</span> <span class="special">&lt;&lt;</span> <span class="identifier">separator</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span><span class="special">-&gt;</span><span class="identifier">second</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 318     <span class="special">}</span>
 319 <span class="special">}</span>
 320
 321 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
 322 <span class="special">{</span>
 323     <span class="comment">// Soccer World cup</span>
 324
 325     <span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</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="keyword">int</span> <span class="special">&gt;</span> <span class="identifier">results_bimap</span><span class="special">;</span>
 326     <span class="keyword">typedef</span> <span class="identifier">results_bimap</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">position</span><span class="special">;</span>
 327
 328     <span class="identifier">results_bimap</span> <span class="identifier">results</span><span class="special">;</span>
 329     <span class="identifier">results</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">position</span><span class="special">(</span><span class="string">"Argentina"</span>    <span class="special">,</span><span class="number">1</span><span class="special">)</span> <span class="special">);</span>
 330     <span class="identifier">results</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">position</span><span class="special">(</span><span class="string">"Spain"</span>        <span class="special">,</span><span class="number">2</span><span class="special">)</span> <span class="special">);</span>
 331     <span class="identifier">results</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">position</span><span class="special">(</span><span class="string">"Germany"</span>      <span class="special">,</span><span class="number">3</span><span class="special">)</span> <span class="special">);</span>
 332     <span class="identifier">results</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">position</span><span class="special">(</span><span class="string">"France"</span>       <span class="special">,</span><span class="number">4</span><span class="special">)</span> <span class="special">);</span>
 333
 334     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The number of countries is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">results</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span>
 335               <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 336
 337     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The winner is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">results</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="number">1</span><span class="special">)</span>
 338               <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
 339               <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 340
 341     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Countries names ordered by their final position:"</span>
 342               <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 343
 344     <span class="comment">// results.right works like a std::map&lt; int, std::string &gt;</span>
 345
 346     <span class="identifier">print_map</span><span class="special">(</span> <span class="identifier">results</span><span class="special">.</span><span class="identifier">right</span><span class="special">,</span> <span class="string">") "</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">);</span>
 347
 348     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
 349               <span class="special">&lt;&lt;</span> <span class="string">"Countries names ordered alphabetically along with"</span>
 350                     <span class="string">"their final position:"</span>
 351               <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 352
 353     <span class="comment">// results.left works like a std::map&lt; std::string, int &gt;</span>
 354
 355     <span class="identifier">print_map</span><span class="special">(</span> <span class="identifier">results</span><span class="special">.</span><span class="identifier">left</span><span class="special">,</span> <span class="string">" ends in position "</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">);</span>
 356
 357     <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 358 <span class="special">}</span>
 359 </pre>
 360 <p>
 361     </p>
 362 <p>
 363       The output of this program will be the following:
 364     </p>
 365 <pre class="programlisting"><code class="literal">The number of countries is 4</code>
 366
 367 <code class="literal">The winner is Argentina</code>
 368
 369 <code class="literal">Countries names ordered by their final position:</code>
 370 <code class="literal">1) Argentina</code>
 371 <code class="literal">2) Spain</code>
 372 <code class="literal">3) Germany</code>
 373 <code class="literal">4) France</code>
 374
 375 <code class="literal">Countries names ordered alphabetically along with their final position:</code>
 376 <code class="literal">Argentina ends in position 1</code>
 377 <code class="literal">France ends in position 4</code>
 378 <code class="literal">Germany ends in position 3</code>
 379 <code class="literal">Spain ends in position 2</code>
 380 </pre>
 381 <h4>
 382 <a name="boost_bimap.one_minute_tutorial.h8"></a>
 383       <span class="phrase"><a name="boost_bimap.one_minute_tutorial.continuing_the_journey"></a></span><a class="link" href="one_minute_tutorial.html#boost_bimap.one_minute_tutorial.continuing_the_journey">Continuing
 384       the journey</a>
 385     </h4>
 386 <p>
 387       For information on function signatures, see any standard library documentation
 388       or read the <a class="link" href="reference.html" title="Reference">reference</a> section
 389       of this documentation.
 390     </p>
 391 <div class="caution"><table border="0" summary="Caution">
 392 <tr>
 393 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../doc/src/images/caution.png"></td>
 394 <th align="left">Caution</th>
 395 </tr>
 396 <tr><td align="left" valign="top"><p>
 397         Be aware that a bidirectional map is only signature-compatible with standard
 398         containers. Some functions may give different results, such as in the case
 399         of inserting a pair into the left map where the second value conflicts with
 400         a stored relation in the container. The functions may be slower in a bimap
 401         because of the duplicated constraints. It is strongly recommended that you
 402         read <a class="link" href="the_tutorial.html" title="The tutorial">The full tutorial</a> if
 403         you intend to use a bimap in a serious project.
 404       </p></td></tr>
 405 </table></div>
 406 <div class="footnotes">
 407 <br><hr style="width:100; align:left;">
 408 <div id="ftn.boost_bimap.one_minute_tutorial.f0" class="footnote"><p><a href="#boost_bimap.one_minute_tutorial.f0" class="para"><sup class="para">[1] </sup></a>
 409         A type is <span class="emphasis"><em>signature-compatible</em></span> with other type if it
 410         has the same signature for functions and metadata. Preconditions, postconditions
 411         and the order of operations need not be the same.
 412       </p></div>
 413 </div>
 414 </div>
 415 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 416 <td align="left"></td>
 417 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2012 Matias Capeletto<p>
 418         Distributed under the Boost Software License, Version 1.0. (See accompanying
 419         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>)
 420       </p>
 421 </div></td>
 422 </tr></table>
 423 <hr>
 424 <div class="spirit-nav">
 425 <a accesskey="p" href="introduction.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="the_tutorial.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 426 </div>
 427 </body>
 428 </html>