CRBMap 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 CRBMap Class.

This class represents a mapping structure, using a Red-Black binary tree.

Syntax

template <typename K,
          typename V, 
          class KTraits = CElementTraits<K>, 
          class VTraits = CElementTraits<V>> 
class CRBMap : 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

Public Methods

Remarks

CRBMap provides support for a mapping array of any given type, managing an ordered array of key elements and their associated values. Each key can have only one associated value. Elements (consisting of a key and a value) are stored in a binary tree structure, using the CRBMap::SetAt method. Elements can be removed using the CRBMap::RemoveKey method, which deletes the element with the given key value.

Traversing the tree is made possible with methods such as CRBTree::GetHeadPosition, CRBTree::GetNext, and CRBTree::GetNextValue.

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

CRBMap is derived from CRBTree, which implements a binary tree using the Red-Black algorithm. CRBMultiMap is a variation that allows multiple values for each key. It too is derived from CRBTree, and so shares many features with CRBMap.

An alternative to both CRBMap and CRBMultiMap 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

CRBMap

Requirements

Header: atlcoll.h

CRBMap::CRBMap

The constructor.

explicit CRBMap(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 map object which has an
   // integer key, a double value, and a
   // block size of 5
   CRBMap<int, double> myMap(5);

CRBMap::~CRBMap

The destructor.

~CRBMap() throw();

Remarks

Frees any allocated resources.

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

CRBMap::Lookup

Call this method to look up keys or values in the CRBMap object.

bool Lookup(KINARGTYPE key, VOUTARGTYPE value) const throw(...);
const CPair* Lookup(KINARGTYPE key) const throw();
CPair* Lookup(KINARGTYPE key) throw();

Parameters

key
Specifies the key that identifies the element to be looked up.

value
Variable that receives the looked-up value.

Return Value

The first form of the method returns true if the key is found, otherwise false. The second and third forms return a pointer to a CPair.

Remarks

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

Example

   // Look up the value for a key of 0
   double v;
   myMap.Lookup(0,v);

CRBMap::RemoveKey

Call this method to remove an element from the CRBMap object, given the key.

bool RemoveKey(KINARGTYPE key) throw();

Parameters

key
The key corresponding to the element pair you want to remove.

Return Value

Returns true if the key is found and removed, false on failure.

Remarks

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

Example

   // Remove an element, based on the key of 0
   ATLVERIFY(myMap.RemoveKey(0) == true);

CRBMap::SetAt

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

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

Parameters

key
The key value to add to the CRBMap object.

value
The value to add to the CRBMap object.

Return Value

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

Remarks

SetAt replaces an existing element if a matching key is found. If the key is not found, a new key/value pair is created.

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

Example

   // Add an element to the map, with a key of 0
   myMap.SetAt(0,1.1);

See Also

CRBTree Class
CAtlMap Class
CRBMultiMap Class
Class Overview