CAtlMap (clase)

Esta clase proporciona métodos para crear y administrar un objeto de mapa.

Sintaxis

template <typename K,
          typename V,
          class KTraits = CElementTraits<K>,
          class VTraits = CElementTraits<V>>
class CAtlMap

Parámetros

K
Tipo de elemento clave.

V
Tipo de elemento de valor.

KTraits
Código usado para copiar o mover elementos de clave. Consulte CElementTraits (clase) para más información.

VTraits
Código usado para copiar o mover elementos de valor.

Miembros

Definiciones de tipos públicas

Nombre	Descripción
CAtlMap::KINARGTYPE	Tipo usado cuando se pasa una clave como argumento de entrada
CAtlMap::KOUTARGTYPE	Tipo utilizado cuando se devuelve una clave como argumento de salida.
CAtlMap::VINARGTYPE	Tipo que se usa cuando se pasa un valor como argumento de entrada.
CAtlMap::VOUTARGTYPE	Tipo que se usa cuando se pasa un valor como argumento de salida.

Clases públicas

Nombre	Descripción
CAtlMap::CPair Class	Clase que contiene los elementos de clave y valor.

Miembros de datos de CPair

Nombre	Descripción
CPair::m_key	Miembro de datos que almacena el elemento clave.
CPair::m_value	Miembro de datos que almacena el elemento value.

Constructores públicos

Nombre	Descripción
CAtlMap::CAtlMap	Constructor .
CAtlMap::~CAtlMap	El destructor .

Métodos públicos

Nombre	Descripción
CAtlMap::AssertValid	Llame a este método para provocar un ASSERT si CAtlMap no es válido.
CAtlMap::DisableAutoRehash	Llame a este método para deshabilitar el rehashing automático del objeto CAtlMap.
CAtlMap::EnableAutoRehash	Llame a este método para habilitar el rehashing automático del objeto CAtlMap.
CAtlMap::GetAt	Llame a este método para devolver el elemento en una posición especificada del mapa.
CAtlMap::GetCount	Llame a este método para recuperar el número de elementos del mapa.
CAtlMap::GetHashTableSize	Llame a este método para determinar el número de contenedores de la tabla hash del mapa.
CAtlMap::GetKeyAt	Llame a este método para recuperar la clave almacenada en la posición especificada del objeto CAtlMap.
CAtlMap::GetNext	Llame a este método para obtener un puntero al siguiente par de elementos almacenado en el objeto CAtlMap.
CAtlMap::GetNextAssoc	Obtiene el siguiente elemento para iterar.
CAtlMap::GetNextKey	Llame a este método para recuperar la siguiente clave del objeto CAtlMap.
CAtlMap::GetNextValue	Llame a este método para obtener el siguiente valor del objeto CAtlMap.
CAtlMap::GetStartPosition	Llame a este método para iniciar una iteración de mapa.
CAtlMap::GetValueAt	Llame a este método para recuperar el valor almacenado en una posición determinada del objeto CAtlMap.
CAtlMap::InitHashTable	Llame a este método para inicializar la tabla hash.
CAtlMap::IsEmpty	Llame a este método para probar un objeto de mapa vacío.
CAtlMap::Lookup	Llame a este método para buscar claves o valores en el objeto CAtlMap.
CAtlMap::Rehash	Llame a este método para volver a guardar el objeto CAtlMap.
CAtlMap::RemoveAll	Llame a este método para quitar todos los elementos del objeto CAtlMap.
CAtlMap::RemoveAtPos	Llame a este método para quitar el elemento en la posición especificada del objeto CAtlMap.
CAtlMap::RemoveKey	Llame a este método para quitar un elemento del objeto CAtlMap, dado la clave.
CAtlMap::SetAt	Llame a este método para insertar un par de elementos en el mapa.
CAtlMap::SetOptimalLoad	Llame a este método para establecer la carga óptima del objeto CAtlMap.
CAtlMap::SetValueAt	Llame a este método para cambiar el valor almacenado en una posición determinada del objeto CAtlMap.

Operadores públicos

Nombre	Descripción
CAtlMap::operator[]	Reemplaza o agrega un nuevo elemento a CAtlMap.

Comentarios

CAtlMap proporciona compatibilidad con una matriz de asignación de cualquier tipo dado, administrando una matriz desordenada de elementos clave y sus valores asociados. Los elementos (que constan de una clave y un valor) se almacenan mediante un algoritmo hash, lo que permite almacenar y recuperar de forma eficaz una gran cantidad de datos.

Los parámetros KTraits y VTraits son clases de rasgos que contienen cualquier código complementario necesario para copiar o mover elementos.

La clase CAtlMapCRBMap ofrece una alternativa a . CRBMap también almacena pares clave-valor, pero presenta características de rendimiento diferentes. El tiempo necesario para insertar un elemento, buscar una clave o eliminar una clave de un objeto CRBMap es de orden log(n), donde n es el número de elementos. Para CAtlMap, todas estas operaciones suelen tardar un tiempo constante, aunque los peores escenarios pueden ser de orden n. Por lo tanto, en un caso típico, CAtlMap es más rápido.

La otra diferencia entre CRBMap y CAtlMap se vuelve evidente al recorrer en iteración los elementos almacenados. En CRBMap, los elementos se visitan en un orden ordenado. En CAtlMap, los elementos no están ordenados y no se puede deducir ningún orden.

Cuando sea necesario almacenar un pequeño número de elementos, considere la posibilidad de usar la clase CSimpleMap en su lugar.

Para obtener más información, consulte Clases de colección en ATL.

Requisitos

Encabezado: atlcoll.h

CAtlMap::AssertValid

Llame a este método para provocar un ASSERT si el objeto CAtlMap no es válido.

void AssertValid() const;

Comentarios

En las compilaciones de depuración, este método provocará un ASSERT si el objeto CAtlMap no es válido.

Ejemplo

Vea el ejemplo de CAtlMap::CAtlMap.

CAtlMap::CAtlMap

Constructor .

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

Parámetros

nBins
Número de contenedores que proporcionan punteros a los elementos almacenados. Vea comentarios más adelante en este tema para obtener una explicación de los contenedores.

fOptimalLoad
Relación de carga óptima.

fLoThreshold
Umbral inferior para la relación de carga.

fHiThreshold
Umbral superior de la relación de carga.

nBlockSize
Tamaño del bloque.

Comentarios

CAtlMap hace referencia a todos sus elementos almacenados creando primero un índice mediante un algoritmo hash en la clave. Este índice hace referencia a un "bin" que contiene un puntero a los elementos almacenados. Si el contenedor ya está en uso, se crea una lista vinculada para acceder a los elementos posteriores. Recorrer una lista es más lento que acceder directamente al elemento correcto, por lo que la estructura del mapa debe equilibrar los requisitos de almacenamiento con respecto al rendimiento. Se han elegido los parámetros predeterminados para dar buenos resultados en la mayoría de los casos.

La relación de carga es la proporción del número de contenedores con el número de elementos almacenados en el objeto de mapa. Cuando se vuelve a calcular la estructura del mapa, se usará el valor del parámetro fOptimalLoad para calcular el número de contenedores necesarios. Este valor se puede cambiar mediante el método CAtlMap::SetOptimalLoad .

El parámetro fLoThreshold es el valor inferior que puede alcanzar la relación de carga antes CAtlMap de volver a calcular el tamaño óptimo del mapa.

El parámetro fHiThreshold es el valor superior que puede alcanzar la relación de carga antes de que el objeto CAtlMap recalcule el tamaño óptimo del mapa.

Este proceso de recálculo (conocido como "rehashing") está habilitado de forma predeterminada. Si desea deshabilitar este proceso, quizás al escribir una gran cantidad de datos a la vez, llame al método CAtlMap::D isableAutoRehash. Vuelva a activarlo con el método CAtlMap::EnableAutoRehash.

El parámetro nBlockSize es una medida de la cantidad de memoria asignada cuando se requiere un nuevo elemento. Los tamaños de bloque más grandes reducen las llamadas a rutinas de asignación de memoria, pero usan más recursos.

Antes de que se puedan almacenar datos, es necesario inicializar la tabla hash con una llamada a CAtlMap::InitHashTable.

Ejemplo

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

CAtlMap::~CAtlMap

El destructor .

~CAtlMap() throw();

Comentarios

Libera los recursos asignados.

CAtlMap::CPair (Clase)

Clase que contiene los elementos de clave y valor.

class CPair : public __POSITION

Comentarios

Los métodos CAtlMap::GetNext y CAtlMap::Lookup usan esta clase para tener acceso a los elementos de clave y valor almacenados en la estructura de asignación.

CAtlMap::DisableAutoRehash

Llame a este método para deshabilitar el rehashing automático del objeto CAtlMap.

void DisableAutoRehash() throw();

Comentarios

Cuando se habilita el rehash automático (que es de forma predeterminada), el número de contenedores de la tabla hash se volverá a calcular automáticamente si el valor de carga (la relación del número de contenedores con el número de elementos almacenados en la matriz) supera los valores máximos o mínimos especificados en el momento en que se creó el mapa.

DisableAutoRehash es más útil cuando se agregará un gran número de elementos al mapa a la vez. En lugar de desencadenar el proceso de rehashing cada vez que se superan los límites, es más eficaz llamar a DisableAutoRehash, agregar los elementos y, por último, llamar a CAtlMap::EnableAutoRehash.

CAtlMap::EnableAutoRehash

Llame a este método para habilitar el rehashing automático del objeto CAtlMap.

void EnableAutoRehash() throw();

Comentarios

Cuando se habilita el rehash automático (que es de forma predeterminada), el número de contenedores de la tabla hash se volverá a calcular automáticamente si el valor de carga (la relación del número de contenedores con el número de elementos almacenados en la matriz) supera los valores máximos o mínimos especificados en el momento en que se crea el mapa.

EnableAutoRefresh suele usarse después de una llamada a CAtlMap::D isableAutoRehash.

CAtlMap::GetAt

Llame a este método para devolver el elemento en una posición especificada del mapa.

void GetAt(
    POSITION pos,
    KOUTARGTYPE key,
    VOUTARGTYPE value) const;

CPair* GetAt(POSITION& pos) throw();

Parámetros

pos
Contador de posición, devuelto por una llamada anterior a CAtlMap::GetNextAssoc o CAtlMap::GetStartPosition.

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

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

Valor devuelto

Devuelve un puntero al par actual de elementos clave-valor almacenados en el mapa.

Comentarios

En las compilaciones de depuración, se producirá un error de aserción si pos es igual a NULL.

CAtlMap::GetCount

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

size_t GetCount() const throw();

Valor devuelto

Devuelve el número de elementos del objeto de mapa. Un único elemento es un par clave-valor.

Ejemplo

Vea el ejemplo de CAtlMap::CAtlMap.

CAtlMap::GetHashTableSize

Llame a este método para determinar el número de contenedores de la tabla hash del mapa.

UINT GetHashTableSize() const throw();

Valor devuelto

Devuelve el número de rangos de la tabla de hash. Vea CAtlMap::CAtlMap para ver una explicación.

CAtlMap::GetKeyAt

Llame a este método para recuperar la clave almacenada en la posición especificada del objeto CAtlMap.

const K& GetKeyAt(POSITION pos) const throw();

Parámetros

pos
Contador de posición, devuelto por una llamada anterior a CAtlMap::GetNextAssoc o CAtlMap::GetStartPosition.

Valor devuelto

Devuelve una referencia a la clave almacenada en la posición especificada del objeto CAtlMap.

Ejemplo

Vea el ejemplo de CAtlMap::CAtlMap.

CAtlMap::GetNext

Llame a este método para obtener un puntero al siguiente par de elementos almacenado en el objeto CAtlMap.

CPair* GetNext(POSITION& pos) throw();
const CPair* GetNext(POSITION& pos) const throw();

Parámetros

pos
Contador de posición, devuelto por una llamada anterior a CAtlMap::GetNextAssoc o CAtlMap::GetStartPosition.

Valor devuelto

Devuelve un puntero al siguiente par de elementos clave-valor almacenados en el mapa. El contador de posición pos se actualiza después de cada llamada. Si el elemento recuperado es el último del mapa, pos se establece en NULL.

CAtlMap::GetNextAssoc

Obtiene el siguiente elemento para iterar.

void GetNextAssoc(
    POSITION& pos,
    KOUTARGTYPE key,
    VOUTARGTYPE value) const;

Parámetros

pos
Contador de posición, devuelto por una llamada anterior a CAtlMap::GetNextAssoc o CAtlMap::GetStartPosition.

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

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

Comentarios

El contador de posición pos se actualiza después de cada llamada. Si el elemento recuperado es el último del mapa, pos se establece en NULL.

CAtlMap::GetNextKey

Llame a este método para recuperar la siguiente clave del objeto CAtlMap.

const K& GetNextKey(POSITION& pos) const throw();

Parámetros

pos
Contador de posición, devuelto por una llamada anterior a CAtlMap::GetNextAssoc o CAtlMap::GetStartPosition.

Valor devuelto

Devuelve una referencia a la siguiente clave del mapa.

Comentarios

Novedades el contador de posición actual, pos. Si no hay más entradas en el mapa, el contador de posición se establece en NULL.

CAtlMap::GetNextValue

Llame a este método para obtener el siguiente valor del objeto CAtlMap.

V& GetNextValue(POSITION& pos) throw();
const V& GetNextValue(POSITION& pos) const throw();

Parámetros

pos
Contador de posición, devuelto por una llamada anterior a CAtlMap::GetNextAssoc o CAtlMap::GetStartPosition.

Valor devuelto

Devuelve una referencia al siguiente valor del mapa.

Comentarios

Novedades el contador de posición actual, pos. Si no hay más entradas en el mapa, el contador de posición se establece en NULL.

Ejemplo

Vea el ejemplo de CAtlMap::CAtlMap.

CAtlMap::GetStartPosition

Llame a este método para iniciar una iteración de mapa.

POSITION GetStartPosition() const throw();

Valor devuelto

Devuelve la posición inicial o NULL se devuelve si el mapa está vacío.

Comentarios

Llame a este método para iniciar una iteración de mapa devolviendo un valor POSITION que se puede pasar al método GetNextAssoc.

Nota:

La secuencia de iteración no es predecible

Ejemplo

Vea el ejemplo de CAtlMap::CAtlMap.

CAtlMap::GetValueAt

Llame a este método para recuperar el valor almacenado en una posición determinada del objeto CAtlMap.

V& GetValueAt(POSITION pos) throw();
const V& GetValueAt(POSITION pos) const throw();

Parámetros

pos
Contador de posición, devuelto por una llamada anterior a CAtlMap::GetNextAssoc o CAtlMap::GetStartPosition.

Valor devuelto

Devuelve una referencia al valor almacenado en la posición especificada del objeto CAtlMap.

CAtlMap::InitHashTable

Llame a este método para inicializar la tabla hash.

bool InitHashTable(
    UINT nBins,
    bool bAllocNow = true);

Parámetros

nBins
Número de rangos usados por la tabla hash. Vea CAtlMap::CAtlMap para ver una explicación.

bAllocNow
Indicación de marca cuando se debe asignar memoria.

Valor devuelto

Devuelve TRUE en la inicialización correcta, FALSE en caso de error.

Comentarios

InitHashTable debe llamarse antes de que los elementos se almacenen en la tabla hash. Si no se llama explícitamente a este método, se llamará automáticamente la primera vez que se agregue un elemento mediante el recuento de intervalos especificado por el constructor CAtlMap. De lo contrario, el mapa se inicializará con el nuevo recuento de intervalos especificado por el parámetro nBins.

Si el parámetro bAllocNow es false, la memoria requerida por la tabla hash no se asignará hasta que sea necesaria por primera vez. Esto puede ser útil si no se sabe si se usará el mapa.

Ejemplo

Vea el ejemplo de CAtlMap::CAtlMap.

CAtlMap::IsEmpty

Llame a este método para probar un objeto de mapa vacío.

bool IsEmpty() const throw();

Valor devuelto

Devuelve TRUE si el mapa está vacío; si no, FALSE.

CAtlMap::KINARGTYPE

Tipo usado cuando se pasa una clave como argumento de entrada.

typedef KTraits::INARGTYPE KINARGTYPE;

CAtlMap::KOUTARGTYPE

Tipo utilizado cuando se devuelve una clave como argumento de salida.

typedef KTraits::OUTARGTYPE KOUTARGTYPE;

CAtlMap::Lookup

Llame a este método para buscar claves o valores en el objeto CAtlMap.

bool Lookup(KINARGTYPE key, VOUTARGTYPE value) const;
const CPair* Lookup(KINARGTYPE key) const throw();
CPair* Lookup(KINARGTYPE key) throw();

Parámetros

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

value
Variable que recibe el valor buscado.

Valor devuelto

La primera forma del método devuelve true si se encuentra la clave; si no, false. Los formularios segundo y tercero devuelven un puntero a un CPair que se puede usar como una posición para las llamadas a CAtlMap::GetNext, etc.

Comentarios

Lookup usa un algoritmo hash para buscar rápidamente el elemento de mapa que contiene una clave que coincide exactamente con el parámetro de clave especificado.

CAtlMap::operator []

Reemplaza o agrega un nuevo elemento a CAtlMap.

V& operator[](kinargtype key) throw();

Parámetros

key
Clave del elemento que se va a agregar.

Valor devuelto

Devuelve una referencia al valor asociado a la clave especificada.

Ejemplo

Si la clave ya existe, se reemplaza el elemento. Si la clave no existe, se agrega un nuevo elemento. Vea el ejemplo de CAtlMap::CAtlMap.

CAtlMap::Rehash

Llame a este método para volver a guardar el objeto CAtlMap.

void Rehash(UINT nBins = 0);

Parámetros

nBins
Nuevo número de contenedores que se van a usar en la tabla hash. Vea CAtlMap::CAtlMap para ver una explicación.

Comentarios

Si nBins es 0, CAtlMap calcula un número razonable en función del número de elementos del mapa y de la configuración de carga óptima. Normalmente, el proceso de rehashing es automático, pero si se ha llamado a CAtlMap::D isableAutoRehash, este método realizará el cambio de tamaño necesario.

CAtlMap::RemoveAll

Llame a este método para quitar todos los elementos del objeto CAtlMap.

void RemoveAll() throw();

Comentarios

Borra el objeto CAtlMap, liberando la memoria usada para almacenar los elementos.

CAtlMap::RemoveAtPos

Llame a este método para quitar el elemento en la posición especificada del objeto CAtlMap.

void RemoveAtPos(POSITION pos) throw();

Parámetros

pos
Contador de posición, devuelto por una llamada anterior a CAtlMap::GetNextAssoc o CAtlMap::GetStartPosition.

Comentarios

Quita el par clave-valor almacenado en la posición especificada. La memoria usada para almacenar el elemento se libera. La posición a la que hace referencia pos no es válida y, mientras que position de cualquier otro elemento del mapa sigue siendo válida, no conservan necesariamente el mismo orden.

CAtlMap::RemoveKey

Llame a este método para quitar un elemento del objeto CAtlMap, dado la clave.

bool RemoveKey(KINARGTYPE key) throw();

Parámetros

key
Clave correspondiente al par de elementos que desea quitar.

Valor devuelto

Devuelve TRUE si se encuentra y se quita la clave, FALSE en caso de error.

Ejemplo

Vea el ejemplo de CAtlMap::CAtlMap.

CAtlMap::SetAt

Llame a este método para insertar un par de elementos en el mapa.

POSITION SetAt(
    KINARGTYPE key,
    VINARGTYPE value);

Parámetros

key
Valor de clave que se va a agregar al objeto CAtlMap.

value
Valor del objeto que se va a agregar a CAtlMap.

Valor devuelto

Devuelve la posición del par de elementos clave-valor del objeto CAtlMap.

Comentarios

SetAt reemplaza un elemento existente si se encuentra una clave coincidente. Si no se encuentra la clave, se crea un nuevo par clave-valor.

CAtlMap::SetOptimalLoad

Llame a este método para establecer la carga óptima del objeto CAtlMap.

void SetOptimalLoad(
    float fOptimalLoad,
    float fLoThreshold,
    float fHiThreshold,
    bool bRehashNow = false);

Parámetros

fOptimalLoad
Relación de carga óptima.

fLoThreshold
Umbral inferior para la relación de carga.

fHiThreshold
Umbral superior de la relación de carga.

bRehashNow
Marca que indica si se debe volver a calcular la tabla hash.

Comentarios

Este método vuelve a definir el valor de carga óptimo para el objeto CAtlMap. Vea CAtlMap::CAtlMap para obtener una explicación de los distintos parámetros. Si bRehashNow es true y el número de elementos está fuera de los valores mínimo y máximo, se vuelve a calcular la tabla hash.

CAtlMap::SetValueAt

Llame a este método para cambiar el valor almacenado en una posición determinada del objeto CAtlMap.

void SetValueAt(
    POSITION pos,
    VINARGTYPE value);

Parámetros

pos
Contador de posición, devuelto por una llamada anterior a CAtlMap::GetNextAssoc o CAtlMap::GetStartPosition.

value
Valor del objeto que se va a agregar a CAtlMap.

Comentarios

Cambia el elemento de valor almacenado en la posición especificada del objeto CAtlMap.

CAtlMap::VINARGTYPE

Tipo que se usa cuando se pasa un valor como argumento de entrada.

typedef VTraits::INARGTYPE VINARGTYPE;

CAtlMap::VOUTARGTYPE

Tipo que se usa cuando se pasa un valor como argumento de salida.

typedef VTraits::OUTARGTYPE VOUTARGTYPE;

CAtlMap::CPair::m_key

Miembro de datos que almacena el elemento clave.

const K m_key;

Parámetros

K
Tipo de elemento clave.

CAtlMap::CPair::m_value

Miembro de datos que almacena el elemento value.

V  m_value;

Parámetros

V
Tipo de elemento de valor.

Consulte también

Ejemplo de marquesina
UpdatePV Sample
Información general sobre la clase