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
| Name | Description |
|---|---|
| CRBMap::CRBMap | The constructor. |
| CRBMap::~CRBMap | The destructor. |
Public Methods
| Name | Description |
|---|---|
| CRBMap::Lookup | Call this method to look up keys or values in the CRBMap object. |
| CRBMap::RemoveKey | Call this method to remove an element from the CRBMap object, given the key. |
| CRBMap::SetAt | Call this method to insert an element pair into the map. |
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
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