Clase `CMap`

Artículo
10/12/2023

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

Compartir vía

Clase CMap

Sintaxis

Parámetros

Miembros

Estructuras públicas

Constructores públicos

Métodos públicos

Operadores públicos

Comentarios

Jerarquía de herencia

Requisitos

CMap::CMap

Parámetros

Comentarios

Ejemplo

CMap::CPair

Comentarios

Ejemplo

CMap::GetCount

Valor devuelto

Ejemplo

CMap::GetHashTableSize

Valor devuelto

Ejemplo

CMap::GetNextAssoc

Parámetros

Comentarios

Ejemplo

CMap::GetSize

Valor devuelto

Comentarios

Ejemplo

CMap::GetStartPosition

Valor devuelto

Comentarios

Ejemplo

CMap::InitHashTable

Parámetros

Comentarios

Ejemplo

CMap::IsEmpty

Valor devuelto

Ejemplo

CMap::Lookup

Parámetros

Valor devuelto

Comentarios

Ejemplo

CMap::operator [ ]

Parámetros

Comentarios

Ejemplo

CMap::PGetFirstAssoc

Valor devuelto

Comentarios

Ejemplo

CMap::PGetNextAssoc

Parámetros

Valor devuelto

Comentarios

Ejemplo

CMap::PLookup

Parámetros

Valor devuelto

Comentarios

Ejemplo

CMap::RemoveAll

Comentarios

Ejemplo

CMap::RemoveKey

Parámetros

Valor devuelto

Comentarios

Ejemplo

CMap::SetAt

Parámetros

Comentarios

Ejemplo

Vea también

Clase `CMap`

`CMap::CMap`

`CMap::CPair`

`CMap::GetCount`

`CMap::GetHashTableSize`

`CMap::GetNextAssoc`

`CMap::GetSize`

`CMap::GetStartPosition`

`CMap::InitHashTable`

`CMap::IsEmpty`

`CMap::Lookup`

`CMap::operator [ ]`

`CMap::PGetFirstAssoc`

`CMap::PGetNextAssoc`

`CMap::PLookup`

`CMap::RemoveAll`

`CMap::RemoveKey`

`CMap::SetAt`