| 1 |
20 |
jlechner |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
| 2 |
|
|
<HTML>
|
| 3 |
|
|
<HEAD>
|
| 4 |
|
|
<TITLE>Multimap Value-Type Utilities</TITLE>
|
| 5 |
|
|
<META NAME="Generator" content="Microsoft Visual Studio .NET 7.1">
|
| 6 |
|
|
</HEAD>
|
| 7 |
|
|
<BODY>
|
| 8 |
|
|
|
| 9 |
|
|
<H1>Multimap Value-Type Utilities</H1>
|
| 10 |
|
|
|
| 11 |
|
|
<p>
|
| 12 |
|
|
In <tt>pb_assoc</tt>, associative containers have a unique-key design.
|
| 13 |
|
|
Multimaps, consequently are maps of sets, <i>e.g.</i>,
|
| 14 |
|
|
a <a href = "cc_ht_multimap.html"><tt>cc_ht_multimap</a><<b>int</b>, <b>char</b>></tt>
|
| 15 |
|
|
object maps <tt><b>int</b></tt>s to sets of <tt><b>char</b></tt>s.
|
| 16 |
|
|
It is often convenient to perform
|
| 17 |
|
|
value-type operations on multimaps, <i>e.g.</i>, in this case, to find a specific
|
| 18 |
|
|
<tt>std::pair<<b>int</b>, <b>char</b>></tt> object (say, <tt>std::make_pair(2, 'b')</tt>)
|
| 19 |
|
|
in a multimap object. These types of operations involve typically two steps: in the
|
| 20 |
|
|
first step, some operation is performed on the multimap object itself, and in the second
|
| 21 |
|
|
step, some operation is performed on the multimap's pertinent set object.
|
| 22 |
|
|
(This is true for the STL's multimaps as well, except that the "set" is an implicit
|
| 23 |
|
|
list.)
|
| 24 |
|
|
</p>
|
| 25 |
|
|
|
| 26 |
|
|
<p>
|
| 27 |
|
|
Coding these two-step operations is repetitious and error prone.
|
| 28 |
|
|
<tt>pb_assoc</tt> containers already maintain the invariant that they support
|
| 29 |
|
|
a value-type method for any mapped-value-type method they support
|
| 30 |
|
|
(hence any multimap of the above type supporsts a method for inserting
|
| 31 |
|
|
<tt>std::make_pair(2, 'b')</tt>). Following are some utility functions for
|
| 32 |
|
|
other common operations.
|
| 33 |
|
|
</p>
|
| 34 |
|
|
|
| 35 |
|
|
|
| 36 |
|
|
<pre>
|
| 37 |
|
|
<b>template</b><
|
| 38 |
|
|
<b>class</b> MMap_Cntnr>
|
| 39 |
|
|
<b>inline</b> std::pair<
|
| 40 |
|
|
<b>typename</b> MMap_Cntnr::mapped_data_type::find_iterator,
|
| 41 |
|
|
<b>bool</b>>
|
| 42 |
|
|
mmap_value_find
|
| 43 |
|
|
(<b>const</b> MMap_Cntnr &r_mmap_cntnr,
|
| 44 |
|
|
<b>typename</b> MMap_Cntnr::const_reference r_val);
|
| 45 |
|
|
</pre>
|
| 46 |
|
|
|
| 47 |
|
|
<p>
|
| 48 |
|
|
Finds the (const reference to a) value-type
|
| 49 |
|
|
<font color = "#666666"><tt>r_val</tt></font> in
|
| 50 |
|
|
the multimap object
|
| 51 |
|
|
<font color = "#666666"><tt>r_mmap_cntnr</tt></font>.
|
| 52 |
|
|
</p>
|
| 53 |
|
|
<p>
|
| 54 |
|
|
It
|
| 55 |
|
|
returns a pair whose first entry is a find-type iterator
|
| 56 |
|
|
of the multimap's set type, and whose second entry is a boolean
|
| 57 |
|
|
indicating whether the value type was found (only in this
|
| 58 |
|
|
case is the first entry in the pair valid).
|
| 59 |
|
|
</p>
|
| 60 |
|
|
|
| 61 |
|
|
<pre>
|
| 62 |
|
|
<b>template</b><
|
| 63 |
|
|
<b>class</b> MMap_Cntnr<
|
| 64 |
|
|
<b>inline</b> <b>typename</b> MMap_Cntnr::size_type
|
| 65 |
|
|
mmap_value_erase
|
| 66 |
|
|
(MMap_Cntnr &r_mmap_cntnr,
|
| 67 |
|
|
<b>typename</b> MMap_Cntnr::const_reference r_val,
|
| 68 |
|
|
<b>bool</b> erase_entry_if_last);
|
| 69 |
|
|
</pre>
|
| 70 |
|
|
|
| 71 |
|
|
<p>
|
| 72 |
|
|
Transactionally erases the (const reference to the) value-type
|
| 73 |
|
|
<font color = "#666666"><tt>r_val</tt></font> from
|
| 74 |
|
|
the multimap object
|
| 75 |
|
|
<font color = "#666666"><tt>r_mmap_cntnr</tt></font>, and
|
| 76 |
|
|
erases the mapped value type
|
| 77 |
|
|
with
|
| 78 |
|
|
<font color = "#666666"><tt>r_val</tt></font>'s key
|
| 79 |
|
|
if there are no more value types with this given key
|
| 80 |
|
|
and
|
| 81 |
|
|
<font color = "#666666"><tt>erase_entry_if_last</tt></font> <tt>= <b>true</b></tt>.
|
| 82 |
|
|
<p>
|
| 83 |
|
|
</p>
|
| 84 |
|
|
It
|
| 85 |
|
|
returns 1 if a value type was actually erased, or 0 otherwise.
|
| 86 |
|
|
</p>
|
| 87 |
|
|
|
| 88 |
|
|
<pre>
|
| 89 |
|
|
<b>template</b><
|
| 90 |
|
|
<b>class</b> MMap_Cntnr>
|
| 91 |
|
|
<b>inline</b> std::pair<
|
| 92 |
|
|
<b>typename</b> MMap_Cntnr::mapped_data_type::find_iterator,
|
| 93 |
|
|
<b>bool</b>>
|
| 94 |
|
|
mmap_value_replace
|
| 95 |
|
|
(MMap_Cntnr &r_mmap_cntnr,
|
| 96 |
|
|
<b>typename</b> MMap_Cntnr::const_reference r_val,
|
| 97 |
|
|
<b>typename</b> MMap_Cntnr::const_data_reference r_data);
|
| 98 |
|
|
</pre>
|
| 99 |
|
|
|
| 100 |
|
|
<p>
|
| 101 |
|
|
Transactionally erases
|
| 102 |
|
|
<font color = "#666666"><tt>r_val</tt></font>
|
| 103 |
|
|
from
|
| 104 |
|
|
<font color = "#666666"><tt>r_mmap_cntnr</tt></font>
|
| 105 |
|
|
(if it such a value type exists) and
|
| 106 |
|
|
inserts instead a value type whose key is
|
| 107 |
|
|
<font color = "#666666"><tt>r_val</tt></font><tt>.first</tt>
|
| 108 |
|
|
and whose data is
|
| 109 |
|
|
<font color = "#666666"><tt>r_data</tt></font>.
|
| 110 |
|
|
</p>
|
| 111 |
|
|
<p>
|
| 112 |
|
|
<p>
|
| 113 |
|
|
It
|
| 114 |
|
|
returns a pair whose first entry is a find-type iterator
|
| 115 |
|
|
of the multimap's set type, and whose second entry is a boolean
|
| 116 |
|
|
indicating whether the new value type was inserted
|
| 117 |
|
|
(it might have
|
| 118 |
|
|
existed previously).
|
| 119 |
|
|
</p>
|
| 120 |
|
|
|
| 121 |
|
|
<p>
|
| 122 |
|
|
(If the multimap type or its set type do not guarantee exception free
|
| 123 |
|
|
erases, <tt>mmap_value_erase</tt> and <tt>mmap_value_replace</tt> will
|
| 124 |
|
|
invalidate pointers, references, and iterators).
|
| 125 |
|
|
</p>
|
| 126 |
|
|
|
| 127 |
|
|
</BODY>
|
| 128 |
|
|
</HTML>
|
