1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 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.79.1"> 7<link rel="home" href="../index.html" title="Chapter 1. Boost.Bimap"> 8<link rel="up" href="../index.html" title="Chapter 1. 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"> 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"><</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span><span class="special">></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" name="boost_bimap.one_minute_tutorial.f0"><sup class="footnote">[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"><</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span><span class="special">></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"><</span><span class="identifier">Y</span><span class="special">,</span><span class="identifier">X</span><span class="special">></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"><</span> <span class="identifier">relation</span><span class="special"><</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span><span class="special">></span> <span class="special">></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"><</span> <span class="keyword">class</span> <span class="identifier">MapType</span> <span class="special">></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">&</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"><<</span> <span class="identifier">iter</span><span class="special">-></span><span class="identifier">first</span> <span class="special"><<</span> <span class="string">"-->"</span> <span class="special"><<</span> <span class="identifier">iter</span><span class="special">-></span><span class="identifier">second</span> <span class="special"><<</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"><</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">></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 --> one</code> 101<code class="literal">2 --> two</code> 102... 103<code class="literal">one --> 1</code> 104<code class="literal">two --> 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 convenience header is available in the boost directory: 128 </p> 129<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</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">></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"><</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">></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"><<</span> <span class="string">"There are "</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="string">"relations"</span> <span class="special"><<</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->left : data : int</span> 162 <span class="comment">// iter->right : data : std::string</span> 163 164 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">iter</span><span class="special">-></span><span class="identifier">left</span> <span class="special"><<</span> <span class="string">" <--> "</span> <span class="special"><<</span> <span class="identifier">iter</span><span class="special">-></span><span class="identifier">right</span> <span class="special"><<</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"><</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">></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->first : key : int</span> 188 <span class="comment">// left_iter->second : data : std::string</span> 189 190 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">left_iter</span><span class="special">-></span><span class="identifier">first</span> <span class="special"><<</span> <span class="string">" --> "</span> <span class="special"><<</span> <span class="identifier">left_iter</span><span class="special">-></span><span class="identifier">second</span> <span class="special"><<</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">-></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"><</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">></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->first : key : std::string</span> 239<span class="comment">// right_iter->second : data : int</span> 240 241<span class="identifier">assert</span><span class="special">(</span> <span class="identifier">right_iter</span><span class="special">-></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"><</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span><span class="special">></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"><</span><span class="keyword">const</span> <span class="identifier">X</span><span class="special">,</span> 268 <span class="identifier">Y</span><span class="special">></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">()-></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"><</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span><span class="special">>::</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"><</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">></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">)-></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"><</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">></span></code> the second insertion will have no effect. 277 In a <code class="computeroutput"><span class="identifier">bimap</span><span class="special"><</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span><span class="special">></span></code> both keys have to remain unique. The insertion 278 may fail in other situations 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"><</span><span class="identifier">string</span><span class="special">></span> 304<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 305 306<span class="preprocessor">#include</span> <span class="special"><</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">></span> 307 308<span class="keyword">template</span><span class="special"><</span> <span class="keyword">class</span> <span class="identifier">MapType</span> <span class="special">></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">&</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">&</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">&</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"><<</span> <span class="identifier">i</span><span class="special">-></span><span class="identifier">first</span> <span class="special"><<</span> <span class="identifier">separator</span> <span class="special"><<</span> <span class="identifier">i</span><span class="special">-></span><span class="identifier">second</span> <span class="special"><<</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"><</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">></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"><<</span> <span class="string">"The number of countries is "</span> <span class="special"><<</span> <span class="identifier">results</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> 335 <span class="special"><<</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"><<</span> <span class="string">"The winner is "</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="identifier">at</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> 338 <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span> 339 <span class="special"><<</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"><<</span> <span class="string">"Countries names ordered by their final position:"</span> 342 <span class="special"><<</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< int, std::string ></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"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span> 349 <span class="special"><<</span> <span class="string">"Countries names ordered alphabetically along with"</span> 350 <span class="string">"their final position:"</span> 351 <span class="special"><<</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< std::string, int ></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; text-align:left;margin-left: 0"> 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 © 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> 429
