Collection Class Helpers
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at Collection Class Helpers.
The collection classes CMap, CList, and CArray use templated global helper functions for such purposes as comparing, copying, and serializing elements. As part of your implementation of classes based on CMap, CList, and CArray, you must override these functions as necessary with versions tailored to the type of data stored in your map, list, or array. For information on overriding helper functions such as SerializeElements, see the article Collections: How to Make a Type-Safe Collection. Note that ConstructElements and DestructElements have been deprecated.
The Microsoft Foundation Class Library provides the following global functions to help you customize your collection classes:
Collection Class Helpers
| CompareElements | Indicates whether elements are the same. |
| CopyElements | Copies elements from one array to another. |
| DumpElements | Provides stream-oriented diagnostic output. |
| HashKey | Calculates a hash key. |
| SerializeElements | Stores or retrieves elements to or from an archive. |
CompareElements
Called directly by [CList::Find](../Topic/CList%20Class.md#not_found.md#clist__find and indirectly by [cmap__lookup](../topic/not_found.md#cmap__lookup and [cmap__operator []]--brokenlink--(../topic/cmap__operator).
template<class TYPE, class ARG_TYPE>
BOOL AFXAPI CompareElements(
const TYPE* pElement1,
const ARG_TYPE* pElement2);
Parameters
TYPE
The type of the first element to be compared.
pElement1
Pointer to the first element to be compared.
ARG_TYPE
The type of the second element to be compared.
pElement2
Pointer to the second element to be compared.
Return Value
Nonzero if the object pointed to by pElement1 is equal to the object pointed to by pElement2; otherwise 0.
Remarks
The CMap calls use the CMap template parameters KEY and ARG_KEY.
The default implementation returns the result of the comparison of *pElement1 and *pElement2. Override this function so that it compares the elements in a way that is appropriate for your application.
The C++ language defines the comparison operator ( ==) for simple types ( char, int, float, and so on) but does not define a comparison operator for classes and structures. If you want to use CompareElements or to instantiate one of the collection classes that uses it, you must either define the comparison operator or overload CompareElements with a version that returns appropriate values.
CopyElements
This function is called directly by CArray::Append and CArray::Copy.
template<class TYPE>
void AFXAPI CopyElements(
TYPE* pDest,
const TYPE* pSrc,
INT_PTR nCount);
Parameters
TYPE
Template parameter specifying the type of elements to be copied.
pDest
Pointer to the destination where the elements will be copied.
pSrc
Pointer to the source of the elements to be copied.
nCount
Number of elements to be copied.
Remarks
The default implementation uses the simple assignment operator ( = ) to perform the copy operation. If the type being copied does not have an overloaded operator=, then the default implementation performs a bitwise copy.
For information on implementing this and other helper functions, see the article Collections: How to Make a Type-Safe Collection.
DumpElements
Provides stream-oriented diagnostic output in text form for the elements of your collection when overridden.
template<class TYPE>
void AFXAPI DumpElements(
CDumpContext& dc,
const TYPE* pElements,
INT_PTR nCount);
Parameters
dc
Dump context for dumping elements.
TYPE
Template parameter specifying the type of the elements.
pElements
Pointer to the elements to be dumped.
nCount
Number of elements to be dumped.
Remarks
The CArray::Dump, CList::Dump, and CMap::Dump functions call this if the depth of the dump is greater than 0.
The default implementation does nothing. If the elements of your collection are derived from CObject, your override will typically iterate through the collection's elements, calling Dump for each element in turn.
For information on diagnostics and on the Dump function, see Debugging MFC Applications.
HashKey
Calculates a hash value for the given key.
template<class ARG_KEY>
AFX_INLINE UINT AFXAPI HashKey(ARG_KEY key);
Parameters
ARG_KEY
Template parameter specifying the data type used to access map keys.
key
The key whose hash value is to be calculated.
Return Value
The key's hash value.
Remarks
This function is called directly by [CMap::RemoveKey](../Topic/CMap%20Class.md#cmap__removekey and indirectly by [CMap::Lookup](../Topic/CMap%20Class.md#cmap__lookup and CMap::Operator [].
The default implementation creates a hash value by shifting key right by four positions. Override this function so that it returns hash values appropriate for your application.
Example
template <> UINT AFXAPI HashKey(unsigned __int64 key)
{
// Generate the hash value by XORing the lower 32 bits of the number
// with the upper 32 bits
return(UINT(key) ^ UINT(key >> 32));
}
SerializeElements
CArray, CList, and CMap call this function to serialize elements.
template<class TYPE>
void AFXAPI SerializeElements(CArchive& ar, TYPE* pElements, INT_PTR nCount);
Parameters
TYPE
Template parameter specifying the type of the elements.
ar
An archive object to archive to or from.
pElements
Pointer to the elements being archived.
nCount
Number of elements being archived
Remarks
The default implementation does a bitwise read or write.
For information on implementing this and other helper functions, see the article Collections: How to Make a Type-Safe Collection.
Example
See the example in the article Collections: How to Make a Type-Safe Collection.