|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
A dictionary collection class that maps unique keys to values.
Once you have inserted a key-value pair (element) into the map, you can efficiently retrieve or delete the pair using the key to access it. You can also iterate over all the elements in the map.
A variable of type POSITION is used for alternate access to entries. You can use a POSITION to "remember" an entry and to iterate through the map. You might think that this iteration is sequential by key value; it is not. The sequence of retrieved elements is indeterminate.
Certain member functions of this class call global helper functions that must be customized for most uses of the CMap class. See Collection Class Helpers in the Macros and Globals section of the MFCReference.
CMap overrides CObject::Serialize to support serialization and dumping of its elements. If a map is stored to an archive using Serialize, each map element is serialized in turn. The default implementation of the SerializeElements helper function does a bitwise write. For information about serialization of pointer collection items derived from CObject or other user defined types, see How to: Make a Type-Safe Collection.
If you need a diagnostic dump of the individual elements in the map (the keys and values), you must set the depth of the dump context to 1 or greater.
When a CMap object is deleted, or when its elements are removed, the keys and values both are removed.
Map class derivation is similar to list derivation. See the article Collections for an illustration of the derivation of a special-purpose list class.