URL
https://opencores.org/ocsvn/scarts/scarts/trunk
Subversion Repositories scarts
[/] [scarts/] [trunk/] [toolchain/] [scarts-gcc/] [gcc-4.1.1/] [libstdc++-v3/] [docs/] [html/] [ext/] [pb_assoc/] [mmap_value_utils.html] - Rev 20
Compare with Previous | Blame | View Log
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>Multimap Value-Type Utilities</TITLE>
<META NAME="Generator" content="Microsoft Visual Studio .NET 7.1">
</HEAD>
<BODY>
<H1>Multimap Value-Type Utilities</H1>
<p>
In <tt>pb_assoc</tt>, associative containers have a unique-key design.
Multimaps, consequently are maps of sets, <i>e.g.</i>,
a <a href = "cc_ht_multimap.html"><tt>cc_ht_multimap</a><<b>int</b>, <b>char</b>></tt>
object maps <tt><b>int</b></tt>s to sets of <tt><b>char</b></tt>s.
It is often convenient to perform
value-type operations on multimaps, <i>e.g.</i>, in this case, to find a specific
<tt>std::pair<<b>int</b>, <b>char</b>></tt> object (say, <tt>std::make_pair(2, 'b')</tt>)
in a multimap object. These types of operations involve typically two steps: in the
first step, some operation is performed on the multimap object itself, and in the second
step, some operation is performed on the multimap's pertinent set object.
(This is true for the STL's multimaps as well, except that the "set" is an implicit
list.)
</p>
<p>
Coding these two-step operations is repetitious and error prone.
<tt>pb_assoc</tt> containers already maintain the invariant that they support
a value-type method for any mapped-value-type method they support
(hence any multimap of the above type supporsts a method for inserting
<tt>std::make_pair(2, 'b')</tt>). Following are some utility functions for
other common operations.
</p>
<pre>
<b>template</b><
<b>class</b> MMap_Cntnr>
<b>inline</b> std::pair<
<b>typename</b> MMap_Cntnr::mapped_data_type::find_iterator,
<b>bool</b>>
mmap_value_find
(<b>const</b> MMap_Cntnr &r_mmap_cntnr,
<b>typename</b> MMap_Cntnr::const_reference r_val);
</pre>
<p>
Finds the (const reference to a) value-type
<font color = "#666666"><tt>r_val</tt></font> in
the multimap object
<font color = "#666666"><tt>r_mmap_cntnr</tt></font>.
</p>
<p>
It
returns a pair whose first entry is a find-type iterator
of the multimap's set type, and whose second entry is a boolean
indicating whether the value type was found (only in this
case is the first entry in the pair valid).
</p>
<pre>
<b>template</b><
<b>class</b> MMap_Cntnr<
<b>inline</b> <b>typename</b> MMap_Cntnr::size_type
mmap_value_erase
(MMap_Cntnr &r_mmap_cntnr,
<b>typename</b> MMap_Cntnr::const_reference r_val,
<b>bool</b> erase_entry_if_last);
</pre>
<p>
Transactionally erases the (const reference to the) value-type
<font color = "#666666"><tt>r_val</tt></font> from
the multimap object
<font color = "#666666"><tt>r_mmap_cntnr</tt></font>, and
erases the mapped value type
with
<font color = "#666666"><tt>r_val</tt></font>'s key
if there are no more value types with this given key
and
<font color = "#666666"><tt>erase_entry_if_last</tt></font> <tt>= <b>true</b></tt>.
<p>
</p>
It
returns 1 if a value type was actually erased, or 0 otherwise.
</p>
<pre>
<b>template</b><
<b>class</b> MMap_Cntnr>
<b>inline</b> std::pair<
<b>typename</b> MMap_Cntnr::mapped_data_type::find_iterator,
<b>bool</b>>
mmap_value_replace
(MMap_Cntnr &r_mmap_cntnr,
<b>typename</b> MMap_Cntnr::const_reference r_val,
<b>typename</b> MMap_Cntnr::const_data_reference r_data);
</pre>
<p>
Transactionally erases
<font color = "#666666"><tt>r_val</tt></font>
from
<font color = "#666666"><tt>r_mmap_cntnr</tt></font>
(if it such a value type exists) and
inserts instead a value type whose key is
<font color = "#666666"><tt>r_val</tt></font><tt>.first</tt>
and whose data is
<font color = "#666666"><tt>r_data</tt></font>.
</p>
<p>
<p>
It
returns a pair whose first entry is a find-type iterator
of the multimap's set type, and whose second entry is a boolean
indicating whether the new value type was inserted
(it might have
existed previously).
</p>
<p>
(If the multimap type or its set type do not guarantee exception free
erases, <tt>mmap_value_erase</tt> and <tt>mmap_value_replace</tt> will
invalidate pointers, references, and iterators).
</p>
</BODY>
</HTML>