[DEV] add v1.66.0

This commit is contained in:
2018-01-12 21:47:58 +01:00
parent 87059bb1af
commit a97e9ae7d4
49032 changed files with 7668950 additions and 0 deletions

View File

@@ -0,0 +1,215 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Additional information</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Bimap">
<link rel="up" href="../the_tutorial.html" title="The tutorial">
<link rel="prev" href="unconstrained_sets.html" title="Unconstrained Sets">
<link rel="next" href="complete_instantiation_scheme.html" title="Complete instantiation scheme">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="unconstrained_sets.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="complete_instantiation_scheme.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_bimap.the_tutorial.additional_information"></a><a class="link" href="additional_information.html" title="Additional information">Additional
information</a>
</h3></div></div></div>
<p>
Bidirectional maps may have associated information about each relation. Suppose
we want to represent a books and author bidirectional map.
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span>
<span class="identifier">multiset_of</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;,</span> <span class="comment">// author</span>
<span class="identifier">set_of</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;</span> <span class="comment">// title</span>
<span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">book</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
<span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">book</span><span class="special">(</span> <span class="string">"Bjarne Stroustrup"</span> <span class="special">,</span> <span class="string">"The C++ Programming Language"</span> <span class="special">)</span> <span class="special">);</span>
<span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">book</span><span class="special">(</span> <span class="string">"Scott Meyers"</span> <span class="special">,</span> <span class="string">"Effective C++"</span> <span class="special">)</span> <span class="special">);</span>
<span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">book</span><span class="special">(</span> <span class="string">"Andrei Alexandrescu"</span> <span class="special">,</span> <span class="string">"Modern C++ Design"</span> <span class="special">)</span> <span class="special">);</span>
<span class="comment">// Print the author of Modern C++</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</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">"Modern C++ Design"</span> <span class="special">);</span>
</pre>
<p>
</p>
<p>
Suppose now that we want to store abstract of each book. We have two options:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
Books name are unique identifiers, so we can create a separate <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">string</span><span class="special">,</span> <span class="identifier">string</span> <span class="special">&gt;</span></code>
that relates books names with abstracts.
</li>
<li class="listitem">
We can use <a href="http://www.boost.org/libs/multi_index/doc/index.html" target="_top"><span class="bold"><strong>Boost.MultiIndex</strong></span></a> for the new beast.
</li>
</ol></div>
<p>
Option 1 is the wrong approach, if we go this path we lost what bimap has
won us. We now have to maintain the logic of two interdependent containers,
there is an extra string stored for each book name, and the performance will
be worse. This is far away from being a good solution.
</p>
<p>
Option 2 is correct. We start thinking books as entries in a table. So it
makes sense to start using Boost.MultiIndex. We can then add the year of
publication, the price, etc... and we can index this new items too. So Boost.MultiIndex
is a sound solution for our problem.
</p>
<p>
The thing is that there are cases where we want to maintain bimap semantics
(use <code class="computeroutput"><span class="identifier">at</span><span class="special">()</span></code>
to find an author given a book name and the other way around) and add information
about the relations that we are sure we will not want to index later (like
the abstracts). Option 1 is not possible, option 2 neither.
</p>
<p>
Boost.Bimap provides support for this kind of situations by means of an embedded
information member. You can pass an extra parameter to a bimap: <code class="computeroutput"><span class="identifier">with_info</span><span class="special">&lt;</span>
<span class="identifier">InfoType</span> <span class="special">&gt;</span></code>
and an <code class="computeroutput"><span class="identifier">info</span></code> member of type
<code class="computeroutput"><span class="identifier">InfoType</span></code> will appear in the
relation and bimap pairs.
</p>
<p>
<span class="inlinemediaobject"><img src="../../images/bimap/relation.and.pair.with.info.png" alt="relation.and.pair.with.info"></span>
</p>
<p>
Relations and bimap pairs constructors will take an extra argument. If only
two arguments are used, the information will be initialized with their default
constructor.
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span>
<span class="identifier">multiset_of</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;,</span> <span class="comment">// author</span>
<span class="identifier">set_of</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;,</span> <span class="comment">// title</span>
<span class="identifier">with_info</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;</span> <span class="comment">// abstract</span>
<span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">book</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
<span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span>
<span class="identifier">book</span><span class="special">(</span> <span class="string">"Bjarne Stroustrup"</span> <span class="special">,</span> <span class="string">"The C++ Programming Language"</span><span class="special">,</span>
<span class="string">"For C++ old-timers, the first edition of this book is"</span>
<span class="string">"the one that started it all&#8212;the font of our knowledge."</span> <span class="special">)</span>
<span class="special">);</span>
<span class="comment">// Print the author of the bible</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</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">"The C++ Programming Language"</span><span class="special">);</span>
<span class="comment">// Print the abstract of this book</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="string">"Bjarne Stroustrup"</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span><span class="special">-&gt;</span><span class="identifier">info</span><span class="special">;</span>
</pre>
<p>
</p>
<p>
Contrary to the two key types, the information will be mutable using iterators.
</p>
<p>
</p>
<pre class="programlisting"><span class="identifier">i</span><span class="special">-&gt;</span><span class="identifier">info</span> <span class="special">+=</span> <span class="string">"More details about this book"</span><span class="special">;</span>
</pre>
<p>
</p>
<p>
A new function is included in <span class="emphasis"><em>unique</em></span> map views: <code class="computeroutput"><span class="identifier">info_at</span><span class="special">(</span><span class="identifier">key</span><span class="special">)</span></code>, that
mimics the standard <code class="computeroutput"><span class="identifier">at</span><span class="special">(</span><span class="identifier">key</span><span class="special">)</span></code> function
but returned the associated information instead of the data.
</p>
<p>
</p>
<pre class="programlisting"><span class="comment">// Print the new abstract</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">info_at</span><span class="special">(</span><span class="string">"The C++ Programming Language"</span><span class="special">);</span>
</pre>
<p>
</p>
<p>
The info member can be tagged just as the left or the right member. The following
is a rewrite of the above example using user defined names:
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span>
<span class="identifier">multiset_of</span><span class="special">&lt;</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">author</span> <span class="special">&gt;</span> <span class="special">&gt;,</span>
<span class="identifier">set_of</span><span class="special">&lt;</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">title</span> <span class="special">&gt;</span> <span class="special">&gt;,</span>
<span class="identifier">with_info</span><span class="special">&lt;</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">abstract</span> <span class="special">&gt;</span> <span class="special">&gt;</span>
<span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">book</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
<span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span>
<span class="identifier">book</span><span class="special">(</span> <span class="string">"Bjarne Stroustrup"</span> <span class="special">,</span> <span class="string">"The C++ Programming Language"</span><span class="special">,</span>
<span class="string">"For C++ old-timers, the first edition of this book is"</span>
<span class="string">"the one that started it all&#8212;the font of our knowledge."</span> <span class="special">)</span>
<span class="special">);</span>
<span class="comment">// Print the author of the bible</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">title</span><span class="special">&gt;().</span><span class="identifier">at</span><span class="special">(</span><span class="string">"The C++ Programming Language"</span><span class="special">);</span>
<span class="comment">// Print the abstract of this book</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">author</span><span class="special">&gt;::</span><span class="identifier">iterator</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">author</span><span class="special">&gt;().</span><span class="identifier">find</span><span class="special">(</span><span class="string">"Bjarne Stroustrup"</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">abstract</span><span class="special">&gt;();</span>
<span class="comment">// Contrary to the two key types, the information will be mutable</span>
<span class="comment">// using iterators.</span>
<span class="identifier">i</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">abstract</span><span class="special">&gt;()</span> <span class="special">+=</span> <span class="string">"More details about this book"</span><span class="special">;</span>
<span class="comment">// Print the new abstract</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">title</span><span class="special">&gt;().</span><span class="identifier">info_at</span><span class="special">(</span><span class="string">"The C++ Programming Language"</span><span class="special">);</span>
</pre>
<p>
</p>
<p>
<a href="../../../../example/tutorial_info_hook.cpp" target="_top">Go to source code</a>
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2006-2012 Matias Capeletto<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="unconstrained_sets.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="complete_instantiation_scheme.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,379 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Bimaps with user defined names</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Bimap">
<link rel="up" href="../the_tutorial.html" title="The tutorial">
<link rel="prev" href="useful_functions.html" title="Useful functions">
<link rel="next" href="unconstrained_sets.html" title="Unconstrained Sets">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="useful_functions.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="unconstrained_sets.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_bimap.the_tutorial.bimaps_with_user_defined_names"></a><a class="link" href="bimaps_with_user_defined_names.html" title="Bimaps with user defined names">Bimaps
with user defined names</a>
</h3></div></div></div>
<p>
In the following example, the library user inserted comments to guide future
programmers:
</p>
<p>
<a href="../../../../example/user_defined_names.cpp" target="_top">Go to source code</a>
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span>
<span class="special">&lt;</span>
<span class="identifier">multiset_of</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;,</span>
<span class="keyword">int</span>
<span class="special">&gt;</span> <span class="identifier">People</span><span class="special">;</span>
<span class="identifier">People</span> <span class="identifier">people</span><span class="special">;</span>
<span class="comment">// ...</span>
<span class="keyword">int</span> <span class="identifier">user_id</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cin</span> <span class="special">&gt;&gt;</span> <span class="identifier">user_id</span><span class="special">;</span>
<span class="comment">// people.right : map&lt;id,name&gt;</span>
<span class="identifier">People</span><span class="special">::</span><span class="identifier">right_const_iterator</span> <span class="identifier">id_iter</span> <span class="special">=</span> <span class="identifier">people</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="identifier">user_id</span><span class="special">);</span>
<span class="keyword">if</span><span class="special">(</span> <span class="identifier">id_iter</span> <span class="special">!=</span> <span class="identifier">people</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">end</span><span class="special">()</span> <span class="special">)</span>
<span class="special">{</span>
<span class="comment">// first : id</span>
<span class="comment">// second : name</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"name: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">id_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">&lt;&lt;</span> <span class="string">"id: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">id_iter</span><span class="special">-&gt;</span><span class="identifier">first</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>
<span class="special">}</span>
<span class="keyword">else</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Unknown id, users are:"</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>
<span class="comment">// people.left : map&lt;name,id&gt;</span>
<span class="keyword">for</span><span class="special">(</span> <span class="identifier">People</span><span class="special">::</span><span class="identifier">left_const_iterator</span>
<span class="identifier">name_iter</span> <span class="special">=</span> <span class="identifier">people</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">people</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span>
<span class="identifier">name_iter</span> <span class="special">!=</span> <span class="identifier">iend</span><span class="special">;</span> <span class="special">++</span><span class="identifier">name_iter</span> <span class="special">)</span>
<span class="special">{</span>
<span class="comment">// first : name</span>
<span class="comment">// second : id</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"name: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">name_iter</span><span class="special">-&gt;</span><span class="identifier">first</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
<span class="special">&lt;&lt;</span> <span class="string">"id: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">name_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>
<span class="special">}</span>
<span class="special">}</span>
</pre>
<p>
</p>
<p>
In Boost.Bimap there is a better way to document the code and in the meantime
helping you to write more maintainable and readable code. You can tag the
two collections of the bimap so they can be accessed by more descriptive
names.
</p>
<p>
<span class="inlinemediaobject"><img src="../../images/bimap/tagged.png" alt="tagged"></span>
</p>
<p>
A tagged type is a type that has been labelled using a tag. A tag is any
valid C++ type. In a bimap, the types are always tagged. If you do not specify
your own tag, the container uses <code class="computeroutput"><span class="identifier">member_at</span><span class="special">::</span><span class="identifier">left</span></code>
and <code class="computeroutput"><span class="identifier">member_at</span><span class="special">::</span><span class="identifier">right</span></code> to tag the left and right sides respectively.
In order to specify a custom tag, the type of each side has to be tagged.
Tagging a type is very simple:
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">a_tag</span> <span class="special">&gt;</span> <span class="identifier">tagged_int</span><span class="special">;</span>
</pre>
<p>
Now we can rewrite the example:
</p>
<p>
<a href="../../../../example/user_defined_names.cpp" target="_top">Go to source code</a>
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">id</span> <span class="special">{};</span> <span class="comment">// Tag for the identification number</span>
<span class="keyword">struct</span> <span class="identifier">name</span> <span class="special">{};</span> <span class="comment">// Tag for the name of the person</span>
<span class="keyword">typedef</span> <span class="identifier">bimap</span>
<span class="special">&lt;</span>
<span class="identifier">tagged</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">,</span> <span class="identifier">id</span> <span class="special">&gt;</span> <span class="special">,</span>
<span class="identifier">multiset_of</span><span class="special">&lt;</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">name</span> <span class="special">&gt;</span> <span class="special">&gt;</span>
<span class="special">&gt;</span> <span class="identifier">People</span><span class="special">;</span>
<span class="identifier">People</span> <span class="identifier">people</span><span class="special">;</span>
<span class="comment">// ...</span>
<span class="keyword">int</span> <span class="identifier">user_id</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cin</span> <span class="special">&gt;&gt;</span> <span class="identifier">user_id</span><span class="special">;</span>
<span class="identifier">People</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">id</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span> <span class="identifier">id_iter</span> <span class="special">=</span> <span class="identifier">people</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">id</span><span class="special">&gt;().</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">user_id</span><span class="special">);</span>
<span class="keyword">if</span><span class="special">(</span> <span class="identifier">id_iter</span> <span class="special">!=</span> <span class="identifier">people</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">id</span><span class="special">&gt;().</span><span class="identifier">end</span><span class="special">()</span> <span class="special">)</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"name: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">id_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">name</span><span class="special">&gt;()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
<span class="special">&lt;&lt;</span> <span class="string">"id: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">id_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">id</span><span class="special">&gt;()</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>
<span class="special">}</span>
<span class="keyword">else</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Unknown id, users are:"</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>
<span class="keyword">for</span><span class="special">(</span> <span class="identifier">People</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">name</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span>
<span class="identifier">name_iter</span> <span class="special">=</span> <span class="identifier">people</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">name</span><span class="special">&gt;().</span><span class="identifier">begin</span><span class="special">(),</span>
<span class="identifier">iend</span> <span class="special">=</span> <span class="identifier">people</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">name</span><span class="special">&gt;().</span><span class="identifier">end</span><span class="special">();</span>
<span class="identifier">name_iter</span> <span class="special">!=</span> <span class="identifier">iend</span><span class="special">;</span> <span class="special">++</span><span class="identifier">name_iter</span> <span class="special">)</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"name: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">name_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">name</span><span class="special">&gt;()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
<span class="special">&lt;&lt;</span> <span class="string">"id: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">name_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">id</span><span class="special">&gt;()</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>
<span class="special">}</span>
<span class="special">}</span>
</pre>
<p>
</p>
<p>
Here is a list of common structures in both tagged and untagged versions.
Remember that when the bimap has user defined tags you can still use the
untagged version structures.
</p>
<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">Left</span> <span class="special">{};</span>
<span class="keyword">struct</span> <span class="identifier">Right</span> <span class="special">{};</span>
<span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span>
<span class="identifier">multiset_of</span><span class="special">&lt;</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">Left</span> <span class="special">&gt;</span> <span class="special">&gt;,</span>
<span class="identifier">unordered_set_of</span><span class="special">&lt;</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">Right</span> <span class="special">&gt;</span> <span class="special">&gt;</span>
<span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
<span class="comment">//...</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">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">bm_type</span><span class="special">::</span><span class="identifier">left_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">bm_type</span><span class="special">::</span><span class="identifier">right_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">begin</span><span class="special">();</span>
</pre>
<div class="table">
<a name="boost_bimap.the_tutorial.bimaps_with_user_defined_names.t0"></a><p class="title"><b>Table&#160;1.3.&#160;Equivalence of expresions using user defined names</b></p>
<div class="table-contents"><table class="table" summary="Equivalence of expresions using user defined names">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Untagged version
</p>
</th>
<th>
<p>
Tagged version
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;()</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;()</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_map</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">right_value_type</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;::</span><span class="identifier">value_type</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;::</span><span class="identifier">iterator</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">right_const_iterator</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">left</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;()</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">right</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;()</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">left_iter</span><span class="special">-&gt;</span><span class="identifier">first</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">left_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;()</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">left_iter</span><span class="special">-&gt;</span><span class="identifier">second</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">left_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;()</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">right_iter</span><span class="special">-&gt;</span><span class="identifier">first</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">right_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;()</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">right_iter</span><span class="special">-&gt;</span><span class="identifier">second</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">right_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;()</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">project_left</span><span class="special">(</span><span class="identifier">iter</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">project</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;(</span><span class="identifier">iter</span><span class="special">)</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">project_right</span><span class="special">(</span><span class="identifier">iter</span><span class="special">)</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">project</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;(</span><span class="identifier">iter</span><span class="special">)</span></code>
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2006-2012 Matias Capeletto<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="useful_functions.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="unconstrained_sets.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,240 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Complete instantiation scheme</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Bimap">
<link rel="up" href="../the_tutorial.html" title="The tutorial">
<link rel="prev" href="additional_information.html" title="Additional information">
<link rel="next" href="../bimap_and_boost.html" title="Bimap and Boost">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="additional_information.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../bimap_and_boost.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_bimap.the_tutorial.complete_instantiation_scheme"></a><a class="link" href="complete_instantiation_scheme.html" title="Complete instantiation scheme">Complete
instantiation scheme</a>
</h3></div></div></div>
<p>
To summarize, this is the complete instantiation scheme.
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span>
<span class="special">&lt;</span>
<span class="identifier">LeftCollectionType</span><span class="special">,</span> <span class="identifier">RightCollectionType</span>
<span class="special">[</span> <span class="special">,</span> <span class="identifier">SetTypeOfRelation</span> <span class="special">]</span> <span class="comment">// Default to left_based</span>
<span class="special">[</span> <span class="special">,</span> <span class="identifier">with_info</span><span class="special">&lt;</span> <span class="identifier">Info</span> <span class="special">&gt;</span> <span class="special">]</span> <span class="comment">// Default to no info</span>
<span class="special">[</span> <span class="special">,</span> <span class="identifier">Allocator</span> <span class="special">]</span> <span class="comment">// Default to std::allocator&lt;&gt;</span>
<span class="special">&gt;</span> <span class="identifier">bm</span><span class="special">;</span>
</pre>
<p>
<code class="computeroutput"><span class="special">{</span><span class="identifier">Side</span><span class="special">}</span><span class="identifier">CollectionType</span></code>
can directly be a type. This defaults to <code class="computeroutput"><span class="identifier">set_of</span><span class="special">&lt;</span><span class="identifier">Type</span><span class="special">&gt;</span></code>, or can be a <code class="computeroutput"><span class="special">{</span><span class="identifier">CollectionType</span><span class="special">}</span><span class="identifier">_of</span><span class="special">&lt;</span><span class="identifier">Type</span><span class="special">&gt;</span></code>
specification. Additionally, the type of this two parameters can be tagged
to specify user defined names instead of the usual <code class="computeroutput"><span class="identifier">member_at</span><span class="special">::-</span><span class="identifier">Side</span><span class="special">-</span></code> tags.
</p>
<p>
The possible way to use the first parameter are:
</p>
<pre class="programlisting"><span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">Type</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">&gt;</span>
</pre>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Left type: <code class="computeroutput"><span class="identifier">Type</span></code>
</li>
<li class="listitem">
Left collection type: <code class="computeroutput"><span class="identifier">set_of</span><span class="special">&lt;</span> <span class="identifier">Type</span>
<span class="special">&gt;</span></code>
</li>
<li class="listitem">
Left tag: <code class="computeroutput"><span class="identifier">member_at</span><span class="special">::</span><span class="identifier">left</span></code>
</li>
</ul></div>
<pre class="programlisting"><span class="identifier">bimap</span><span class="special">&lt;</span> <span class="special">{</span><span class="identifier">CollectionType</span><span class="special">}</span><span class="identifier">_of</span><span class="special">&lt;</span> <span class="identifier">Type</span> <span class="special">&gt;,</span> <span class="identifier">R</span> <span class="special">&gt;</span>
</pre>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Left type: <code class="computeroutput"><span class="identifier">Type</span></code>
</li>
<li class="listitem">
Left collection type: <code class="computeroutput"><span class="special">{</span><span class="identifier">CollectionType</span><span class="special">}</span><span class="identifier">_of</span><span class="special">&lt;</span> <span class="identifier">LeftType</span> <span class="special">&gt;</span></code>
</li>
<li class="listitem">
Left tag: <code class="computeroutput"><span class="identifier">member_at</span><span class="special">::</span><span class="identifier">left</span></code>
</li>
</ul></div>
<pre class="programlisting"><span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="identifier">Type</span><span class="special">,</span> <span class="identifier">Tag</span> <span class="special">&gt;,</span> <span class="identifier">R</span> <span class="special">&gt;</span>
</pre>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Left type: <code class="computeroutput"><span class="identifier">Type</span></code>
</li>
<li class="listitem">
Left collection type: <code class="computeroutput"><span class="identifier">set_of</span><span class="special">&lt;</span> <span class="identifier">LeftType</span>
<span class="special">&gt;</span></code>
</li>
<li class="listitem">
Left tag: <code class="computeroutput"><span class="identifier">Tag</span></code>
</li>
</ul></div>
<pre class="programlisting"><span class="identifier">bimap</span><span class="special">&lt;</span> <span class="special">{</span><span class="identifier">CollectionType</span><span class="special">}</span><span class="identifier">_of</span><span class="special">&lt;</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="identifier">Type</span><span class="special">,</span> <span class="identifier">Tag</span> <span class="special">&gt;</span> <span class="special">&gt;,</span> <span class="identifier">R</span> <span class="special">&gt;</span>
</pre>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Left type: <code class="computeroutput"><span class="identifier">Type</span></code>
</li>
<li class="listitem">
Left collection type: <code class="computeroutput"><span class="special">{</span><span class="identifier">CollectionType</span><span class="special">}</span><span class="identifier">_of</span><span class="special">&lt;</span> <span class="identifier">LeftType</span> <span class="special">&gt;</span></code>
</li>
<li class="listitem">
Left tag: <code class="computeroutput"><span class="identifier">Tag</span></code>
</li>
</ul></div>
<p>
The same options are available for the second parameter.
</p>
<p>
The last three parameters are used to specify the collection type of the
relation, the information member and the allocator type.
</p>
<p>
If you want to specify a custom allocator type while relying on the default
value of CollectionTypeOfRelation, you can do so by simply writing <code class="computeroutput"><span class="identifier">bimap</span><span class="special">&lt;</span><span class="identifier">LeftKeyType</span><span class="special">,</span>
<span class="identifier">RightKeyType</span><span class="special">,</span>
<span class="identifier">Allocator</span><span class="special">&gt;</span></code>.
Boost.Bimap's internal machinery detects that the third parameter in this
case does not refer to the relation type but rather to an allocator.
</p>
<p>
The following are the possible ways of instantiating the last three parameters
of a bimap. You can ignore some of the parameter but the order must be respected.
</p>
<pre class="programlisting"><span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">L</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">&gt;</span>
</pre>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
set_of_relation_type: based on the left key type
</li>
<li class="listitem">
info: no info
</li>
<li class="listitem">
allocator: std::allocator
</li>
</ul></div>
<pre class="programlisting"><span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">L</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">,</span><span class="identifier">SetOfRelationType</span><span class="special">&gt;</span>
</pre>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
set_of_relation_type: SetOfRelationType
</li>
<li class="listitem">
info: no info
</li>
<li class="listitem">
allocator: std::allocator
</li>
</ul></div>
<pre class="programlisting"><span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">L</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">,</span> <span class="identifier">SetOfRelationType</span><span class="special">,</span> <span class="identifier">with_info</span><span class="special">&lt;</span><span class="identifier">Info</span><span class="special">&gt;</span> <span class="special">&gt;</span>
</pre>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
set_of_relation_type: SetOfRelationType
</li>
<li class="listitem">
info: Info
</li>
<li class="listitem">
allocator: std::allocator
</li>
</ul></div>
<pre class="programlisting"><span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">L</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">,</span> <span class="identifier">SetOfRelationType</span><span class="special">,</span> <span class="identifier">with_info</span><span class="special">&lt;</span><span class="identifier">Info</span><span class="special">&gt;,</span> <span class="identifier">Allocator</span><span class="special">&gt;</span>
</pre>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
set_of_relation_type: SetOfRelationType
</li>
<li class="listitem">
info: Info
</li>
<li class="listitem">
allocator: Allocator
</li>
</ul></div>
<pre class="programlisting"><span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">L</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">,</span> <span class="identifier">SetOfRelationType</span><span class="special">,</span> <span class="identifier">Allocator</span><span class="special">&gt;</span>
</pre>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
set_of_relation_type: SetOfRelationType
</li>
<li class="listitem">
info: no info
</li>
<li class="listitem">
allocator: Allocator
</li>
</ul></div>
<pre class="programlisting"><span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">L</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">,</span> <span class="identifier">with_info</span><span class="special">&lt;</span><span class="identifier">Info</span><span class="special">&gt;</span> <span class="special">&gt;</span>
</pre>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
set_of_relation_type: based on the left key type
</li>
<li class="listitem">
info: Info
</li>
<li class="listitem">
allocator: std::allocator
</li>
</ul></div>
<pre class="programlisting"><span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">L</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">,</span> <span class="identifier">with_info</span><span class="special">&lt;</span><span class="identifier">Info</span><span class="special">&gt;,</span> <span class="identifier">Allocator</span><span class="special">&gt;</span>
</pre>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
set_of_relation_type: based on the left key type
</li>
<li class="listitem">
allocator: Allocator
</li>
</ul></div>
<pre class="programlisting"><span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">L</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">,</span> <span class="identifier">Allocator</span><span class="special">&gt;</span>
</pre>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
set_of_relation_type: based on the left key type
</li>
<li class="listitem">
info: no info
</li>
<li class="listitem">
allocator: Allocator
</li>
</ul></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2006-2012 Matias Capeletto<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="additional_information.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../bimap_and_boost.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,538 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Controlling collection types</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Bimap">
<link rel="up" href="../the_tutorial.html" title="The tutorial">
<link rel="prev" href="discovering_the_bimap_framework.html" title="Discovering the bimap framework">
<link rel="next" href="the_collection_of_relations_type.html" title="The collection of relations type">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="discovering_the_bimap_framework.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="the_collection_of_relations_type.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_bimap.the_tutorial.controlling_collection_types"></a><a class="link" href="controlling_collection_types.html" title="Controlling collection types">Controlling
collection types</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="controlling_collection_types.html#boost_bimap.the_tutorial.controlling_collection_types.freedom_of_choice">Freedom
of choice</a></span></dt>
<dt><span class="section"><a href="controlling_collection_types.html#boost_bimap.the_tutorial.controlling_collection_types.configuration_parameters">Configuration
parameters</a></span></dt>
<dt><span class="section"><a href="controlling_collection_types.html#boost_bimap.the_tutorial.controlling_collection_types.examples">Examples</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.controlling_collection_types.freedom_of_choice"></a><a class="link" href="controlling_collection_types.html#boost_bimap.the_tutorial.controlling_collection_types.freedom_of_choice" title="Freedom of choice">Freedom
of choice</a>
</h4></div></div></div>
<p>
As has already been said, in STL maps, you can only control the constraints
from one of the collections, namely the one that you are viewing. In Boost.Bimap,
you can control both and it is as easy as using the STL.
</p>
<p>
<span class="inlinemediaobject"><img src="../../images/bimap/extended.mapping.framework.png" alt="extended.mapping.framework"></span>
</p>
<p>
The idea is to use the same constraint names that are used in the standard.
If you don't specify the collection type, Boost.Bimap assumes that the
collection is a set. The instantiation of a bimap with custom collection
types looks like this:
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span> <span class="bold"><strong>CollectionType</strong></span><span class="identifier">_of</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;,</span> <span class="bold"><strong>CollectionType</strong></span><span class="identifier">_of</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
</pre>
<p>
The following is the list of all supported collection types.
</p>
<div class="table">
<a name="boost_bimap.the_tutorial.controlling_collection_types.freedom_of_choice.t0"></a><p class="title"><b>Table&#160;1.2.&#160;Collection of Key Types</b></p>
<div class="table-contents"><table class="table" summary="Collection of Key Types">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
name
</p>
</th>
<th>
<p>
Features
</p>
</th>
<th>
<p>
map view type
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">set_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>ordered, unique</em></span>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">map</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">multiset_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>ordered </em></span>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">multimap</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">unordered_set_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>hashed, unique </em></span>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">unordered_map</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">unordered_multiset_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>hashed </em></span>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">unordered_multimap</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">list_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>sequenced </em></span>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">list_map</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">vector_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>random access </em></span>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">vector_map</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">unconstrained_set_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>unconstrained </em></span>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>can not be viewed</em></span>
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
<code class="computeroutput"><span class="identifier">list_of</span></code> and <code class="computeroutput"><span class="identifier">vector_of</span></code> map views are not associated
with any existing STL associative containers. They are two examples of
unsorted associative containers. <code class="computeroutput"><span class="identifier">unconstrained_set_of</span></code>
allow the user to ignore a view. This will be explained later.
</p>
<p>
<span class="inlinemediaobject"><img src="../../images/bimap/bimap.structures.png" alt="bimap.structures"></span>
</p>
<p>
The selection of the collection type affects the possible operations that
you can perform with each side of the bimap and the time it takes to do
each. If we have:
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span> <span class="bold"><strong>CollectionType</strong></span><span class="identifier">_of</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;,</span> <span class="bold"><strong>CollectionType</strong></span><span class="identifier">_of</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
</pre>
<p>
The following now describes the resulting map views of the bidirectional
map.
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span></code> is signature-compatible with
<span class="bold"><strong>LeftMapType</strong></span><code class="computeroutput"><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span><span class="identifier">B</span><span class="special">&gt;</span></code>
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span></code> is signature-compatible with
<span class="bold"><strong>RightMapType</strong></span><code class="computeroutput"><span class="special">&lt;</span><span class="identifier">B</span><span class="special">,</span><span class="identifier">A</span><span class="special">&gt;</span></code>
</li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.controlling_collection_types.configuration_parameters"></a><a class="link" href="controlling_collection_types.html#boost_bimap.the_tutorial.controlling_collection_types.configuration_parameters" title="Configuration parameters">Configuration
parameters</a>
</h4></div></div></div>
<p>
Each collection type template has different parameters to control its behaviour.
For example, in <code class="computeroutput"><span class="identifier">set_of</span></code>
specification, you can pass a Functor type that compares two types. All
of these parameters are exactly the same as those of the standard library
container, except for the allocator type. You will learn later how to change
the allocator for a bimap.
</p>
<p>
The following table lists the meanings of each collection type's parameters.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
name
</p>
</th>
<th>
<p>
Additional Parameters
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">set_of</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">KeyComp</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">multiset_of</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">KeyComp</span><span class="special">&gt;</span></code>
</p>
</td>
<td>
<p>
<span class="bold"><strong>KeyComp </strong></span> is a Functor that compares
two types using a less-than operator. By default, this is <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">unordered_set_of</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">HashFunctor</span><span class="special">,</span><span class="identifier">EqualKey</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">unordered_multiset_of</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">HashFunctor</span><span class="special">,</span><span class="identifier">EqualKey</span><span class="special">&gt;</span></code>
</p>
</td>
<td>
<p>
<span class="bold"><strong>HashFunctor </strong></span> converts a <code class="computeroutput"><span class="identifier">T</span></code> object into an <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code> value. By default it
is <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">hash</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>.
</p>
<p>
<span class="bold"><strong>EqualKey </strong></span> is a Functor that
tests two types for equality. By default, the equality operator
is <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">equal_to</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">list_of</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
</p>
</td>
<td>
<p>
No additional parameters.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">vector_of</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
</p>
</td>
<td>
<p>
No additional parameters.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">unconstrained_set_of</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
</p>
</td>
<td>
<p>
No additional parameters.
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.controlling_collection_types.examples"></a><a class="link" href="controlling_collection_types.html#boost_bimap.the_tutorial.controlling_collection_types.examples" title="Examples">Examples</a>
</h4></div></div></div>
<h6>
<a name="boost_bimap.the_tutorial.controlling_collection_types.examples.h0"></a>
<span class="phrase"><a name="boost_bimap.the_tutorial.controlling_collection_types.examples.countries_populations"></a></span><a class="link" href="controlling_collection_types.html#boost_bimap.the_tutorial.controlling_collection_types.examples.countries_populations">Countries
Populations</a>
</h6>
<p>
We want to store countries populations. The requirements are:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
Get a list of countries in decreasing order of their populations.
</li>
<li class="listitem">
Given a country, get their population.
</li>
</ol></div>
<p>
Lets create the appropriate bimap.
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span>
<span class="identifier">unordered_set_of</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;,</span>
<span class="identifier">multiset_of</span><span class="special">&lt;</span> <span class="keyword">long</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">greater</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="special">&gt;</span>
<span class="special">&gt;</span> <span class="identifier">populations_bimap</span><span class="special">;</span>
</pre>
<p>
First of all countries names are unique identifiers, while two countries
may have the same population. This is why we choose <span class="bold"><strong>multi</strong></span><code class="computeroutput"><span class="identifier">set_of</span></code> for populations.
</p>
<p>
Using a <code class="computeroutput"><span class="identifier">multiset_of</span></code> for
population allow us to iterate over the data. Since listing countries ordered
by their names is not a requisite, we can use an <code class="computeroutput"><span class="identifier">unordered_set_of</span></code>
that allows constant order look up.
</p>
<p>
And now lets use it in a complete example
</p>
<p>
<a href="../../../../example/population_bimap.cpp" target="_top">Go to source code</a>
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span>
<span class="identifier">unordered_set_of</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;,</span>
<span class="identifier">multiset_of</span><span class="special">&lt;</span> <span class="keyword">long</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">greater</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="special">&gt;</span>
<span class="special">&gt;</span> <span class="identifier">population_bimap</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">population_bimap</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">population</span><span class="special">;</span>
<span class="identifier">population_bimap</span> <span class="identifier">pop</span><span class="special">;</span>
<span class="identifier">pop</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">population</span><span class="special">(</span><span class="string">"China"</span><span class="special">,</span> <span class="number">1321000000</span><span class="special">)</span> <span class="special">);</span>
<span class="identifier">pop</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">population</span><span class="special">(</span><span class="string">"India"</span><span class="special">,</span> <span class="number">1129000000</span><span class="special">)</span> <span class="special">);</span>
<span class="identifier">pop</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">population</span><span class="special">(</span><span class="string">"United States"</span><span class="special">,</span> <span class="number">301950000</span><span class="special">)</span> <span class="special">);</span>
<span class="identifier">pop</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">population</span><span class="special">(</span><span class="string">"Indonesia"</span><span class="special">,</span> <span class="number">234950000</span><span class="special">)</span> <span class="special">);</span>
<span class="identifier">pop</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">population</span><span class="special">(</span><span class="string">"Brazil"</span><span class="special">,</span> <span class="number">186500000</span><span class="special">)</span> <span class="special">);</span>
<span class="identifier">pop</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">population</span><span class="special">(</span><span class="string">"Pakistan"</span><span class="special">,</span> <span class="number">163630000</span><span class="special">)</span> <span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Countries by their population:"</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>
<span class="comment">// First requirement</span>
<a class="co" name="boost_bimap.the_tutorial.controlling_collection_types.examples.c0" href="controlling_collection_types.html#boost_bimap.the_tutorial.controlling_collection_types.examples.c1"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="keyword">for</span><span class="special">(</span> <span class="identifier">population_bimap</span><span class="special">::</span><span class="identifier">right_const_iterator</span>
<span class="identifier">i</span> <span class="special">=</span> <span class="identifier">pop</span><span class="special">.</span><span class="identifier">right</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">pop</span><span class="special">.</span><span class="identifier">right</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>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</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="string">" with "</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">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="special">}</span>
<span class="comment">// Second requirement</span>
<a class="co" name="boost_bimap.the_tutorial.controlling_collection_types.examples.c2" href="controlling_collection_types.html#boost_bimap.the_tutorial.controlling_collection_types.examples.c3"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Population of China: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pop</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="string">"China"</span><span class="special">)</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>
</pre>
<p>
</p>
<div class="calloutlist"><table border="0" summary="Callout list">
<tr>
<td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.controlling_collection_types.examples.c1"></a><a href="#boost_bimap.the_tutorial.controlling_collection_types.examples.c0"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
The right map view works like a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">multimap</span><span class="special">&lt;</span> <span class="keyword">long</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">std</span><span class="special">::</span><span class="identifier">greater</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="special">&gt;</span></code>,
We can iterate over it to print the results in the required order.
</p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.controlling_collection_types.examples.c3"></a><a href="#boost_bimap.the_tutorial.controlling_collection_types.examples.c2"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
<td valign="top" align="left"><p>
The left map view works like a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">unordered_map</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">long</span> <span class="special">&gt;</span></code>, given the name of the country
we can use it to search for the population in constant time
</p></td>
</tr>
</table></div>
<h6>
<a name="boost_bimap.the_tutorial.controlling_collection_types.examples.h1"></a>
<span class="phrase"><a name="boost_bimap.the_tutorial.controlling_collection_types.examples.repetitions_counter"></a></span><a class="link" href="controlling_collection_types.html#boost_bimap.the_tutorial.controlling_collection_types.examples.repetitions_counter">Repetitions
counter</a>
</h6>
<p>
We want to count the repetitions for each word in a text and print them
in order of appearance.
</p>
<p>
<a href="../../../../example/repetitions_counter.cpp" target="_top">Go to source code</a>
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span>
<span class="special">&lt;</span>
<span class="identifier">unordered_set_of</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;,</span>
<span class="identifier">list_of</span><span class="special">&lt;</span> <span class="identifier">counter</span> <span class="special">&gt;</span> <a class="co" name="boost_bimap.the_tutorial.controlling_collection_types.examples.c4" href="controlling_collection_types.html#boost_bimap.the_tutorial.controlling_collection_types.examples.c5"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>
<span class="special">&gt;</span> <span class="identifier">word_counter</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">tokenizer</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">char_separator</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">text_tokenizer</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">text</span><span class="special">=</span>
<span class="string">"Relations between data in the STL are represented with maps."</span>
<span class="string">"A map is a directed relation, by using it you are representing "</span>
<span class="string">"a mapping. In this directed relation, the first type is related to "</span>
<span class="string">"the second type but it is not true that the inverse relationship "</span>
<span class="string">"holds. This is useful in a lot of situations, but there are some "</span>
<span class="string">"relationships that are bidirectional by nature."</span><span class="special">;</span>
<span class="comment">// feed the text into the container</span>
<span class="identifier">word_counter</span> <span class="identifier">wc</span><span class="special">;</span>
<span class="identifier">text_tokenizer</span> <span class="identifier">tok</span><span class="special">(</span><span class="identifier">text</span><span class="special">,</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">char_separator</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;(</span><span class="string">" \t\n.,;:!?'\"-"</span><span class="special">));</span>
<span class="keyword">for</span><span class="special">(</span> <span class="identifier">text_tokenizer</span><span class="special">::</span><span class="identifier">const_iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">tok</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">it_end</span> <span class="special">=</span> <span class="identifier">tok</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span>
<span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">it_end</span> <span class="special">;</span> <span class="special">++</span><span class="identifier">it</span> <span class="special">)</span>
<span class="special">{</span>
<a class="co" name="boost_bimap.the_tutorial.controlling_collection_types.examples.c6" href="controlling_collection_types.html#boost_bimap.the_tutorial.controlling_collection_types.examples.c7"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a><span class="special">++</span> <span class="identifier">wc</span><span class="special">.</span><span class="identifier">left</span><span class="special">[*</span><span class="identifier">it</span><span class="special">];</span>
<span class="special">}</span>
<span class="comment">// list words with counters by order of appearance</span>
<a class="co" name="boost_bimap.the_tutorial.controlling_collection_types.examples.c8" href="controlling_collection_types.html#boost_bimap.the_tutorial.controlling_collection_types.examples.c9"><img src="../../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a><span class="keyword">for</span><span class="special">(</span> <span class="identifier">word_counter</span><span class="special">::</span><span class="identifier">right_const_iterator</span>
<span class="identifier">wit</span> <span class="special">=</span> <span class="identifier">wc</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">wit_end</span> <span class="special">=</span> <span class="identifier">wc</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span>
<span class="identifier">wit</span> <span class="special">!=</span> <span class="identifier">wit_end</span><span class="special">;</span> <span class="special">++</span><span class="identifier">wit</span> <span class="special">)</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">wit</span><span class="special">-&gt;</span><span class="identifier">second</span> <span class="special">&lt;&lt;</span> <span class="string">": "</span> <span class="special">&lt;&lt;</span> <span class="identifier">wit</span><span class="special">-&gt;</span><span class="identifier">first</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
</p>
<div class="calloutlist"><table border="0" summary="Callout list">
<tr>
<td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.controlling_collection_types.examples.c5"></a><a href="#boost_bimap.the_tutorial.controlling_collection_types.examples.c4"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
<code class="computeroutput"><span class="identifier">counter</span></code> is an integer
that is initialized in zero in the constructor
</p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.controlling_collection_types.examples.c7"></a><a href="#boost_bimap.the_tutorial.controlling_collection_types.examples.c6"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
<td valign="top" align="left"><p>
Because the right collection type is <code class="computeroutput"><span class="identifier">list_of</span></code>,
the right data is not used a key and can be modified in the same way
as with standard maps.
</p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.controlling_collection_types.examples.c9"></a><a href="#boost_bimap.the_tutorial.controlling_collection_types.examples.c8"><img src="../../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a> </p></td>
<td valign="top" align="left"><p>
When we insert the elements using the left map view, the element is
inserted at the end of the list.
</p></td>
</tr>
</table></div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2006-2012 Matias Capeletto<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="discovering_the_bimap_framework.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="the_collection_of_relations_type.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,446 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Differences with standard maps</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Bimap">
<link rel="up" href="../the_tutorial.html" title="The tutorial">
<link rel="prev" href="the_collection_of_relations_type.html" title="The collection of relations type">
<link rel="next" href="useful_functions.html" title="Useful functions">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="the_collection_of_relations_type.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="useful_functions.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_bimap.the_tutorial.differences_with_standard_maps"></a><a class="link" href="differences_with_standard_maps.html" title="Differences with standard maps">Differences
with standard maps</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="differences_with_standard_maps.html#boost_bimap.the_tutorial.differences_with_standard_maps.insertion">Insertion</a></span></dt>
<dt><span class="section"><a href="differences_with_standard_maps.html#boost_bimap.the_tutorial.differences_with_standard_maps.iterator__value_type">iterator::value_type</a></span></dt>
<dt><span class="section"><a href="differences_with_standard_maps.html#boost_bimap.the_tutorial.differences_with_standard_maps.operator_____and_at__">operator[]
and at()</a></span></dt>
<dt><span class="section"><a href="differences_with_standard_maps.html#boost_bimap.the_tutorial.differences_with_standard_maps.complexity_of_operations">Complexity
of operations</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.differences_with_standard_maps.insertion"></a><a class="link" href="differences_with_standard_maps.html#boost_bimap.the_tutorial.differences_with_standard_maps.insertion" title="Insertion">Insertion</a>
</h4></div></div></div>
<p>
Remember that a map can be interpreted as a relation between two collections.
In bimaps we have the freedom to change both collection types, imposing
constrains in each of them. Some insertions that we give for granted to
success in standard maps fails with bimaps. For example:
</p>
<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>
<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="number">1</span><span class="special">,</span><span class="string">"orange"</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">insert</span><span class="special">(</span><span class="number">2</span><span class="special">,</span><span class="string">"orange"</span><span class="special">);</span> <span class="comment">// No effect! returns make_pair(iter,false)</span>
</pre>
<p>
The insertion will only succeed if it is allowed by all views of the <code class="computeroutput"><span class="identifier">bimap</span></code>. In the next snippet we define
the right collection as a multiset, when we try to insert the same two
elements the second insertion is allowed by the left map view because both
values are different and it is allowed by the right map view because it
is a non-unique collection type.
</p>
<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">multiset_of</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">bm</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">insert</span><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="string">"orange"</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">insert</span><span class="special">(</span><span class="number">2</span><span class="special">,</span><span class="string">"orange"</span><span class="special">);</span> <span class="comment">// Insertion succeed!</span>
</pre>
<p>
If we use a custom collection of relation type, the insertion has to be
allowed by it too.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.differences_with_standard_maps.iterator__value_type"></a><a class="link" href="differences_with_standard_maps.html#boost_bimap.the_tutorial.differences_with_standard_maps.iterator__value_type" title="iterator::value_type">iterator::value_type</a>
</h4></div></div></div>
<p>
The relations stored in the Bimap will not be in most cases modifiable
directly by iterators because both sides are used as keys of <span class="emphasis"><em>key-based</em></span>
sets. When a <code class="computeroutput"><span class="identifier">bimap</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span><span class="identifier">B</span><span class="special">&gt;</span></code> left view iterator is dereferenced
the return type 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">A</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">B</span> <span class="special">&gt;</span></code>.
However there are some collection types that are not <span class="emphasis"><em>key_based</em></span>,
for example list_of. If a Bimap uses one of these collection types there
is no problem with modifying the data of that side. The following code
is valid:
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">list_of</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
<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">relation</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>
<span class="special">...</span>
<span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="number">1</span><span class="special">)-&gt;</span><span class="identifier">second</span> <span class="special">=</span> <span class="string">"1"</span><span class="special">;</span> <span class="comment">// Valid</span>
</pre>
<p>
In this case, when the iterator is dereferenced the return type 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="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>.
</p>
<p>
The following table shows the constness of the dereferenced data of each
collection type of:
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Side collection type
</p>
</th>
<th>
<p>
Dereferenced data
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">set_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>constant</em></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">multiset_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>constant</em></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">unordered_set_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>constant</em></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">unordered_multiset_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>constant</em></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">list_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>mutable</em></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">vector_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>mutable</em></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">unconstrained_set_of</span></code>
</p>
</td>
<td>
<p>
<span class="emphasis"><em>mutable</em></span>
</p>
</td>
</tr>
</tbody>
</table></div>
<p>
Here are some examples. When dereferenced the iterators returns a type
that is <span class="emphasis"><em>signature-compatible</em></span> with these types.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Bimap type
</p>
</th>
<th>
<p>
Signature-compatible types
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">bimap</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span><span class="identifier">B</span><span class="special">&gt;</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">iterator</span> </code> <span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">relation</span><span class="special">&lt;</span><span class="keyword">const</span>
<span class="identifier">A</span><span class="special">,</span><span class="keyword">const</span> <span class="identifier">B</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">left_iterator</span> </code>
<span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">const</span>
<span class="identifier">A</span><span class="special">,</span><span class="keyword">const</span> <span class="identifier">B</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">right_iterator</span></code>
<span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">const</span>
<span class="identifier">B</span><span class="special">,</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&gt;</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">bimap</span><span class="special">&lt;</span><span class="identifier">multiset_of</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;,</span><span class="identifier">unordered_set_of</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span>
<span class="special">&gt;</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">iterator</span> </code> <span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">relation</span><span class="special">&lt;</span><span class="keyword">const</span>
<span class="identifier">A</span><span class="special">,</span><span class="keyword">const</span> <span class="identifier">B</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">left_iterator</span> </code>
<span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">const</span>
<span class="identifier">A</span><span class="special">,</span><span class="keyword">const</span> <span class="identifier">B</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">right_iterator</span></code>
<span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">const</span>
<span class="identifier">B</span><span class="special">,</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&gt;</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">bimap</span><span class="special">&lt;</span><span class="identifier">set_of</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;,</span><span class="identifier">list_of</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span>
<span class="special">&gt;</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">iterator</span> </code> <span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">relation</span><span class="special">&lt;</span><span class="keyword">const</span>
<span class="identifier">A</span><span class="special">,</span><span class="identifier">B</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">left_iterator</span> </code>
<span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">const</span>
<span class="identifier">A</span><span class="special">,</span><span class="identifier">B</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">right_iterator</span></code>
<span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">,</span><span class="keyword">const</span>
<span class="identifier">A</span><span class="special">&gt;</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">bimap</span><span class="special">&lt;</span><span class="identifier">vector_of</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;,</span><span class="identifier">set_of</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span>
<span class="special">&gt;</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">iterator</span> </code> <span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">relation</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span><span class="keyword">const</span>
<span class="identifier">B</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">left_iterator</span> </code>
<span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span><span class="keyword">const</span>
<span class="identifier">B</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">right_iterator</span></code>
<span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">const</span>
<span class="identifier">B</span><span class="special">,</span><span class="identifier">A</span><span class="special">&gt;</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">bimap</span><span class="special">&lt;</span><span class="identifier">list_of</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;,</span><span class="identifier">unconstrained_set_of</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span>
<span class="special">&gt;</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">iterator</span> </code> <span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">relation</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span><span class="identifier">B</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">left_iterator</span> </code>
<span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span><span class="identifier">B</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">right_iterator</span></code>
<span class="bold"><strong>-&gt;</strong></span> <code class="computeroutput"><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">,</span><span class="identifier">A</span><span class="special">&gt;</span></code>
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.differences_with_standard_maps.operator_____and_at__"></a><a class="link" href="differences_with_standard_maps.html#boost_bimap.the_tutorial.differences_with_standard_maps.operator_____and_at__" title="operator[] and at()">operator[]
and at()</a>
</h4></div></div></div>
<p>
<code class="computeroutput"><span class="identifier">set_of</span></code> and <code class="computeroutput"><span class="identifier">unordered_set_of</span></code> map views overload
<code class="computeroutput"><span class="keyword">operator</span><span class="special">[]</span></code>
to retrieve the associated data of a given key only when the other collection
type is a mutable one. In these cases it works in the same way as the standard.
</p>
<pre class="programlisting"><span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">unorderd_set_of</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;,</span> <span class="identifier">list_of</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">bm</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="string">"one"</span><span class="special">]</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="comment">// Ok</span>
</pre>
<p>
The standard defines an access function for <code class="computeroutput"><span class="identifier">map</span></code>
and <code class="computeroutput"><span class="identifier">unordered_map</span></code>:
</p>
<pre class="programlisting"><span class="keyword">const</span> <span class="identifier">data_type</span> <span class="special">&amp;</span> <span class="identifier">at</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">key_type</span> <span class="special">&amp;</span> <span class="identifier">k</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span>
<span class="identifier">data_type</span> <span class="special">&amp;</span> <span class="identifier">at</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">key_type</span> <span class="special">&amp;</span> <span class="identifier">k</span><span class="special">);</span>
</pre>
<p>
These functions look for a key and returns the associated data value, but
throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">out_of_range</span></code> exception if the key is
not found.
</p>
<p>
In bimaps the constant version of these functions is given for <code class="computeroutput"><span class="identifier">set_of</span></code> and <code class="computeroutput"><span class="identifier">unorderd_set_of</span></code>
map views independently of the other collection type. The mutable version
is only provided when the other collection type is mutable.
</p>
<p>
The following examples shows the behaviour of <code class="computeroutput"><span class="identifier">at</span><span class="special">(</span><span class="identifier">key</span><span class="special">)</span></code>
</p>
<p>
<a href="../../../../example/at_function_examples.cpp" target="_top">Go to source code</a>
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">set_of</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;,</span> <span class="identifier">list_of</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
<span class="keyword">try</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">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> <span class="comment">// throws std::out_of_range</span>
<span class="special">}</span>
<span class="keyword">catch</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">out_of_range</span> <span class="special">&amp;</span> <span class="identifier">e</span> <span class="special">)</span> <span class="special">{}</span>
<span class="identifier">assert</span><span class="special">(</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">empty</span><span class="special">()</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="string">"one"</span><span class="special">]</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="comment">// Ok</span>
<span class="identifier">assert</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">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> <span class="comment">// Ok</span>
</pre>
<p>
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">multiset_of</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;,</span> <span class="identifier">unordered_set_of</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</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="number">1</span><span class="special">]</span> <span class="special">=</span> <span class="string">"one"</span><span class="special">;</span> <span class="comment">// compilation error</span>
<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="number">1</span><span class="special">,</span><span class="string">"one"</span><span class="special">)</span> <span class="special">);</span>
<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="number">1</span><span class="special">)</span> <span class="special">==</span> <span class="string">"one"</span> <span class="special">);</span> <span class="comment">// Ok</span>
<span class="keyword">try</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</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="number">2</span><span class="special">);</span> <span class="comment">// throws std::out_of_range</span>
<span class="special">}</span>
<span class="keyword">catch</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">out_of_range</span> <span class="special">&amp;</span> <span class="identifier">e</span> <span class="special">)</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="number">1</span><span class="special">)</span> <span class="special">=</span> <span class="string">"1"</span><span class="special">;</span> <span class="comment">// compilation error</span>
</pre>
<p>
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.differences_with_standard_maps.complexity_of_operations"></a><a class="link" href="differences_with_standard_maps.html#boost_bimap.the_tutorial.differences_with_standard_maps.complexity_of_operations" title="Complexity of operations">Complexity
of operations</a>
</h4></div></div></div>
<p>
The complexity of some operations is different in bimaps. Read <a class="link" href="../reference/bimap_reference.html#complexity_signature_explanation">the
reference</a> to find the complexity of each function.
</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2006-2012 Matias Capeletto<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="the_collection_of_relations_type.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="useful_functions.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,320 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Discovering the bimap framework</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Bimap">
<link rel="up" href="../the_tutorial.html" title="The tutorial">
<link rel="prev" href="../the_tutorial.html" title="The tutorial">
<link rel="next" href="controlling_collection_types.html" title="Controlling collection types">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="controlling_collection_types.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_bimap.the_tutorial.discovering_the_bimap_framework"></a><a class="link" href="discovering_the_bimap_framework.html" title="Discovering the bimap framework">Discovering
the bimap framework</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="discovering_the_bimap_framework.html#boost_bimap.the_tutorial.discovering_the_bimap_framework.interpreting_bidirectional_maps">Interpreting
bidirectional maps</a></span></dt>
<dt><span class="section"><a href="discovering_the_bimap_framework.html#boost_bimap.the_tutorial.discovering_the_bimap_framework.standard_mapping_framework">Standard
mapping framework</a></span></dt>
<dt><span class="section"><a href="discovering_the_bimap_framework.html#boost_bimap.the_tutorial.discovering_the_bimap_framework.bimap_mapping_framework">Bimap
mapping framework</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.discovering_the_bimap_framework.interpreting_bidirectional_maps"></a><a class="link" href="discovering_the_bimap_framework.html#boost_bimap.the_tutorial.discovering_the_bimap_framework.interpreting_bidirectional_maps" title="Interpreting bidirectional maps">Interpreting
bidirectional maps</a>
</h4></div></div></div>
<p>
One way to interpret bidirectional maps is as a function between two collections
of data, lets call them the left and the right collection. An element in
this bimap is a relation between an element from the left collection and
an element from the right collection. The types of both collections defines
the bimap behaviour. We can view the stored data from the left side, as
a mapping between keys from the left collection and data from the right
one, or from the right side, as a mapping between keys from the right collection
and data from the left collection.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.discovering_the_bimap_framework.standard_mapping_framework"></a><a class="link" href="discovering_the_bimap_framework.html#boost_bimap.the_tutorial.discovering_the_bimap_framework.standard_mapping_framework" title="Standard mapping framework">Standard
mapping framework</a>
</h4></div></div></div>
<p>
Relationships between data in the STL are represented by maps. A standard
map is a directed relation of keys from a left collection and data from
a right unconstrained collection. The following diagram shows the relationship
represented and the user's viewpoint.
</p>
<p>
<span class="inlinemediaobject"><img src="../../images/bimap/standard.mapping.framework.png" alt="standard.mapping.framework"></span>
</p>
<p>
The left collection type depends on the selected map type. For example
if the the map type is <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">multimap</span></code>
the collection type of X is a <code class="computeroutput"><span class="identifier">multiset_of</span></code>.
The following table shows the equivalent types for the std associative
containers.
</p>
<div class="table">
<a name="boost_bimap.the_tutorial.discovering_the_bimap_framework.standard_mapping_framework.t0"></a><p class="title"><b>Table&#160;1.1.&#160;std associative containers</b></p>
<div class="table-contents"><table class="table" summary="std associative containers">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
container
</p>
</th>
<th>
<p>
left collection type
</p>
</th>
<th>
<p>
right collection type
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">map</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">set_of</span></code>
</p>
</td>
<td>
<p>
no constraints
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">multimap</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">multiset_of</span></code>
</p>
</td>
<td>
<p>
no constraints
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">unordered_map</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">unordered_set_of</span></code>
</p>
</td>
<td>
<p>
no constraints
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">unordered_multimap</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">unordered_multiset_of</span></code>
</p>
</td>
<td>
<p>
no constraints
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.discovering_the_bimap_framework.bimap_mapping_framework"></a><a class="link" href="discovering_the_bimap_framework.html#boost_bimap.the_tutorial.discovering_the_bimap_framework.bimap_mapping_framework" title="Bimap mapping framework">Bimap
mapping framework</a>
</h4></div></div></div>
<p>
Boost.Bimap design is based on the STL, and extends the framework in a
natural way. The following diagram represents the new situation.
</p>
<p>
<span class="inlinemediaobject"><img src="../../images/bimap/extended.mapping.framework.png" alt="extended.mapping.framework"></span>
</p>
<p>
Notice that now the <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">maps</span></code>
are a particular case of a Boost.Bimap container, where you can view only
one side of the relationship and can control the constraints of only one
of the collections. Boost.Bimap allows the user to view the relationship
from three viewpoints. You can view it from one side, obtaining a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span></code> compatible container, or you can
work directly with the whole relation.
</p>
<p>
The next diagram shows the layout of the relation and pairs of a bimap.
It is the one from the <span class="emphasis"><em>one minute tutorial</em></span>
</p>
<p>
<span class="inlinemediaobject"><img src="../../images/bimap/relation.and.pair.png" alt="relation.and.pair"></span>
</p>
<p>
Bimap pairs are signature-compatible with standard pairs but are different
from them. As you will see in other sections they can be tagged with user
defined names and additional information can be attached to them. You can
convert from <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pairs</span></code> to bimap pairs directly but the
reverse conversion is not provided. This mean that you can insert elements
in a bimap using algorithms like <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span></code>
from containers <code class="computeroutput"><span class="identifier">like</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span></code>,
or use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span></code> to add new elements. However
it is best to use <code class="computeroutput"><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="identifier">f</span><span class="special">,</span><span class="identifier">s</span><span class="special">)</span> <span class="special">)</span></code> instead
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">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span><span class="identifier">s</span><span class="special">)</span> <span class="special">)</span></code> to avoid
an extra call to the copy constructor of each type.
</p>
<p>
The following code snippet shows the relation between a bimap and standard
maps.
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>
You have to used references to views, and not directly views object.
Views cannot be constructed as separate objects from the container they
belong to, so the following:
</p>
<pre class="programlisting"><span class="comment">// Wrong: we forgot the &amp; after bm_type::left_type</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_map</span> <span class="identifier">lm</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">;</span>
</pre>
<p>
does not compile, since it is trying to construct the view object <code class="computeroutput"><span class="identifier">lm</span></code>. This is a common source of errors
in user code.
</p>
</td></tr>
</table></div>
<p>
<a href="../../../../example/standard_map_comparison.cpp" target="_top">Go to source code</a>
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">Map</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">CompatibleKey</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">CompatibleData</span> <span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">use_it</span><span class="special">(</span> <span class="identifier">Map</span> <span class="special">&amp;</span> <span class="identifier">m</span><span class="special">,</span>
<span class="keyword">const</span> <span class="identifier">CompatibleKey</span> <span class="special">&amp;</span> <span class="identifier">key</span><span class="special">,</span>
<span class="keyword">const</span> <span class="identifier">CompatibleData</span> <span class="special">&amp;</span> <span class="identifier">data</span> <span class="special">)</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Map</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">value_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Map</span><span class="special">::</span><span class="identifier">const_iterator</span> <span class="identifier">const_iterator</span><span class="special">;</span>
<span class="identifier">m</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">value_type</span><span class="special">(</span><span class="identifier">key</span><span class="special">,</span><span class="identifier">data</span><span class="special">)</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">find</span><span class="special">(</span><span class="identifier">key</span><span class="special">);</span>
<span class="keyword">if</span><span class="special">(</span> <span class="identifier">iter</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="special">)</span>
<span class="special">{</span>
<span class="identifier">assert</span><span class="special">(</span> <span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">first</span> <span class="special">==</span> <span class="identifier">key</span> <span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span> <span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">second</span> <span class="special">==</span> <span class="identifier">data</span> <span class="special">);</span>
<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">;</span>
<span class="special">}</span>
<span class="identifier">m</span><span class="special">.</span><span class="identifier">erase</span><span class="special">(</span><span class="identifier">key</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">set_of</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;,</span> <span class="identifier">set_of</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">bimap_type</span><span class="special">;</span>
<span class="identifier">bimap_type</span> <span class="identifier">bm</span><span class="special">;</span>
<span class="comment">// Standard map</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">map</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">map_type</span><span class="special">;</span>
<span class="identifier">map_type</span> <span class="identifier">m</span><span class="special">;</span>
<span class="identifier">use_it</span><span class="special">(</span> <span class="identifier">m</span><span class="special">,</span> <span class="string">"one"</span><span class="special">,</span> <span class="number">1</span> <span class="special">);</span>
<span class="special">}</span>
<span class="comment">// Left map view</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="identifier">bimap_type</span><span class="special">::</span><span class="identifier">left_map</span> <span class="identifier">map_type</span><span class="special">;</span>
<span class="identifier">map_type</span> <span class="special">&amp;</span> <span class="identifier">m</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">use_it</span><span class="special">(</span> <span class="identifier">m</span><span class="special">,</span> <span class="string">"one"</span><span class="special">,</span> <span class="number">1</span> <span class="special">);</span>
<span class="special">}</span>
<span class="comment">// Reverse standard map</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <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> <span class="identifier">reverse_map_type</span><span class="special">;</span>
<span class="identifier">reverse_map_type</span> <span class="identifier">rm</span><span class="special">;</span>
<span class="identifier">use_it</span><span class="special">(</span> <span class="identifier">rm</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>
<span class="comment">// Right map view</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="identifier">bimap_type</span><span class="special">::</span><span class="identifier">right_map</span> <span class="identifier">reverse_map_type</span><span class="special">;</span>
<span class="identifier">reverse_map_type</span> <span class="special">&amp;</span> <span class="identifier">rm</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">use_it</span><span class="special">(</span> <span class="identifier">rm</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>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2006-2012 Matias Capeletto<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="controlling_collection_types.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,407 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>The collection of relations type</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Bimap">
<link rel="up" href="../the_tutorial.html" title="The tutorial">
<link rel="prev" href="controlling_collection_types.html" title="Controlling collection types">
<link rel="next" href="differences_with_standard_maps.html" title="Differences with standard maps">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="controlling_collection_types.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="differences_with_standard_maps.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_bimap.the_tutorial.the_collection_of_relations_type"></a><a class="link" href="the_collection_of_relations_type.html" title="The collection of relations type">The
collection of relations type</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="the_collection_of_relations_type.html#boost_bimap.the_tutorial.the_collection_of_relations_type.a_new_point_of_view">A
new point of view</a></span></dt>
<dt><span class="section"><a href="the_collection_of_relations_type.html#boost_bimap.the_tutorial.the_collection_of_relations_type.configuration_parameters">Configuration
parameters</a></span></dt>
<dt><span class="section"><a href="the_collection_of_relations_type.html#boost_bimap.the_tutorial.the_collection_of_relations_type.examples">Examples</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.the_collection_of_relations_type.a_new_point_of_view"></a><a class="link" href="the_collection_of_relations_type.html#boost_bimap.the_tutorial.the_collection_of_relations_type.a_new_point_of_view" title="A new point of view">A
new point of view</a>
</h4></div></div></div>
<p>
Being able to change the collection type of the bimap relation view is
another very important feature. Remember that this view allows the user
to see the container as a group of the stored relations. This view has
set semantics instead of map semantics.
</p>
<p>
<span class="inlinemediaobject"><img src="../../images/bimap/collection.type.of.relation.png" alt="collection.type.of.relation"></span>
</p>
<p>
By default, Boost.Bimap will base the collection type of the relation on
the type of the left collection. If the left collection type is a set,
then the collection type of the relation will be a set with the same order
as the left view.
</p>
<p>
In general, Boost.Bimap users will base the collection type of a relation
on the type of the collection on one of the two sides. However there are
times where it is useful to give this collection other constraints or simply
to order it differently. The user is allowed to choose between:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
left_based
</li>
<li class="listitem">
right_based
</li>
<li class="listitem">
set_of_relation&lt;&gt;
</li>
<li class="listitem">
multiset_of_relation&lt;&gt;
</li>
<li class="listitem">
unordered_set_of_relation&lt;&gt;
</li>
<li class="listitem">
unordered_multiset_of_relation&lt;&gt;
</li>
<li class="listitem">
list_of_relation
</li>
<li class="listitem">
vector_of_relation
</li>
<li class="listitem">
unconstrained_set_of_relation
</li>
</ul></div>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
The first two options and the last produce faster bimaps, so prefer these
where possible.
</p></td></tr>
</table></div>
<p>
<span class="inlinemediaobject"><img src="../../images/bimap/more.bimap.structures.png" alt="more.bimap.structures"></span>
</p>
<p>
The collection type of relation can be used to create powerful containers.
For example, if you need to maximize search speed, then the best bidirectional
map possible is one that relates elements from an <code class="computeroutput"><span class="identifier">unordered_set</span></code>
to another <code class="computeroutput"><span class="identifier">unordered_set</span></code>.
The problem is that this container cannot be iterated. If you need to know
the list of relations inside the container, you need another collection
type of relation. In this case, a <code class="computeroutput"><span class="identifier">list_of_relation</span></code>
is a good choice. The resulting container trades insertion and deletion
time against fast search capabilities and the possibility of bidirectional
iteration.
</p>
<p>
<a href="../../../../example/mighty_bimap.cpp" target="_top">Go to source code</a>
</p>
<p>
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
<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">bimap</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<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">list_of</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<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">unordered_set_of</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">english</span> <span class="special">{};</span>
<span class="keyword">struct</span> <span class="identifier">spanish</span> <span class="special">{};</span>
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
<span class="special">{</span>
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bimaps</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">bimap</span>
<span class="special">&lt;</span>
<span class="identifier">unordered_set_of</span><span class="special">&lt;</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">spanish</span> <span class="special">&gt;</span> <span class="special">&gt;,</span>
<span class="identifier">unordered_set_of</span><span class="special">&lt;</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">english</span> <span class="special">&gt;</span> <span class="special">&gt;,</span>
<span class="identifier">list_of_relation</span>
<span class="special">&gt;</span> <span class="identifier">translator</span><span class="special">;</span>
<span class="identifier">translator</span> <span class="identifier">trans</span><span class="special">;</span>
<span class="comment">// We have to use `push_back` because the collection of relations is</span>
<span class="comment">// a `list_of_relation`</span>
<span class="identifier">trans</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span> <span class="identifier">translator</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="string">"hola"</span> <span class="special">,</span><span class="string">"hello"</span> <span class="special">)</span> <span class="special">);</span>
<span class="identifier">trans</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span> <span class="identifier">translator</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="string">"adios"</span> <span class="special">,</span><span class="string">"goodbye"</span> <span class="special">)</span> <span class="special">);</span>
<span class="identifier">trans</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span> <span class="identifier">translator</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="string">"rosa"</span> <span class="special">,</span><span class="string">"rose"</span> <span class="special">)</span> <span class="special">);</span>
<span class="identifier">trans</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span> <span class="identifier">translator</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="string">"mesa"</span> <span class="special">,</span><span class="string">"table"</span> <span class="special">)</span> <span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"enter a word"</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>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">word</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">getline</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cin</span><span class="special">,</span><span class="identifier">word</span><span class="special">);</span>
<span class="comment">// Search the queried word on the from index (Spanish)</span>
<span class="identifier">translator</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">spanish</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span> <span class="identifier">is</span>
<span class="special">=</span> <span class="identifier">trans</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">spanish</span><span class="special">&gt;().</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">word</span><span class="special">);</span>
<span class="keyword">if</span><span class="special">(</span> <span class="identifier">is</span> <span class="special">!=</span> <span class="identifier">trans</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">spanish</span><span class="special">&gt;().</span><span class="identifier">end</span><span class="special">()</span> <span class="special">)</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">word</span> <span class="special">&lt;&lt;</span> <span class="string">" is said "</span>
<span class="special">&lt;&lt;</span> <span class="identifier">is</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">english</span><span class="special">&gt;()</span>
<span class="special">&lt;&lt;</span> <span class="string">" in English"</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>
<span class="special">}</span>
<span class="keyword">else</span>
<span class="special">{</span>
<span class="comment">// Word not found in Spanish, try our luck in English</span>
<span class="identifier">translator</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">english</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span> <span class="identifier">ie</span>
<span class="special">=</span> <span class="identifier">trans</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">english</span><span class="special">&gt;().</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">word</span><span class="special">);</span>
<span class="keyword">if</span><span class="special">(</span> <span class="identifier">ie</span> <span class="special">!=</span> <span class="identifier">trans</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">english</span><span class="special">&gt;().</span><span class="identifier">end</span><span class="special">()</span> <span class="special">)</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">word</span> <span class="special">&lt;&lt;</span> <span class="string">" is said "</span>
<span class="special">&lt;&lt;</span> <span class="identifier">ie</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">spanish</span><span class="special">&gt;()</span>
<span class="special">&lt;&lt;</span> <span class="string">" in Spanish"</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>
<span class="special">}</span>
<span class="keyword">else</span>
<span class="special">{</span>
<span class="comment">// Word not found, show the possible translations</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"No such word in the dictionary"</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>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"These are the possible translations"</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>
<span class="keyword">for</span><span class="special">(</span> <span class="identifier">translator</span><span class="special">::</span><span class="identifier">const_iterator</span>
<span class="identifier">i</span> <span class="special">=</span> <span class="identifier">trans</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span>
<span class="identifier">i_end</span> <span class="special">=</span> <span class="identifier">trans</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">i_end</span> <span class="special">;</span> <span class="special">++</span><span class="identifier">i</span> <span class="special">)</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">spanish</span><span class="special">&gt;()</span>
<span class="special">&lt;&lt;</span> <span class="string">" &lt;---&gt; "</span>
<span class="special">&lt;&lt;</span> <span class="identifier">i</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">english</span><span class="special">&gt;()</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>
<span class="special">}</span>
<span class="special">}</span>
<span class="special">}</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.the_collection_of_relations_type.configuration_parameters"></a><a class="link" href="the_collection_of_relations_type.html#boost_bimap.the_tutorial.the_collection_of_relations_type.configuration_parameters" title="Configuration parameters">Configuration
parameters</a>
</h4></div></div></div>
<p>
Each collection type of relation has different parameters to control its
behaviour. For example, in the <code class="computeroutput"><span class="identifier">set_of_relation</span></code>
specification, you can pass a Functor type that compares two types. All
of the parameters are exactly as in the standard library containers, except
for the type, which is set to the bimap relation and the allocator type.
To help users in the creation of each functor, the collection type of relation
templates takes an mpl lambda expression where the relation type will be
evaluated later. A placeholder named <code class="computeroutput"><span class="identifier">_relation</span></code>
is available to bimap users.
</p>
<p>
The following table lists the meaning of the parameters for each collection
type of relations.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
name
</p>
</th>
<th>
<p>
Additional Parameters
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">left_based</span></code>
</p>
</td>
<td>
<p>
Not a template.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">right_based</span></code>
</p>
</td>
<td>
<p>
Not a template.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">set_of_relation</span><span class="special">&lt;</span><span class="identifier">KeyComp</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">multiset_of_relation</span><span class="special">&lt;</span><span class="identifier">KeyComp</span><span class="special">&gt;</span></code>
</p>
</td>
<td>
<p>
<span class="bold"><strong>KeyComp </strong></span> is a Functor that compares
two types using less than. By default, the less-than operator
is <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span><span class="special">&lt;</span><span class="identifier">_relation</span><span class="special">&gt;</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">unordered_set_of_relation</span><span class="special">&lt;</span><span class="identifier">HashFunctor</span><span class="special">,</span><span class="identifier">EqualKey</span><span class="special">&gt;</span></code>
</p>
<p>
<code class="computeroutput"><span class="identifier">unordered_multiset_of_relation</span><span class="special">&lt;</span><span class="identifier">HashFunctor</span><span class="special">,</span><span class="identifier">EqualKey</span><span class="special">&gt;</span></code>
</p>
</td>
<td>
<p>
<span class="bold"><strong>HashFunctor </strong></span> converts the <code class="computeroutput"><span class="identifier">relation</span></code> into an <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code> value. By default it
is <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">hash</span><span class="special">&lt;</span><span class="identifier">_relation</span><span class="special">&gt;</span></code>.
</p>
<p>
<span class="bold"><strong>EqualKey </strong></span> is a Functor that
tests two relations for equality. By default, the equality operator
is <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">equal_to</span><span class="special">&lt;</span><span class="identifier">_relation</span><span class="special">&gt;</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">list_of_relation</span></code>
</p>
</td>
<td>
<p>
Not a template.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">vector_of_relation</span></code>
</p>
</td>
<td>
<p>
Not a template.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">unconstrained_set_of_relation</span></code>
</p>
</td>
<td>
<p>
Not a template.
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.the_collection_of_relations_type.examples"></a><a class="link" href="the_collection_of_relations_type.html#boost_bimap.the_tutorial.the_collection_of_relations_type.examples" title="Examples">Examples</a>
</h4></div></div></div>
<p>
Consider this example:
</p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">Rel</span> <span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">RelOrder</span>
<span class="special">{</span>
<span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">Rel</span> <span class="identifier">ra</span><span class="special">,</span> <span class="identifier">Rel</span> <span class="identifier">rb</span><span class="special">)</span> <span class="keyword">const</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="special">(</span><span class="identifier">ra</span><span class="special">.</span><span class="identifier">left</span><span class="special">+</span><span class="identifier">ra</span><span class="special">.</span><span class="identifier">right</span><span class="special">)</span> <span class="special">&lt;</span> <span class="special">(</span><span class="identifier">rb</span><span class="special">.</span><span class="identifier">left</span><span class="special">+</span><span class="identifier">rb</span><span class="special">.</span><span class="identifier">right</span><span class="special">);</span>
<span class="special">}</span>
<span class="special">};</span>
<span class="keyword">typedef</span> <span class="identifier">bimap</span>
<span class="special">&lt;</span>
<span class="identifier">multiset_of</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;,</span>
<span class="identifier">multiset_of</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;,</span>
<span class="identifier">set_of_relation</span><span class="special">&lt;</span> <span class="identifier">RelOrder</span><span class="special">&lt;</span><span class="identifier">_relation</span><span class="special">&gt;</span> <span class="special">&gt;</span>
<span class="special">&gt;</span> <span class="identifier">bimap_type</span><span class="special">;</span>
</pre>
<p>
Here the bimap relation view is ordered using the information of both sides.
This container will only allow unique relations because <code class="computeroutput"><span class="identifier">set_of_relation</span></code>
has been used but the elements in each side of the bimap can be repeated.
</p>
<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">name</span> <span class="special">{};</span>
<span class="keyword">struct</span> <span class="identifier">phone_number</span> <span class="special">{};</span>
<span class="keyword">typedef</span> <span class="identifier">bimap</span>
<span class="special">&lt;</span>
<span class="identifier">tagged</span><span class="special">&lt;</span> <span class="identifier">unordered_multiset_of</span><span class="special">&lt;</span> <span class="identifier">string</span> <span class="special">&gt;,</span> <span class="identifier">name</span> <span class="special">&gt;,</span>
<span class="identifier">tagged</span><span class="special">&lt;</span> <span class="identifier">unordered_set_of</span> <span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;,</span> <span class="identifier">phone_number</span> <span class="special">&gt;,</span>
<span class="identifier">set_of_relation</span><span class="special">&lt;&gt;</span>
<span class="special">&gt;</span> <span class="identifier">bimap_type</span><span class="special">;</span>
</pre>
<p>
In this other case the bimap will relate names to phone numbers. Names
can be repeated and phone numbers are unique. You can perform quick searches
by name or phone number and the container can be viewed ordered using the
relation view.
</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2006-2012 Matias Capeletto<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="controlling_collection_types.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="differences_with_standard_maps.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,145 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Unconstrained Sets</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Bimap">
<link rel="up" href="../the_tutorial.html" title="The tutorial">
<link rel="prev" href="bimaps_with_user_defined_names.html" title="Bimaps with user defined names">
<link rel="next" href="additional_information.html" title="Additional information">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="bimaps_with_user_defined_names.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="additional_information.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_bimap.the_tutorial.unconstrained_sets"></a><a class="link" href="unconstrained_sets.html" title="Unconstrained Sets">Unconstrained
Sets</a>
</h3></div></div></div>
<p>
Unconstrained sets allow the user to disable one of the views of a bimap.
Doing so makes the bimap operations execute faster and reduces memory consumption.
This completes the bidirectional mapping framework by including unidirectional
mappings as a particular case.
</p>
<p>
Unconstrained sets are useful for the following reasons:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
A bimap type has stronger guarantees than its standard equivalent, and
includes some useful functions (replace, modify) that the standard does
not have.
</li>
<li class="listitem">
You can view the mapping as a collection of relations.
</li>
<li class="listitem">
Using this kind of map makes the code very extensible. If, at any moment
of the development, the need to perform searches from the right side
of the mapping arises, the only necessary change is to the <code class="computeroutput"><span class="keyword">typedef</span></code>.
</li>
</ul></div>
<p>
Given this bimap instance,
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">unconstrained_set_of</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_map</span> <span class="identifier">map_type</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
<span class="identifier">map_type</span> <span class="special">&amp;</span> <span class="identifier">m</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">;</span>
</pre>
<p>
</p>
<p>
or this standard map one
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">map</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">map_type</span><span class="special">;</span>
<span class="identifier">map_type</span> <span class="identifier">m</span><span class="special">;</span>
</pre>
<p>
</p>
<p>
The following code snippet is valid
</p>
<p>
</p>
<pre class="programlisting"><span class="identifier">m</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>
<span class="identifier">assert</span><span class="special">(</span> <span class="identifier">m</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="string">"one"</span><span class="special">)</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="special">);</span>
<span class="keyword">for</span><span class="special">(</span> <span class="identifier">map_type</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">i</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">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>
<span class="special">{</span>
<a class="co" name="boost_bimap.the_tutorial.unconstrained_sets.c0" href="unconstrained_sets.html#boost_bimap.the_tutorial.unconstrained_sets.c1"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="special">++(</span><span class="identifier">i</span><span class="special">-&gt;</span><span class="identifier">second</span><span class="special">);</span>
<span class="special">}</span>
<span class="identifier">m</span><span class="special">.</span><span class="identifier">erase</span><span class="special">(</span><span class="string">"one"</span><span class="special">);</span>
</pre>
<p>
</p>
<div class="calloutlist"><table border="0" summary="Callout list"><tr>
<td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.unconstrained_sets.c1"></a><a href="#boost_bimap.the_tutorial.unconstrained_sets.c0"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
The right collection of the bimap is mutable so its elements can be modified
using iterators.
</p></td>
</tr></table></div>
<p>
But using a bimap has some benefits
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">map_type</span><span class="special">::</span><span class="identifier">const_iterator</span> <span class="identifier">const_iterator</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">const_iterator</span><span class="special">,</span><span class="identifier">const_iterator</span><span class="special">&gt;</span> <span class="identifier">const_range</span><span class="special">;</span>
<a class="co" name="boost_bimap.the_tutorial.unconstrained_sets.c2" href="unconstrained_sets.html#boost_bimap.the_tutorial.unconstrained_sets.c3"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">const_range</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">m</span><span class="special">.</span><span class="identifier">range</span><span class="special">(</span> <span class="string">"one"</span> <span class="special">&lt;=</span> <span class="identifier">_key</span><span class="special">,</span> <span class="identifier">_key</span> <span class="special">&lt;=</span> <span class="string">"two"</span> <span class="special">);</span>
<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">r</span><span class="special">.</span><span class="identifier">first</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">!=</span> <span class="identifier">r</span><span class="special">.</span><span class="identifier">second</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span> <span class="special">)</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</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="string">"--&gt;"</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>
<span class="special">}</span>
<span class="identifier">m</span><span class="special">.</span><span class="identifier">modify_key</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">_key</span> <span class="special">=</span> <span class="string">"1"</span> <span class="special">);</span>
</pre>
<p>
</p>
<div class="calloutlist"><table border="0" summary="Callout list"><tr>
<td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.unconstrained_sets.c3"></a><a href="#boost_bimap.the_tutorial.unconstrained_sets.c2"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
This range is a model of BidirectionalRange, read the docs of Boost.Range
for more information.
</p></td>
</tr></table></div>
<p>
<a href="../../../../example/unconstrained_collection.cpp" target="_top">Go to source code</a>
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2006-2012 Matias Capeletto<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="bimaps_with_user_defined_names.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="additional_information.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@@ -0,0 +1,368 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Useful functions</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Bimap">
<link rel="up" href="../the_tutorial.html" title="The tutorial">
<link rel="prev" href="differences_with_standard_maps.html" title="Differences with standard maps">
<link rel="next" href="bimaps_with_user_defined_names.html" title="Bimaps with user defined names">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="differences_with_standard_maps.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="bimaps_with_user_defined_names.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_bimap.the_tutorial.useful_functions"></a><a class="link" href="useful_functions.html" title="Useful functions">Useful functions</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.projection_of_iterators">Projection
of iterators</a></span></dt>
<dt><span class="section"><a href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.replace_and_modify">replace
and modify</a></span></dt>
<dt><span class="section"><a href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges">Retrieval
of ranges</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.useful_functions.projection_of_iterators"></a><a class="link" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.projection_of_iterators" title="Projection of iterators">Projection
of iterators</a>
</h4></div></div></div>
<p>
Iterators can be projected to any of the three views of the bimap. A bimap
provides three member functions to cope with projection: <code class="computeroutput"><span class="identifier">project_left</span></code>, <code class="computeroutput"><span class="identifier">project_right</span></code>
and <code class="computeroutput"><span class="identifier">project_up</span></code>, with projects
iterators to the <span class="emphasis"><em>left map view</em></span>, the <span class="emphasis"><em>right
map view</em></span> and the <span class="emphasis"><em>collection of relations view</em></span>.
These functions take any iterator from the bimap and retrieve an iterator
over the projected view pointing to the same element.
</p>
<p>
Here is an example that uses projection:
</p>
<p>
<a href="../../../../example/projection.cpp" target="_top">Go to source code</a>
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span><span class="identifier">multiset_of</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">greater</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
<span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="string">"John"</span> <span class="special">,</span><span class="number">34</span><span class="special">)</span> <span class="special">);</span>
<span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="string">"Peter"</span><span class="special">,</span><span class="number">24</span><span class="special">)</span> <span class="special">);</span>
<span class="identifier">bm</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span> <span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">(</span><span class="string">"Mary"</span> <span class="special">,</span><span class="number">12</span><span class="special">)</span> <span class="special">);</span>
<span class="comment">// Find the name of the next younger person after Peter</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_const_iterator</span> <span class="identifier">name_iter</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="string">"Peter"</span><span class="special">);</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">right_const_iterator</span> <span class="identifier">years_iter</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">project_right</span><span class="special">(</span><span class="identifier">name_iter</span><span class="special">);</span>
<span class="special">++</span><span class="identifier">years_iter</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The next younger person after Peter is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">years_iter</span><span class="special">-&gt;</span><span class="identifier">second</span><span class="special">;</span>
</pre>
<p>
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.useful_functions.replace_and_modify"></a><a class="link" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.replace_and_modify" title="replace and modify">replace
and modify</a>
</h4></div></div></div>
<p>
These functions are members of the views of a bimap that are not founded
in their standard counterparts.
</p>
<p>
The <code class="computeroutput"><span class="identifier">replace</span></code> family member
functions performs in-place replacement of a given element as the following
example shows:
</p>
<p>
<a href="../../../../example/tutorial_modify_and_replace.cpp" target="_top">Go to source
code</a>
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
<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>
<span class="comment">// Replace (1,"one") with (1,"1") using the right map view</span>
<span class="special">{</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">right_iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="string">"one"</span><span class="special">);</span>
<span class="keyword">bool</span> <span class="identifier">successful_replace</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">replace_key</span><span class="special">(</span> <span class="identifier">it</span><span class="special">,</span> <span class="string">"1"</span> <span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span> <span class="identifier">successful_replace</span> <span class="special">);</span>
<span class="special">}</span>
<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>
<span class="comment">// Fail to replace (1,"1") with (1,"two") using the left map view</span>
<span class="special">{</span>
<span class="identifier">assert</span><span class="special">(</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">2</span> <span class="special">);</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="number">1</span><span class="special">);</span>
<span class="keyword">bool</span> <span class="identifier">successful_replace</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">replace_data</span><span class="special">(</span> <span class="identifier">it</span><span class="special">,</span> <span class="string">"two"</span> <span class="special">);</span>
<a class="co" name="boost_bimap.the_tutorial.useful_functions.replace_and_modify.c0" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.replace_and_modify.c1"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">assert</span><span class="special">(</span> <span class="special">!</span> <span class="identifier">successful_replace</span> <span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">2</span> <span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
</p>
<div class="calloutlist"><table border="0" summary="Callout list"><tr>
<td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.useful_functions.replace_and_modify.c1"></a><a href="#boost_bimap.the_tutorial.useful_functions.replace_and_modify.c0"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
<code class="computeroutput"><span class="identifier">it</span></code> is still valid here,
and the bimap was left unchanged
</p></td>
</tr></table></div>
<p>
<code class="computeroutput"><span class="identifier">replace</span></code> functions performs
this substitution in such a manner that:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
The complexity is constant time if the changed element retains its
original order with respect to all views; it is logarithmic otherwise.
</li>
<li class="listitem">
Iterator and reference validity are preserved.
</li>
<li class="listitem">
The operation is strongly exception-safe, i.e. the <code class="computeroutput"><span class="identifier">bimap</span></code>
remains unchanged if some exception (originated by the system or the
user's data types) is thrown.
</li>
</ul></div>
<p>
<code class="computeroutput"><span class="identifier">replace</span></code> functions are powerful
operations not provided by standard STL containers, and one that is specially
handy when strong exception-safety is required.
</p>
<p>
The observant reader might have noticed that the convenience of replace
comes at a cost: namely the whole element has to be copied <span class="emphasis"><em>twice</em></span>
to do the updating (when retrieving it and inside <code class="computeroutput"><span class="identifier">replace</span></code>).
If elements are expensive to copy, this may be quite a computational cost
for the modification of just a tiny part of the object. To cope with this
situation, Boost.Bimap provides an alternative updating mechanism: <code class="computeroutput"><span class="identifier">modify</span></code> functions.
</p>
<p>
<code class="computeroutput"><span class="identifier">modify</span></code> functions accepts
a functor (or pointer to function) taking a reference to the data to be
changed, thus eliminating the need for spurious copies. Like <code class="computeroutput"><span class="identifier">replace</span></code> functions, <code class="computeroutput"><span class="identifier">modify</span></code>
functions does preserve the internal orderings of all the indices of the
<code class="computeroutput"><span class="identifier">bimap</span></code>. However, the semantics
of modify functions are not entirely equivalent to replace functions. Consider
what happens if a collision occurs as a result of modifying the element,
i.e. the modified element clashes with another with respect to some unique
view. In the case of <code class="computeroutput"><span class="identifier">replace</span></code>
functions, the original value is kept and the method returns without altering
the container, but <code class="computeroutput"><span class="identifier">modify</span></code>
functions cannot afford such an approach, since the modifying functor leaves
no trace of the previous value of the element. Integrity constraints thus
lead to the following policy: when a collision happens in the process of
calling a modify functions, the element is erased and the method returns
false. This difference in behavior between <code class="computeroutput"><span class="identifier">replace</span></code>
and <code class="computeroutput"><span class="identifier">modify</span></code> functions has
to be considered by the programmer on a case-by-case basis.
</p>
<p>
Boost.Bimap defines new placeholders named <code class="computeroutput"><span class="identifier">_key</span></code>
and <code class="computeroutput"><span class="identifier">_data</span></code> to allow a sounder
solution. You have to include <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bimap</span><span class="special">/</span><span class="identifier">support</span><span class="special">/</span><span class="identifier">lambda</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
to use them.
</p>
<p>
<a href="../../../../example/tutorial_modify_and_replace.cpp" target="_top">Go to source
code</a>
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
<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>
<span class="comment">// Modify (1,"one") to (1,"1") using the right map view</span>
<span class="special">{</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">right_iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="string">"one"</span><span class="special">);</span>
<span class="keyword">bool</span> <span class="identifier">successful_modify</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">modify_key</span><span class="special">(</span> <span class="identifier">it</span> <span class="special">,</span> <span class="identifier">_key</span> <span class="special">=</span> <span class="string">"1"</span> <span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span> <span class="identifier">successful_modify</span> <span class="special">);</span>
<span class="special">}</span>
<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>
<span class="comment">// Fail to modify (1,"1") to (1,"two") using the left map view</span>
<span class="special">{</span>
<span class="identifier">assert</span><span class="special">(</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">2</span> <span class="special">);</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="number">1</span><span class="special">);</span>
<span class="keyword">bool</span> <span class="identifier">successful_modify</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">modify_data</span><span class="special">(</span> <span class="identifier">it</span><span class="special">,</span> <span class="identifier">_data</span> <span class="special">=</span> <span class="string">"two"</span> <span class="special">);</span>
<a class="co" name="boost_bimap.the_tutorial.useful_functions.replace_and_modify.c2" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.replace_and_modify.c3"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">assert</span><span class="special">(</span> <span class="special">!</span> <span class="identifier">successful_modify</span> <span class="special">);</span>
<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>
<span class="special">}</span>
</pre>
<p>
</p>
<div class="calloutlist"><table border="0" summary="Callout list"><tr>
<td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.useful_functions.replace_and_modify.c3"></a><a href="#boost_bimap.the_tutorial.useful_functions.replace_and_modify.c2"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
<code class="computeroutput"><span class="identifier">it</span></code> is not longer valid
and <code class="computeroutput"><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="string">"1"</span><span class="special">)</span></code> is removed from the bimap
</p></td>
</tr></table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges"></a><a class="link" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges" title="Retrieval of ranges">Retrieval
of ranges</a>
</h4></div></div></div>
<p>
Standard <code class="computeroutput"><span class="identifier">lower_bound</span></code> and
<code class="computeroutput"><span class="identifier">upper_bound</span></code> functions can
be used to lookup for all the elements in a given range.
</p>
<p>
Suppose we want to retrieve the elements from a <code class="computeroutput"><span class="identifier">bimap</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span></code> where the left value is in the range
<code class="computeroutput"><span class="special">[</span><span class="number">20</span><span class="special">,</span><span class="number">50</span><span class="special">]</span></code>
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
<span class="comment">// ...</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span> <span class="identifier">iter_first</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">lower_bound</span><span class="special">(</span><span class="number">20</span><span class="special">);</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span> <span class="identifier">iter_second</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">upper_bound</span><span class="special">(</span><span class="number">50</span><span class="special">);</span>
<span class="comment">// range [iter_first,iter_second) contains the elements in [20,50]</span>
</pre>
<p>
</p>
<p>
Subtle changes to the code are required when strict inequalities are considered.
To retrieve the elements greater than 20 and less than 50, the code has
to be rewritten as
</p>
<p>
</p>
<pre class="programlisting"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span> <span class="identifier">iter_first</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">upper_bound</span><span class="special">(</span><span class="number">20</span><span class="special">);</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span> <span class="identifier">iter_second</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">lower_bound</span><span class="special">(</span><span class="number">50</span><span class="special">);</span>
<span class="comment">// range [iter_first,iter_second) contains the elements in (20,50)</span>
</pre>
<p>
</p>
<p>
To add to this complexity, the careful programmer has to take into account
that the lower and upper bounds of the interval searched be compatible:
for instance, if the lower bound is 50 and the upper bound is 20, the iterators
<code class="computeroutput"><span class="identifier">iter_first</span></code> and <code class="computeroutput"><span class="identifier">iter_second</span></code> produced by the code above
will be in reverse order, with possibly catastrophic results if a traversal
from <code class="computeroutput"><span class="identifier">iter_first</span></code> to <code class="computeroutput"><span class="identifier">iter_second</span></code> is tried. All these details
make range searching a tedious and error prone task.
</p>
<p>
The range member function, often in combination with lambda expressions,
can greatly help alleviate this situation:
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>
<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>
<span class="comment">// ...</span>
<a class="co" name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c0" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c1"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_range_type</span> <span class="identifier">r</span><span class="special">;</span>
<a class="co" name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c2" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c3"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a><span class="identifier">r</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">range</span><span class="special">(</span> <span class="number">20</span> <span class="special">&lt;=</span> <span class="identifier">_key</span><span class="special">,</span> <span class="identifier">_key</span> <span class="special">&lt;=</span> <span class="number">50</span> <span class="special">);</span> <span class="comment">// [20,50]</span>
<span class="identifier">r</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">range</span><span class="special">(</span> <span class="number">20</span> <span class="special">&lt;</span> <span class="identifier">_key</span><span class="special">,</span> <span class="identifier">_key</span> <span class="special">&lt;</span> <span class="number">50</span> <span class="special">);</span> <span class="comment">// (20,50)</span>
<span class="identifier">r</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">range</span><span class="special">(</span> <span class="number">20</span> <span class="special">&lt;=</span> <span class="identifier">_key</span><span class="special">,</span> <span class="identifier">_key</span> <span class="special">&lt;</span> <span class="number">50</span> <span class="special">);</span> <span class="comment">// [20,50)</span>
</pre>
<p>
</p>
<div class="calloutlist"><table border="0" summary="Callout list">
<tr>
<td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c1"></a><a href="#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c0"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
<code class="computeroutput"><span class="identifier">range_type</span></code> is a handy
typedef equal to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">iterator</span><span class="special">,</span><span class="identifier">iterator</span><span class="special">&gt;</span></code>. <code class="computeroutput"><span class="identifier">const_range_type</span></code>
is provided too, and it is equal to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">const_iterator</span><span class="special">,</span><span class="identifier">const_iterator</span><span class="special">&gt;</span></code>
</p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c3"></a><a href="#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c2"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
<td valign="top" align="left"><p>
_key is a Boost.Lambda placeholder. To use it you have to include
<code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bimap</span><span class="special">/</span><span class="identifier">support</span><span class="special">/</span><span class="identifier">lambda</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
</p></td>
</tr>
</table></div>
<p>
<code class="computeroutput"><span class="identifier">range</span></code> simply accepts predicates
specifying the lower and upper bounds of the interval searched. Please
consult the reference for a detailed explanation of the permissible predicates
passed to range.
</p>
<p>
One or both bounds can be omitted with the special unbounded marker:
</p>
<p>
</p>
<pre class="programlisting"><span class="identifier">r</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">range</span><span class="special">(</span> <span class="number">20</span> <span class="special">&lt;=</span> <span class="identifier">_key</span><span class="special">,</span> <span class="identifier">unbounded</span> <span class="special">);</span> <span class="comment">// [20,inf)</span>
<span class="identifier">r</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">range</span><span class="special">(</span> <span class="identifier">unbounded</span> <span class="special">,</span> <span class="identifier">_key</span> <span class="special">&lt;</span> <span class="number">50</span> <span class="special">);</span> <span class="comment">// (-inf,50)</span>
<a class="co" name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c4" href="useful_functions.html#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c5"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">r</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">range</span><span class="special">(</span> <span class="identifier">unbounded</span> <span class="special">,</span> <span class="identifier">unbounded</span> <span class="special">);</span> <span class="comment">// (-inf,inf)</span>
</pre>
<p>
</p>
<div class="calloutlist"><table border="0" summary="Callout list"><tr>
<td width="5%" valign="top" align="left"><p><a name="boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c5"></a><a href="#boost_bimap.the_tutorial.useful_functions.retrieval_of_ranges.c4"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
This is equivalent to std::make_pair(s.begin(),s.end())
</p></td>
</tr></table></div>
<p>
<a href="../../../../example/tutorial_range.cpp" target="_top">Go to source code</a>
</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2006-2012 Matias Capeletto<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="differences_with_standard_maps.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="bimaps_with_user_defined_names.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>