CAtlMap Class

Article
01/08/2013

This class provides methods for creating and managing a map object.

template< 
   typename K, 
   typename V, 
   class KTraits = CElementTraits< K >, 
   class VTraits = CElementTraits< V > 
> 
class CAtlMap

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 Typedefs

Name	Description
CAtlMap::KINARGTYPE	Type used when a key is passed as an input argument
CAtlMap::KOUTARGTYPE	Type used when a key is returned as an output argument.
CAtlMap::VINARGTYPE	Type used when a value is passed as an input argument.
CAtlMap::VOUTARGTYPE	Type used when a value is passed as an output argument.

Public Classes

Name	Description
CAtlMap::CPair Class	A class containing the key and value elements.

CPair Data Members

Name	Description
CAtlMap::CPair::m_key	The data member storing the key element.
CAtlMap::CPair::m_value	The data member storing the value element.

Public Constructors

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

Public Methods

Name	Description
CAtlMap::AssertValid	Call this method to cause an ASSERT if the CAtlMap is not valid.
CAtlMap::DisableAutoRehash	Call this method to disable automatic rehashing of the CAtlMap object.
CAtlMap::EnableAutoRehash	Call this method to enable automatic rehashing of the CAtlMap object.
CAtlMap::GetAt	Call this method to return the element at a specified position in the map.
CAtlMap::GetCount	Call this method to retrieve the number of elements in the map.
CAtlMap::GetHashTableSize	Call this method to determine the number of bins in the map's hash table.
CAtlMap::GetKeyAt	Call this method to retrieve the key stored at the given position in the CAtlMap object.
CAtlMap::GetNext	Call this method to obtain a pointer to the next element pair stored in the CAtlMap object.
CAtlMap::GetNextAssoc	Gets the next element for iterating.
CAtlMap::GetNextKey	Call this method to retrieve the next key from the CAtlMap object.
CAtlMap::GetNextValue	Call this method to get the next value from the CAtlMap object.
CAtlMap::GetStartPosition	Call this method to start a map iteration.
CAtlMap::GetValueAt	Call this method to retrieve the value stored at a given position in the CAtlMap object.
CAtlMap::InitHashTable	Call this method to initialize the hash table.
CAtlMap::IsEmpty	Call this method to test for an empty map object.
CAtlMap::Lookup	Call this method to look up keys or values in the CAtlMap object.
CAtlMap::Rehash	Call this method to rehash the CAtlMap object.
CAtlMap::RemoveAll	Call this method to remove all elements from the CAtlMap object.
CAtlMap::RemoveAtPos	Call this method to remove the element at the given position in the CAtlMap object.
CAtlMap::RemoveKey	Call this method to remove an element from the CAtlMap object, given the key.
CAtlMap::SetAt	Call this method to insert an element pair into the map.
CAtlMap::SetOptimalLoad	Call this method to set the optimal load of the CAtlMap object.
CAtlMap::SetValueAt	Call this method to change the value stored at a given position in the CAtlMap object.

Public Operators

Name	Description
CAtlMap::operator []	Replaces or adds a new element to the CAtlMap.

Remarks

CAtlMap provides support for a mapping array of any given type, managing an unordered array of key elements and their associated values. Elements (consisting of a key and a value) are stored using a hashing algorithm, allowing a large amount of data to be efficiently stored and retrieved.

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

An alternative to CAtlMap is offered by the CRBMap class. CRBMap also stores key/value pairs, but exhibits different performance characteristics. The time taken to insert an item, look up a key, or delete a key from a CRBMap object is of order log(n), where n is the number of elements. For CAtlMap, all of these operations typically take a constant time, although worst-case scenarios might be of order n. Therefore, in a typical case, CAtlMap is faster.

The other difference between CRBMap and CAtlMap becomes apparent when iterating through the stored elements. In a CRBMap, the elements are visited in a sorted order. In a CAtlMap, the elements are not ordered, and no order can be inferred.

When a small number of elements need to be stored, consider using the CSimpleMap class instead.

For more information, see ATL Collection Classes.

Requirements

Header: atlcoll.h