Share via


CRBMultiMap Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CRBMultiMap Class.

This class represents a mapping structure that allows each key can be associated with more than one value, using a Red-Black binary tree.

Syntax

template<typename K,
         typename V, 
         class KTraits = CElementTraits<K>, 
         class VTraits = CElementTraits<V>>  
class CRBMultiMap : public CRBTree<K, V, KTraits, VTraits>

Parameters

K
The key element type.

V
The value element type.

KTraits
The code used to copy or move key elements. See CElementTraits Class for more details.

VTraits
The code used to copy or move value elements.

Members

Public Constructors

Name Description
CRBMultiMap::CRBMultiMap The constructor.
CRBMultiMap::~CRBMultiMap The destructor.

Public Methods

Name Description
CRBMultiMap::FindFirstWithKey Call this method to find the position of the first element with a given key.
CRBMultiMap::GetNextValueWithKey Call this method to get the value associated with a given key, and update the position value.
CRBMultiMap::GetNextWithKey Call this method to get the element associated with a given key, and update the position value.
CRBMultiMap::Insert Call this method to insert an element pair into the map.
CRBMultiMap::RemoveKey Call this method to remove all of the key/value elements for a given key.

Remarks

CRBMultiMap provides support for a mapping array of any given type, managing an ordered array of key elements and values. Unlike the CRBMap class, each key can be associated with more than one value.

Elements (consisting of a key and a value) are stored in a binary tree structure, using the CRBMultiMap::Insert method. Elements can be removed using the CRBMultiMap::RemoveKey method, which deletes all elements which match the given key.

Traversing the tree is made possible with methods such as CRBTree::GetHeadPosition, CRBTree::GetNext, and CRBTree::GetNextValue. Accessing the potentially multiple values per key is possible using the CRBMultiMap::FindFirstWithKey, CRBMultiMap::GetNextValueWithKey, and CRBMultiMap::GetNextWithKey methods. See the example for CRBMultiMap::CRBMultiMap for an illustration of this in practice.

The KTraits and VTraits parameters are traits classes that contain any supplemental code needed to copy or move elements.

CRBMultiMap is derived from CRBTree, which implements a binary tree using the Red-Black algorithm. An alternative to CRBMultiMap and CRBMap is offered by the CAtlMap class. When only a small number of elements needs to be stored, consider using the CSimpleMap class instead.

For a more complete discussion of the various collection classes and their features and performance characteristics, see ATL Collection Classes.

Inheritance Hierarchy

CRBTree

CRBMultiMap

Requirements

Header: atlcoll.h

CRBMultiMap::CRBMultiMap

The constructor.

explicit CRBMultiMap(size_t nBlockSize = 10) throw();

Parameters

nBlockSize
The block size.

Remarks

The nBlockSize parameter is a measure of the amount of memory allocated when a new element is required. Larger block sizes reduce calls to memory allocation routines, but use more resources. The default will allocate space for 10 elements at a time.

See the documentation for the base class CRBTree for information on the other methods available.

Example

   // Define a multimap object which has an integer
   // key, a double value, and a block size of 5
   CRBMultiMap<int, double> myMap(5);

   // Add some key/values. Notice how three
   // different values are associated with 
   // one key. In a CRBMap object, the values
   // would simply overwrite each other.
   myMap.Insert(0, 1.1);
   myMap.Insert(0, 1.2);
   myMap.Insert(0, 1.3);
   myMap.Insert(1, 2.1);

   // Look up a key and iterate through
   // all associated values

   double v;
   POSITION myPos = myMap.FindFirstWithKey(0);

   while (myPos != NULL)
   {
      v = myMap.GetNextValueWithKey(myPos,0);
      // As the loop iterates, v 
      // contains the values 1.3, 1.2, 1.1
   }

   // Remove all of the values associated with that key
   size_t i = myMap.RemoveKey(0);

   // Confirm all three values were deleted
   ATLASSERT(i == 3);

CRBMultiMap::~CRBMultiMap

The destructor.

~CRBMultiMap() throw();

Remarks

Frees any allocated resources.

See the documentation for the base class CRBTree for information on the other methods available.

CRBMultiMap::FindFirstWithKey

Call this method to find the position of the first element with a given key.

POSITION FindFirstWithKey(KINARGTYPE key) const throw();

Parameters

key
Specifies the key that identifies the element to be found.

Return Value

Returns the POSITION of the first key/value element if the key is found, NULL otherwise.

Remarks

A key in the CRBMultiMap can have one or more associated values. This method will provide the position value of the first value (which may, in fact, be the only value) associated with that particular key. The position value returned can then be used with CRBMultiMap::GetNextValueWithKey or CRBMultiMap::GetNextWithKey to obtain the value and update the position.

See the documentation for the base class CRBTree for information on the other methods available.

Example

See the example for CRBMultiMap::CRBMultiMap.

CRBMultiMap::GetNextValueWithKey

Call this method to get the value associated with a given key and update the position value.

const V& GetNextValueWithKey(
    POSITION& pos,
    KINARGTYPE key) const throw();
V& GetNextValueWithKey(
    POSITION& pos,
    KINARGTYPE key) throw();

Parameters

pos
The position value, obtained with either a call to CRBMultiMap::FindFirstWithKey or CRBMultiMap::GetNextWithKey, or a previous call to GetNextValueWithKey.

key
Specifies the key that identifies the element to be found.

Return Value

Returns the element pair associated with the given key.

Remarks

The position value is updated to point to the next value associated with the key. If no more values exist, the position value is set to NULL.

See the documentation for the base class CRBTree for information on the other methods available.

Example

See the example for CRBMultiMap::CRBMultiMap.

CRBMultiMap::GetNextWithKey

Call this method to get the element associated with a given key and update the position value.

const CPair* GetNextWithKey(
    POSITION& pos,
    KINARGTYPE key) const throw();
CPair* GetNextWithKey(
    POSITION& pos,
    KINARGTYPE key) throw();

Parameters

pos
The position value, obtained with either a call to CRBMultiMap::FindFirstWithKey or CRBMultiMap::GetNextValueWithKey, or a previous call to GetNextWithKey.

key
Specifies the key that identifies the element to be found.

Return Value

Returns the next CRBTree::CPair Class element associated with the given key.

Remarks

The position value is updated to point to the next value associated with the key. If no more values exist, the position value is set to NULL.

See the documentation for the base class CRBTree for information on the other methods available.

CRBMultiMap::Insert

Call this method to insert an element pair into the map.

POSITION Insert(KINARGTYPE key, VINARGTYPE value) throw(...);

Parameters

key
The key value to add to the CRBMultiMap object.

value
The value to add to the CRBMultiMap object, associated with key.

Return Value

Returns the position of the key/value element pair in the CRBMultiMap object.

Remarks

See the documentation for the base class CRBTree for information on the other methods available.

Example

See the example for CRBMultiMap::CRBMultiMap.

CRBMultiMap::RemoveKey

Call this method to remove all of the key/value elements for a given key.

size_t RemoveKey(KINARGTYPE key) throw();

Parameters

key
Specifies the key that identifies the element(s) to be deleted.

Return Value

Returns the number of values associated with the given key.

Remarks

RemoveKey deletes all of the key/value elements that have a key that matches key.

See the documentation for the base class CRBTree for information on the other methods available.

Example

See the example for CRBMultiMap::CRBMultiMap.

See Also

CRBTree Class
CAtlMap Class
CRBMap Class
Class Overview