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 CAtlMap
CRBMap 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