l4/pkg/libstdc++-v3/contrib/libstdc++-v3-4.1.0/docs/html/ext/pb_assoc/mmap_value_utils.html

   1 <!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>&lt;<b>int</b>, <b>char</b>&gt;</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&lt;<b>int</b>, <b>char</b>&gt;</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>&lt;
  38   <b>class</b> MMap_Cntnr&gt;
  39 <b>inline</b> std::pair&lt;
  40     <b>typename</b> MMap_Cntnr::mapped_data_type::find_iterator,
  41     <b>bool</b>&gt;
  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>&lt;
  63   <b>class</b> MMap_Cntnr&lt;
  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>&lt;
  90   <b>class</b> MMap_Cntnr&gt;
  91 <b>inline</b> std::pair&lt;
  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>