Asistentes de clase de colección

Las clases de colección CMap, CList y CArray usan funciones de asistente globales con plantilla para fines como comparar, copiar y serializar elementos. Como parte de la implementación de clases basadas en CMap, CList y CArray, debe reemplazar estas funciones según sea necesario con versiones adaptadas al tipo de datos almacenados en la asignación, lista o matriz. Para obtener información sobre cómo reemplazar funciones de asistente como SerializeElements, consulte el artículo Colecciones: cómo crear una colección con seguridad de tipos. Tenga en cuenta que ConstructElements y DestructElements han quedado en desuso.

La biblioteca MFC (Microsoft Foundation Class) proporciona las siguientes funciones globales en afxtempl.h para ayudarle a personalizar las clases de colección:

Asistentes de clase de colección

Nombre	Descripción
CompareElements	Indica si los elementos son iguales.
CopyElements	Copia un intervalo de elementos de una matriz a otra.
DumpElements	Proporciona una salida de diagnóstico orientada a flujos.
HashKey	Calcula una clave hash.
SerializeElements	Almacena o recupera elementos hacia o desde un archivo.

CompareElements

Llamado directamente por CList::Find y indirectamente por CMap::Lookup y CMap::operator[].

template<class TYPE, class ARG_TYPE>
BOOL AFXAPI
CompareElements(
    const TYPE* pElement1,
    const ARG_TYPE* pElement2);

Parámetros

TYPE
El tipo del primer elemento que se va a comparar.

pElement1
Puntero al primer elemento que se va a comparar.

ARG_TYPE
El tipo del segundo elemento que se va a comparar.

pElement2
Puntero al segundo elemento que se va a comparar.

Valor devuelto

Distinto de cero si el objeto al que apunta pElement1 es igual al objeto al que apunta pElement2; de lo contrario, 0.

Comentarios

Las llamadas CMap usan los parámetros de plantilla CMapKEY y ARG_KEY.

La implementación predeterminada devuelve el resultado de la comparación de *pElement1 y *pElement2. Reemplace esta función para que compare los elementos de una manera adecuada para la aplicación.

El lenguaje C++ define el operador de comparación (==) para tipos simples (char, int, float, etc.), pero no define un operador de comparación para clases y estructuras. Si desea usar CompareElements o crear una instancia de una de las clases de colección que la usa, debe definir el operador de comparación o sobrecargar CompareElements con una versión que devuelva los valores adecuados.

Requisitos

Encabezado: afxtempl.h

CopyElements

CArray::Append y CArray::Copy llaman directamente a esta función.

template<class TYPE>
void AFXAPI CopyElements(
    TYPE* pDest,
    const TYPE* pSrc,
    INT_PTR nCount);

Parámetros

TYPE
Parámetro de plantilla que especifica el tipo de elementos que se van a copiar.

pDest
Puntero al destino donde se copiarán los elementos.

pSrc
Puntero al origen de los elementos que se van a copiar.

nCount
Número de elementos que se van a copiar.

Comentarios

La implementación predeterminada usa el operador de asignación simple (=) para realizar la operación de copia. Si el tipo que se copia no tiene un operador sobrecargado =, la implementación predeterminada realiza una copia bit a bit.

Para obtener información sobre cómo implementar esta y otras funciones de asistente, consulte el artículo Colecciones: cómo crear una colección con seguridad de tipos.

Requisitos

Encabezado afxtempl.h

DumpElements

Proporciona una salida de diagnóstico orientada a secuencias en formato de texto para los elementos de la colección cuando se reemplazan.

template<class TYPE>
void  AFXAPI DumpElements(
    CDumpContext& dc,
    const TYPE* pElements,
    INT_PTR nCount);

Parámetros

dc
Contexto de volcado de memoria para elementos de volcado.

TYPE
Parámetro de plantilla que especifica el tipo de los elementos.

pElements
Puntero a los elementos que se van a volcar.

nCount
Número de elementos que se van a volcar.

Comentarios

Las funciones CArray::Dump, CList::Dump y CMap::Dump llaman a esto si la profundidad del volcado es mayor que 0.

La implementación predeterminada no hace nada. Si los elementos de la colección se derivan de CObject, el reemplazo normalmente recorrerá en iteración los elementos de la colección, llamando a Dump para cada elemento a su vez.

Requisitos

Encabezado afxtempl.h

HashKey

Calcula un valor hash para la clave especificada.

template<class ARG_KEY>
AFX_INLINE UINT AFXAPI HashKey(ARG_KEY  key);

Parámetros

ARG_KEY
Parámetro de plantilla que especifica el tipo de datos usado para acceder a las claves de asignación.

key
Clave cuyo valor hash se va a calcular.

Valor devuelto

El valor hash de la clave.

Comentarios

A esta función la llama directamente CMap::RemoveKey e indirectamente CMap::Lookup y CMap::operator[].

La implementación predeterminada crea un valor hash desplazando la clave a la derecha cuatro posiciones. Reemplace esta función para que devuelva los valores hash adecuados para la aplicación.

Ejemplo

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));
}

Requisitos

Encabezado afxtempl.h

SerializeElements

CArray, CList y CMap llaman a esta función para serializar elementos.

template<class TYPE>
void AFXAPI SerializeElements(CArchive& ar, TYPE* pElements, INT_PTR nCount);

Parámetros

TYPE
Parámetro de plantilla que especifica el tipo de los elementos.

Ar
Un objeto de archivo desde o hacia el que se va a archivar.

pElements
Puntero a los elementos que se archivan.

nCount
Número de elementos que se archivan.

Comentarios

La implementación predeterminada realiza una lectura o escritura bit a bit.

Para obtener información sobre cómo implementar esta y otras funciones de asistente, consulte el artículo Colecciones: cómo crear una colección con seguridad de tipos.

Ejemplo

Consulte el ejemplo del artículo Colecciones: cómo crear una colección con seguridad de tipos.

Requisitos

Encabezado afxtempl.h

Consulte también

Macros y globales
CMap (clase)
CList (clase)
CArray (clase)