    
    
Multimap Value-Type Utilities
	In 
pb_assoc, associative containers have a unique-key design.
Multimaps, consequently are maps of sets, 
e.g.,
a 
cc_ht_multimap.htmlcc_ht_multimap <int, char>object maps 
ints to sets of chars.
 It is often convenient to perform
value-type operations on multimaps, 
e.g., in this case, to find a specific
std::pair<int, char> object (say, std::make_pair(2, 'b'))
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.)
	Coding these two-step operations is repetitious and error prone.
	
pb_assoc 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
 
std::make_pair(2, 'b')). Following are some utility functions for
 other common operations.
template<
  
class MMap_Cntnr>
inline std::pair<
    
typename MMap_Cntnr::mapped_data_type::find_iterator,
    
bool>
  mmap_value_find
  (
const MMap_Cntnr &r_mmap_cntnr,
    
typename MMap_Cntnr::const_reference r_val);
	Finds the (const reference to a) value-type
r_val in
the multimap object
r_mmap_cntnr.
 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).
template<
  
class MMap_Cntnr<
inline typename MMap_Cntnr::size_type
  mmap_value_erase
  (MMap_Cntnr &r_mmap_cntnr,
    
typename MMap_Cntnr::const_reference r_val,
    
bool erase_entry_if_last);
	Transactionally erases the (const reference to the) value-type
r_val from
the multimap object
r_mmap_cntnr, and
erases the mapped value type
with
r_val's key
if there are no more value types with this given key
and
erase_entry_if_last = true.
 It
returns 1 if a value type was actually erased, or 0 otherwise.
template<
  
class MMap_Cntnr>
inline std::pair<
    
typename MMap_Cntnr::mapped_data_type::find_iterator,
    
bool>
  mmap_value_replace
  (MMap_Cntnr &r_mmap_cntnr,
    
typename MMap_Cntnr::const_reference r_val,
    
typename MMap_Cntnr::const_data_reference r_data);
	Transactionally erases
r_valfrom
r_mmap_cntnr(if it such a value type exists) and
inserts instead a value type whose key is
r_val.firstand whose data is
r_data.
 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).
(If the multimap type or its set type do not guarantee exception free
erases, 
mmap_value_erase and mmap_value_replace will
invalidate pointers, references, and iterators).
