Share via


CAtlMap Class

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

See Also

Concepts

Marquee Sample

UpdatePV Sample

Other Resources

ATL Class Overview