Compartir a través de

Clase CMap

  • Artículo

Una clase de colección de diccionarios que asigna claves únicas a valores.

Sintaxis

template<class KEY, class ARG_KEY, class VALUE, class ARG_VALUE>class CMap : public CObject

Parámetros

KEY
Clase del objeto utilizado como clave para la asignación.

ARG_KEY
Tipo de datos usado para argumentos KEY; normalmente una referencia a KEY.

VALUE
Clase del objeto almacenado en la asignación.

ARG_VALUE
Tipo de datos usado para argumentos VALUE; normalmente una referencia a VALUE.

Miembros

Estructuras públicas

Nombre Descripción
CMap::CPair Estructura anidada que contiene un valor de clave y el valor del objeto asociado.

Constructores públicos

Nombre Descripción
CMap::CMap Construye una colección que asigna claves a valores.

Métodos públicos

Nombre Descripción
CMap::GetCount Devuelve el número de elementos en esta asignación.
CMap::GetHashTableSize Devuelve el número de elementos de la tabla hash.
CMap::GetNextAssoc Obtiene el siguiente elemento para iterar.
CMap::GetSize Devuelve el número de elementos en esta asignación.
CMap::GetStartPosition Devuelve la posición del primer elemento.
CMap::InitHashTable Inicializa la tabla hash y especifica su tamaño.
CMap::IsEmpty Prueba la condición de asignación vacía (sin elementos).
CMap::Lookup Busca el valor asignado a una clave determinada.
CMap::PGetFirstAssoc Devuelve un puntero al primer elemento.
CMap::PGetNextAssoc Obtiene un puntero al siguiente elemento para iterar.
CMap::PLookup Devuelve un puntero a una clave cuyo valor coincide con el valor especificado.
CMap::RemoveAll Quita todos los elementos de esta asignación.
CMap::RemoveKey Quita un elemento especificado por una clave.
CMap::SetAt Inserta un elemento en el mapa; reemplaza un elemento existente si se encuentra una clave coincidente.

Operadores públicos

Nombre Descripción
CMap::operator [ ] Inserta un elemento en la asignación: sustitución de operadores para SetAt.

Comentarios

Una vez que hayas insertado un par clave-valor (elemento) en la asignación, puedes recuperar o eliminar eficazmente el par utilizando la clave para acceder a él. También puede iterar todos los elementos de la asignación.

Se usa una variable de tipo POSITION para el acceso alternativo a las entradas. Puede usar POSITION para "recordar" una entrada y recorrer en iteración el mapa. Podrías pensar que esta iteración es secuencial según el valor de clave; pero no es así. La secuencia de elementos recuperados es indeterminada.

Algunas funciones miembro de esta clase llaman a funciones auxiliares globales que se deben personalizar en la mayoría de los usos de la clase CMap. Consulta Asistentes de clase de colección en la sección Macros y variables globales de la Referencia MFC.

CMap invalida CObject::Serialize para admitir la serialización y el volcado de sus elementos. Si un mapa se almacena en un archivo mediante Serialize, cada elemento de la asignación se serializa a su vez. La implementación predeterminada de la función auxiliar SerializeElements realiza una escritura bit a bit. Para obtener información sobre la serialización de elementos de colección de punteros derivados de CObject u otros tipos definidos por el usuario, consulta Tutorial: hacer una recopilación con seguridad de tipos.

Si necesitas un volcado de diagnóstico de los elementos individuales de la asignación (las claves y los valores), debes establecer la profundidad del contexto de volcado en 1 o más.

Cuando se elimina un objeto CMap, o cuando se quitan sus elementos, se eliminan tanto las claves como los valores.

La derivación de clases de asignación es similar a la derivación de listas. Consulta el artículo Colecciones para obtener una ilustración de la derivación de una clase de lista para un propósito especial.

Jerarquía de herencia

CObject

CMap

Requisitos

Encabezado: afxtempl.h

CMap::CMap

Construye una asignación vacía.

CMap(INT_PTR nBlockSize = 10);

Parámetros

nBlockSize
Especifica la granularidad de la asignación de memoria para extender la asignación.

Comentarios

A medida que crece la asignación, la memoria se asigna en unidades de nBlockSize entradas.

Ejemplo

// declares a map of ints to points
CMap<int, int, CPoint, CPoint> myMap(16);

CMap::CPair

Contiene un valor de clave y el valor del objeto asociado.

Comentarios

Se trata de una estructura anidada dentro de la clase CMap.

La estructura se compone de dos campos:

  • key El valor real del tipo de clave.

  • value El valor del objeto asociado.

Se usa para almacenar los valores devueltos de CMap::PLookup, CMap::PGetFirstAssocy CMap::PGetNextAssoc.

Ejemplo

Para obtener un ejemplo de uso, consulta el ejemplo para CMap::PLookup.

CMap::GetCount

Recupera el número de elementos de la asignación.

INT_PTR GetCount() const;

Valor devuelto

Número de elementos.

Ejemplo

Vea el ejemplo de CMap::Lookup.

CMap::GetHashTableSize

Determina el número de elementos de la tabla hash para la asignación.

UINT GetHashTableSize() const;

Valor devuelto

El número de elementos de la tabla hash.

Ejemplo

CMap<int, int, CPoint, CPoint> myMap;

UINT uTableSize = myMap.GetHashTableSize();

CMap::GetNextAssoc

Recupera el elemento de la asignación en rNextPosition y, a continuación, se actualiza rNextPosition para hacer referencia al siguiente elemento de la asignación.

void GetNextAssoc(
    POSITION& rNextPosition,
    KEY& rKey,
    VALUE& rValue) const;

Parámetros

rNextPosition
Especifica una referencia a un valor POSITION devuelto por una llamada a GetNextAssoc o GetStartPosition anterior.

KEY
Parámetro de plantilla que especifica el tipo de clave de la asignación.

rKey
Especifica la clave devuelta del elemento recuperado.

VALUE
Parámetro de plantilla que especifica el tipo del valor del mapa.

rValue
Especifica el valor devuelto del elemento recuperado.

Comentarios

Esta función es más útil para recorrer en iteración todos los elementos del mapa. Tenga en cuenta que la secuencia de posición no es necesariamente la misma que la secuencia de valores de clave.

Si el elemento recuperado es el último del mapa, el nuevo valor de rNextPosition se establece en NULL.

Ejemplo

Vea el ejemplo de CMap::SetAt.

CMap::GetSize

Devuelve el número de elementos de la asignación.

INT_PTR GetSize() const;

Valor devuelto

El número de elementos de la asignación.

Comentarios

Llame a este método para recuperar el número de elementos del mapa.

Ejemplo

CMap<int, int, CPoint, CPoint> myMap;

myMap.InitHashTable(257);

// Add 200 elements to the map.
for (int i = 0; i < 200; i++)
{
   myMap[i] = CPoint(i, i);
}

// Remove the elements with even key values.
CPoint pt;
for (int i = 0; myMap.Lookup(i, pt); i += 2)
{
   myMap.RemoveKey(i);
}

ASSERT(myMap.GetSize() == 100);
TRACE(_T("myMap with %d elements:\n"), myMap.GetCount());
POSITION pos = myMap.GetStartPosition();
int iKey;
CPoint ptVal;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, iKey, ptVal);
   TRACE(_T("\t[%d] = (%d,%d)\n"), iKey, ptVal.x, ptVal.y);
}

CMap::GetStartPosition

Inicia una iteración de la asignación mediante la devolución de un valor POSITION que se puede pasar a una llamada a GetNextAssoc.

POSITION GetStartPosition() const;

Valor devuelto

Un valor POSITION que indica una posición inicial para iterar la asignación; o NULL si la asignación está vacía.

Comentarios

La secuencia de iteración no es predecible; por lo tanto, el «primer elemento de la asignación» no tiene importancia especial.

Ejemplo

Vea el ejemplo de CMap::SetAt.

CMap::InitHashTable

Inicializa la tabla hash.

void InitHashTable(UINT hashSize, BOOL  bAllocNow = TRUE);

Parámetros

hashSize
Número de entradas de la tabla hash.

bAllocNow
Si es TRUE, se asigna la tabla hash después de la inicialización; de lo contrario, la tabla se asigna cuando es necesario.

Comentarios

Para obtener el mejor rendimiento, el tamaño de la tabla hash debe ser un número primo. Para minimizar las colisiones, el tamaño debe ser aproximadamente un 20 por ciento mayor que el conjunto de datos previsto más grande.

Ejemplo

Vea el ejemplo de CMap::Lookup.

CMap::IsEmpty

Determina si la asignación está vacía.

BOOL IsEmpty() const;

Valor devuelto

Distinto de cero si esta asignación no contiene elementos; de lo contrario, 0.

Ejemplo

Vea el ejemplo de CMap::RemoveAll.

CMap::Lookup

Busca el valor asignado a una clave determinada.

BOOL Lookup(ARG_KEY key, VALUE& rValue) const;

Parámetros

ARG_KEY
Parámetro de plantilla que especifica el tipo de valor key.

key
Especifica la clave que identifica el elemento que se va a buscar.

VALUE
Especifica el tipo del valor que se va a buscar.

rValue
Recibe el valor buscado.

Valor devuelto

Distinto de cero si se ha encontrado el elemento; de lo contrario, 0.

Comentarios

Lookup usa un algoritmo hash para buscar, de forma rápida, el elemento de mapa con una clave que coincida exactamente con la clave dada.

Ejemplo

CMap<int, int, CPoint, CPoint> myMap;

myMap.InitHashTable(257);

// Add 200 elements to the map.
for (int i = 0; i < 200; i++)
{
   myMap[i] = CPoint(i, i);
}

// Remove the elements with even key values.
CPoint pt;
for (int i = 0; myMap.Lookup(i, pt); i += 2)
{
   myMap.RemoveKey(i);
}

ASSERT(myMap.GetSize() == 100);
TRACE(_T("myMap with %d elements:\n"), myMap.GetCount());
POSITION pos = myMap.GetStartPosition();
int iKey;
CPoint ptVal;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, iKey, ptVal);
   TRACE(_T("\t[%d] = (%d,%d)\n"), iKey, ptVal.x, ptVal.y);
}

CMap::operator [ ]

Un sustituto conveniente de la función miembro SetAt.

VALUE& operator[](arg_key key);

Parámetros

VALUE
Parámetro de plantilla que especifica el tipo de clave de la asignación.

ARG_KEY
Parámetro de plantilla que especifica el tipo de valor clave.

key
La clave usada para recuperar el valor de la asignación.

Comentarios

Por tanto, solo se puede usar en el lado izquierdo de una instrucción de asignación (un valor-I). Si no hay ningún elemento de mapa con la clave especificada, se crea un nuevo elemento.

No hay ningún «lado derecho» (r-value) equivalente a este operador porque existe la posibilidad de que no se encuentre una clave en el mapa. Use la función miembro Lookup para la recuperación de elementos.

Ejemplo

Vea el ejemplo de CMap::Lookup.

CMap::PGetFirstAssoc

Devuelve la primera entrada del objeto de asignación.

const CPair* PGetFirstAssoc() const;
CPair* PGetFirstAssoc();

Valor devuelto

Un puntero a la primera entrada de la asignación; consulta CMap::CPair. Si el mapa no contiene entradas, el valor es NULL.

Comentarios

Llama a esta función para devolver un puntero al primer elemento del objeto de mapa.

Ejemplo

typedef CMap<int, int, CPoint, CPoint> CMyMap;
CMyMap myMap;

myMap.InitHashTable(257);

// Add 10 elements to the map.
for (int i = 0; i <= 10; i++)
   myMap.SetAt(i, CPoint(i, i));

// Print the element value with even key values.
int nKey = 0;
CPoint pt;
CMyMap::CPair *pCurVal;

pCurVal = myMap.PGetFirstAssoc();
while (pCurVal != NULL)
{
   if ((nKey % 2) == 0)
   {
      _tprintf_s(_T("Current key value at %d: %d,%d\n"),
                 pCurVal->key, pCurVal->value.x, pCurVal->value.y);
   }
   pCurVal = myMap.PGetNextAssoc(pCurVal);
   nKey++;
}

CMap::PGetNextAssoc

Recupera el elemento de mapa al que pAssocRec apunta.

const CPair *PGetNextAssoc(const CPair* pAssocRet) const;

CPair *PGetNextAssoc(const CPair* pAssocRet);

Parámetros

pAssocRet
Apunta a una entrada de mapa devuelta por una llamada PGetNextAssoc o CMap::PGetFirstAssoc anterior.

Valor devuelto

Un puntero a la siguiente entrada de la asignación; consulta CMap::CPair. Si el elemento es el último del mapa, el valor es NULL.

Comentarios

Llama a este método para recorrer en iteración todos los elementos del mapa. Recupera el primer elemento con una llamada a PGetFirstAssoc y, a continuación, recorra en iteración el mapa con llamadas sucesivas a PGetNextAssoc.

Ejemplo

Vea el ejemplo de CMap::PGetFirstAssoc.

CMap::PLookup

Encuentra el valor asignado a una clave determinada.

const CPair* PLookup(ARG_KEY key) const;
CPair* PLookup(ARG_KEY key);

Parámetros

key
Clave para el elemento que se va a buscar.

Valor devuelto

Un puntero a una estructura de clave; consulta CMap::CPair. Si no se encuentra ninguna coincidencia, CMap::PLookupdevuelve NULL.

Comentarios

Llama a este método para buscar un elemento de asignación con una clave que coincida exactamente con la clave especificada.

Ejemplo

typedef CMap<int, int, CPoint, CPoint> CMyMap;
CMyMap myMap;

myMap.InitHashTable(257);

// Add 10 elements to the map.
for (int i = 0; i <= 10; i++)
   myMap[i] = CPoint(i, i);

// Print the element values with even key values.
CMyMap::CPair *pCurVal;

for (int i = 0; i <= myMap.GetCount(); i += 2)
{
   pCurVal = myMap.PLookup(i);
   _tprintf_s(_T("Current key value at %d: %d,%d\n"),
              pCurVal->key, pCurVal->value.x, pCurVal->value.y);
}

CMap::RemoveAll

Quita todos los valores de este mapa llamando a la función auxiliar global DestructElements.

void RemoveAll();

Comentarios

La función funciona correctamente si la asignación ya está vacía.

Ejemplo

CMap<int, int, CPoint, CPoint> myMap;

// Add 10 elements to the map.
for (int i = 0; i < 10; i++)
   myMap.SetAt(i, CPoint(i, i));

myMap.RemoveAll();

ASSERT(myMap.IsEmpty());

CMap::RemoveKey

Busca la entrada de la asignación correspondiente a la clave proporcionada; después, si se encuentra la clave, se elimina la entrada.

BOOL RemoveKey(ARG_KEY key);

Parámetros

ARG_KEY
Parámetro de plantilla que especifica el tipo de clave.

key
Clave del elemento que se va a quitar.

Valor devuelto

Distinto de cero si la entrada se ha encontrado y se ha quitado correctamente; de lo contrario, 0.

Comentarios

La función auxiliar DestructElements se usa para quitar la entrada.

Ejemplo

Vea el ejemplo de CMap::SetAt.

CMap::SetAt

El medio principal para insertar un elemento en una asignación.

void SetAt(ARG_KEY key, ARG_VALUE newValue);

Parámetros

ARG_KEY
Parámetro de plantilla que especifica el tipo de los key parámetros.

key
Especifica el valor clave del elemento nuevo.

ARG_VALUE
Parámetro de plantilla que especifica el tipo de los newValue parámetros.

newValue
Especifica el valor del elemento nuevo.

Comentarios

En primer lugar, se busca la clave. Si se encuentra la clave, se cambia el valor correspondiente; de lo contrario, se crea un nuevo elemento clave-valor.

Ejemplo

CMap<int, int, CPoint, CPoint> myMap;

// Add 10 elements to the map.
for (int i = 0; i < 10; i++)
   myMap.SetAt(i, CPoint(i, i));

// Remove the elements with even key values.
POSITION pos = myMap.GetStartPosition();
int nKey;
CPoint pt;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, nKey, pt);

   if ((nKey % 2) == 0)
      myMap.RemoveKey(nKey);
}

// Print the element values.
pos = myMap.GetStartPosition();
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, nKey, pt);
   _tprintf_s(_T("Current key value at %d: %d,%d\n"),
              nKey, pt.x, pt.y);
}

Vea también

Ejemplo de MFCCOLLECT
CObject (clase)
Gráfico de jerarquías