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 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">
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>
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>
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>
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
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
47 The following code creates an empty bimap container:
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>
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>
56 <div class=
"itemizedlist"><ul class=
"itemizedlist" style=
"list-style-type: disc; ">
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>
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>
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>
69 <span class=
"inlinemediaobject"><img src=
"../images/bimap/simple.bimap.png" alt=
"simple.bimap"></span>
72 You can see how a bimap container offers three views over the same collection
73 of bidirectional relations.
76 If we have any generic function that work with maps
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>
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
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>
98 And the output will be
100 <pre class=
"programlisting"><code class=
"literal">1 --
> one
</code>
101 <code class=
"literal">2 --
> two
</code>
103 <code class=
"literal">one --
> 1</code>
104 <code class=
"literal">two --
> 2</code>
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>
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>.
119 <span class=
"inlinemediaobject"><img src=
"../images/bimap/relation.and.pair.png" alt=
"relation.and.pair"></span>
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
127 A convenience header is available in the boost directory:
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>
132 Lets define a bidirectional map between integers and strings:
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>
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>
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
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>
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>
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>
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>
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
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
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>
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>
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>
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>
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>
200 <div class=
"calloutlist"><table border=
"0" summary=
"Callout list">
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>
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-
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>
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
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.
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>
238 <span class=
"comment">// right_iter-
>first : key : std::string
</span>
239 <span class=
"comment">// right_iter-
>second : data : int
</span>
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>
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>
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>
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>
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>
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
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>
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>
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
280 <pre class=
"programlisting"><span class=
"identifier">bm
</span><span class=
"special">.
</span><span class=
"identifier">clear
</span><span class=
"special">();
</span>
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>
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>
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>
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
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.
299 <a href=
"../../../example/simple_bimap.cpp" target=
"_top">Go to source code
</a>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
344 <span class=
"comment">// results.right works like a std::map
< int, std::string
></span>
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>
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>
353 <span class=
"comment">// results.left works like a std::map
< std::string, int
></span>
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>
357 <span class=
"keyword">return
</span> <span class=
"number">0</span><span class=
"special">;
</span>
358 <span class=
"special">}
</span>
363 The output of this program will be the following:
365 <pre class=
"programlisting"><code class=
"literal">The number of countries is
4</code>
367 <code class=
"literal">The winner is Argentina
</code>
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>
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>
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
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.
391 <div class=
"caution"><table border=
"0" summary=
"Caution">
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>
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.
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.
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>)
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>