CAtlMap::CAtlMap

Article
12/01/2015

The constructor.

Syntax

      CAtlMap(
   UINT nBins = 17,
   float fOptimalLoad = 0.75f,
   float fLoThreshold = 0.25f,
   float fHiThreshold = 2.25f,
   UINT nBlockSize = 10 
) throw ( );

Parameters

nBins
The number of bins providing pointers to the stored elements. See Remarks later in this topic for an explanation of bins.
fOptimalLoad
The optimal load ratio.
fLoThreshold
The lower threshold for the load ratio.
fHiThreshold
The upper threshold for the load ratio.
nBlockSize
The block size.

Remarks

CAtlMap references all of its stored elements by first creating an index using a hashing algorithm on the key. This index references a "bin" which contains a pointer to the stored elements. If the bin is already in use, a linked-list is created to access the subsequent elements. Traversing a list is slower than directly accessing the correct element, and so the map structure needs to balance storage requirements against performance. The default parameters have been chosen to give good results in most cases.

The load ratio is the ratio of the number of bins to the number of elements stored in the map object. When the map structure is recalculated, the fOptimalLoad parameter value will be used to calculate the number of bins required. This value can be changed using the CAtlMap::SetOptimalLoad method.

The fLoThreshold parameter is the lower value that the load ratio can reach before CAtlMap will recalculate the optimal size of the map.

The fHiThreshold parameter is the upper value that the load ratio can reach before the CAtlMap object will recalculate the optimal size of the map.

This recalculation process (known as rehashing) is enabled by default. If you want to disable this process, perhaps when entering a lot of data at one time, call the CAtlMap::DisableAutoRehash method. Reactivate it with the CAtlMap::EnableAutoRehash method.

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.

Before any data can be stored, it is necessary to initialize the hash table with a call to CAtlMap::InitHashTable.

Example

// Create a map which stores a double
// value using an integer key

CAtlMap<int, double> mySinTable;
int i;

// Initialize the Hash Table
mySinTable.InitHashTable(257);

// Add items to the map
for (i = 0; i < 90; i++)
   mySinTable[i] = sin((double)i);

// Confirm the map is valid
mySinTable.AssertValid();

// Confirm the number of elements in the map
ATLASSERT(mySinTable.GetCount() == 90);

// Remove elements with even key values
for (i = 0; i < 90; i += 2)
   mySinTable.RemoveKey(i);

// Confirm the number of elements in the map
ATLASSERT(mySinTable.GetCount() == 45);

// Walk through all the elements in the map.
// First, get start position.
POSITION pos;
int key;
double value;
pos = mySinTable.GetStartPosition();

// Now iterate the map, element by element
while (pos != NULL) 
{
   key = mySinTable.GetKeyAt(pos);
   value = mySinTable.GetNextValue(pos);
}

Requirements

Header: atlcoll.h

Share via