]> git.proxmox.com Git - ceph.git/blame - ceph/src/boost/libs/bimap/doc/html/boost_bimap/one_minute_tutorial.html
projects / ceph.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
bump version to 12.2.2-pve1
[ceph.git] / ceph / src / boost / libs / bimap / doc / html / boost_bimap / one_minute_tutorial.html
CommitLineData
7c673cae
FG		 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 convenience header is available 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 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">&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>
Ceph