Classe CAtlMap
Essa classe fornece métodos para criar e gerenciar um objeto de mapa.
Sintaxe
template <typename K,
typename V,
class KTraits = CElementTraits<K>,
class VTraits = CElementTraits<V>>
class CAtlMap
Parâmetros
K
O tipo de elemento key.
V
O tipo de elemento valor.
KTraits
O código usado para copiar ou mover elementos de chave. Confira a classe CElementTraits para obter mais detalhes.
VTraits
O código usado para copiar ou mover elementos valor.
Membros
Typedefs públicos
| Nome | Descrição |
|---|---|
| CAtlMap::KINARGTYPE | O tipo usado quando uma chave é passada como um argumento de entrada |
| CAtlMap::KOUTARGTYPE | O tipo usado quando uma chave é retornada como um argumento de saída. |
| CAtlMap::VINARGTYPE | O tipo usado quando um valor é passado como um argumento de entrada. |
| CAtlMap::VOUTARGTYPE | O tipo usado quando um valor é passado como um argumento de saída. |
Classes públicas
| Nome | Descrição |
|---|---|
| CAtlMap::CPair Class | Uma classe que contém os elementos key e value. |
Membros de dados do CPair
| Nome | Descrição |
|---|---|
| CPair::m_key | O membro de dados que armazena o elemento key. |
| CPair::m_value | O membro de dados que armazena o elemento value. |
Construtores públicos
| Nome | Descrição |
|---|---|
| CAtlMap::CAtlMap | O construtor . |
| CAtlMap::~CAtlMap | O destruidor. |
Métodos públicos
| Nome | Descrição |
|---|---|
| CAtlMap::AssertValid | Chame esse método para causar um ASSERT caso o valor CAtlMap não seja válido. |
| CAtlMap::DisableAutoRehash | Chame esse método para desabilitar o redirecionamento automático do objeto CAtlMap. |
| CAtlMap::EnableAutoRehash | Chame esse método para habilitar o redirecionamento automático do objeto CAtlMap. |
| CAtlMap::GetAt | Chame esse método para retornar o elemento a uma posição especificada no mapa. |
| CAtlMap::GetCount | Chame esse método para recuperar o número de elementos no mapa. |
| CAtlMap::GetHashTableSize | Chame esse método para determinar o número de compartimentos na tabela de hash do mapa. |
| CAtlMap::GetKeyAt | Chame esse método para recuperar a chave armazenada na posição determinada no objeto CAtlMap. |
| CAtlMap::GetNext | Chame esse método para obter um ponteiro para o próximo par de elementos armazenado no objeto CAtlMap. |
| CAtlMap::GetNextAssoc | Obtém o próximo elemento para iteração. |
| CAtlMap::GetNextKey | Chame esse método para recuperar a próxima chave do objeto CAtlMap. |
| CAtlMap::GetNextValue | Chame esse método para obter o próximo valor do objeto CAtlMap. |
| CAtlMap::GetStartPosition | Chame esse método para iniciar uma iteração de mapa. |
| CAtlMap::GetValueAt | Chame esse método para recuperar o valor armazenado em uma determinada posição no objeto CAtlMap. |
| CAtlMap::InitHashTable | Chame esse método para inicializar a tabela de hash. |
| CAtlMap::IsEmpty | Chame esse método para testar um objeto de mapa vazio. |
| CAtlMap::Lookup | Chame esse método para pesquisar chaves ou valores no objeto CAtlMap. |
| CAtlMap::Rehash | Chame esse método para um novo hash do objeto CAtlMap. |
| CAtlMap::RemoveAll | Chame esse método para remover todos os elementos do objeto CAtlMap. |
| CAtlMap::RemoveAtPos | Chame esse método para remover o elemento na posição determinada no objeto CAtlMap. |
| CAtlMap::RemoveKey | Chame esse método para remover um elemento do objeto CAtlMap, dada a chave. |
| CAtlMap::SetAt | Chame esse método para inserir um par de elementos no mapa. |
| CAtlMap::SetOptimalLoad | Chame esse método para definir a carga ideal do objeto CAtlMap. |
| CAtlMap::SetValueAt | Chame esse método para alterar o valor armazenado em uma determinada posição no objeto CAtlMap. |
Operadores públicos
| Nome | Descrição |
|---|---|
| CAtlMap::operator[] | Substitui ou adiciona um novo elemento a CAtlMap. |
Comentários
O CAtlMap fornece suporte para uma matriz de mapeamento de qualquer tipo específico, gerenciando uma matriz não ordenada de elementos de chave e seus valores associados. Os elementos (compostos por uma chave e um valor) são armazenados usando um algoritmo de hash, permitindo que uma grande quantidade de dados seja armazenada e recuperada com eficiência.
Os parâmetros KTraits e VTraits são classes de características que contêm qualquer código suplementar necessário para copiar ou mover elementos.
Uma alternativa a CAtlMap é oferecida pela classe CRBMap. O CRBMap também armazena pares chave/valor, mas exibe características de desempenho diferentes. O tempo necessário para inserir um item, pesquisar uma chave ou excluir uma chave de um objeto CRBMap é da ordem log(n), em que n é o número de elementos. Para CAtlMap, todas essas operações normalmente levam um tempo constante, embora os piores cenários possam ser da ordem n. Portanto, em um caso típico, CAtlMap é mais rápido.
A outra diferença entre CRBMap e CAtlMap se torna aparente ao se fazer a iteração por meio dos elementos armazenados. Em um CRBMap, os elementos são visitados em uma ordem classificada. Em um CAtlMap, os elementos não são ordenados, e nenhuma ordem pode ser inferida.
Quando um pequeno número de elementos precisar ser armazenado, cogite usar a classe CSimpleMap.
Para obter mais informações, confira Classes de Coleção da ATL.
Requisitos
Cabeçalho: atlcoll.h
CAtlMap::AssertValid
Chame esse método para causar um ASSERT se o objeto CAtlMap não for válido.
void AssertValid() const;
Comentários
Em builds de depuração, esse método causará um ASSERT se o objeto CAtlMap não for válido.
Exemplo
Confira o exemplo de CAtlMap::CAtlMap.
CAtlMap::CAtlMap
O construtor .
CAtlMap(
UINT nBins = 17,
float fOptimalLoad = 0.75f,
float fLoThreshold = 0.25f,
float fHiThreshold = 2.25f,
UINT nBlockSize = 10) throw ();
Parâmetros
nBins
O número de compartimentos que fornecem ponteiros para os elementos armazenados. Confira a seção Comentários mais adiante neste tópico para obter uma explicação sobre os compartimentos.
fOptimalLoad
A taxa de carga ideal.
fLoThreshold
O limite inferior da taxa de carga.
fHiThreshold
O limite superior da taxa de carga.
nBlockSize
O tamanho do bloco.
Comentários
O CAtlMap referencia todos os seus elementos armazenados ao, primeiro, criar um índice usando um algoritmo de hash na chave. Esse índice faz referência a um “compartimento” que contém um ponteiro para os elementos armazenados. Se o compartimento já estiver em uso, uma lista vinculada será criada para acessar os elementos subsequentes. Percorrer uma lista é um processo mais lento do que acessar o elemento correto diretamente e, portanto, a estrutura do mapa precisa equilibrar os requisitos de armazenamento em relação ao desempenho. Os parâmetros padrão foram escolhidos para fornecer bons resultados na maioria dos casos.
A taxa de carga é a proporção entre o número de compartimentos e o número de elementos armazenados no objeto do mapa. Quando a estrutura do mapa for recalculada, o valor do parâmetro fOptimalLoad será usado para calcular o número de compartimentos necessários. Esse valor pode ser alterado usando o método CAtlMap::SetOptimalLoad.
O parâmetro fLoThreshold é o valor inferior que a taxa de carga pode alcançar antes de CAtlMap recalcular o tamanho ideal do mapa.
O parâmetro fHiThreshold é o valor superior que a taxa de carga pode alcançar antes de o objeto CAtlMap recalcular o tamanho ideal do mapa.
Esse processo de recálculo (conhecido como novo hash) é habilitado por padrão. Caso queira desabilitar esse processo, talvez ao inserir muitos dados ao mesmo tempo, chame o método CAtlMap::DisableAutoRehash. Reative com o método CAtlMap::EnableAutoRehash.
O parâmetro nBlockSize é uma medida da quantidade de memória alocada quando um novo elemento é necessário. Tamanhos de bloco maiores reduzem as chamadas às rotinas de alocação de memória, mas usam mais recursos.
Antes que qualquer dado possa ser armazenado, é necessário inicializar a tabela de hash com uma chamada para CAtlMap::InitHashTable.
Exemplo
// 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
O destruidor.
~CAtlMap() throw();
Comentários
Libera todos os recursos alocados.
CAtlMap::CPair Class
Uma classe que contém os elementos key e value.
class CPair : public __POSITION
Comentários
Essa classe é usada pelos métodos CAtlMap::GetNext e CAtlMap::Lookup para acessar os elementos de chave e valor armazenados na estrutura de mapeamento.
CAtlMap::DisableAutoRehash
Chame esse método para desabilitar o redirecionamento automático do objeto CAtlMap.
void DisableAutoRehash() throw();
Comentários
Quando o novo hash automático estiver habilitado (o que é feito por padrão), o número de compartimentos na tabela de hash será recalculado automaticamente se o valor de carga (a proporção entre o número de compartimentos e o número de elementos armazenados na matriz) exceder os valores máximos ou mínimos especificados no momento em que o mapa tiver sido criado.
O DisableAutoRehash é mais útil quando um grande número de elementos é adicionado ao mapa de uma só vez. Em vez de disparar o processo de redirecionamento sempre que os limites forem excedidos, é mais eficiente chamar DisableAutoRehash, adicionar os elementos e, por fim, chamar CAtlMap::EnableAutoRehash.
CAtlMap::EnableAutoRehash
Chame esse método para habilitar o redirecionamento automático do objeto CAtlMap.
void EnableAutoRehash() throw();
Comentários
Quando o novo hash automático estiver habilitado (o que é feito por padrão), o número de compartimentos na tabela de hash será recalculado automaticamente se o valor de carga (a proporção entre o número de compartimentos e o número de elementos armazenados na matriz) exceder os valores máximos ou mínimos especificados no momento em que o mapa tiver sido criado.
O EnableAutoRefresh é mais usado com mais frequência após uma chamada para CAtlMap::DisableAutoRehash.
CAtlMap::GetAt
Chame esse método para retornar o elemento a uma posição especificada no mapa.
void GetAt(
POSITION pos,
KOUTARGTYPE key,
VOUTARGTYPE value) const;
CPair* GetAt(POSITION& pos) throw();
Parâmetros
pos
O contador de posição, retornado por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.
chave
Parâmetro de modelo que especifica o tipo da chave do mapa.
value
Parâmetro de modelo que especifica o tipo do valor do mapa.
Valor de Devolução
Retorna um ponteiro para o par atual de elementos de chave/valor armazenados no mapa.
Comentários
Em builds de depuração, ocorrerá um erro de asserção se pos for igual a NULL.
CAtlMap::GetCount
Chame esse método para recuperar o número de elementos no mapa.
size_t GetCount() const throw();
Valor de Devolução
Retorna o número de elementos no objeto do mapa. Um único elemento é um par chave/valor.
Exemplo
Confira o exemplo de CAtlMap::CAtlMap.
CAtlMap::GetHashTableSize
Chame esse método para determinar o número de compartimentos na tabela de hash do mapa.
UINT GetHashTableSize() const throw();
Valor de Devolução
Retorna o número de compartimentos na tabela de hash. Confira CAtlMap::CAtlMap para obter uma explicação.
CAtlMap::GetKeyAt
Chame esse método para recuperar a chave armazenada na posição determinada no objeto CAtlMap.
const K& GetKeyAt(POSITION pos) const throw();
Parâmetros
pos
O contador de posição, retornado por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.
Valor de Devolução
Retorna uma referência à chave armazenada na posição determinada no objeto CAtlMap.
Exemplo
Confira o exemplo de CAtlMap::CAtlMap.
CAtlMap::GetNext
Chame esse método para obter um ponteiro para o próximo par de elementos armazenado no objeto CAtlMap.
CPair* GetNext(POSITION& pos) throw();
const CPair* GetNext(POSITION& pos) const throw();
Parâmetros
pos
O contador de posição, retornado por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.
Valor de Devolução
Retorna um ponteiro para o próximo par de elementos de chave/valor armazenados no mapa. O contador de posição pos é atualizado após cada chamada. Se o elemento recuperado for o último no mapa, pos será definido como NULL.
CAtlMap::GetNextAssoc
Obtém o próximo elemento para iteração.
void GetNextAssoc(
POSITION& pos,
KOUTARGTYPE key,
VOUTARGTYPE value) const;
Parâmetros
pos
O contador de posição, retornado por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.
chave
Parâmetro de modelo que especifica o tipo da chave do mapa.
value
Parâmetro de modelo que especifica o tipo do valor do mapa.
Comentários
O contador de posição pos é atualizado após cada chamada. Se o elemento recuperado for o último no mapa, pos será definido como NULL.
CAtlMap::GetNextKey
Chame esse método para recuperar a próxima chave do objeto CAtlMap.
const K& GetNextKey(POSITION& pos) const throw();
Parâmetros
pos
O contador de posição, retornado por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.
Valor de Devolução
Retorna uma referência à próxima chave no mapa.
Comentários
Atualiza o contador de posição atual pos. Se não houver mais entradas no mapa, o contador de posição será definido como NULL.
CAtlMap::GetNextValue
Chame esse método para obter o próximo valor do objeto CAtlMap.
V& GetNextValue(POSITION& pos) throw();
const V& GetNextValue(POSITION& pos) const throw();
Parâmetros
pos
O contador de posição, retornado por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.
Valor de Devolução
Retorna uma referência ao próximo valor no mapa.
Comentários
Atualiza o contador de posição atual pos. Se não houver mais entradas no mapa, o contador de posição será definido como NULL.
Exemplo
Confira o exemplo de CAtlMap::CAtlMap.
CAtlMap::GetStartPosition
Chame esse método para iniciar uma iteração de mapa.
POSITION GetStartPosition() const throw();
Valor de Devolução
Retorna a posição inicial, ou NULL será retornado se o mapa estiver vazio.
Comentários
Chame esse método para iniciar uma iteração de mapa retornando um valor POSITION que pode ser passado para o método GetNextAssoc.
Observação
A sequência de iteração não é previsível
Exemplo
Confira o exemplo de CAtlMap::CAtlMap.
CAtlMap::GetValueAt
Chame esse método para recuperar o valor armazenado em uma determinada posição no objeto CAtlMap.
V& GetValueAt(POSITION pos) throw();
const V& GetValueAt(POSITION pos) const throw();
Parâmetros
pos
O contador de posição, retornado por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.
Valor de Devolução
Retorna uma referência ao valor armazenado na posição determinada no objeto CAtlMap.
CAtlMap::InitHashTable
Chame esse método para inicializar a tabela de hash.
bool InitHashTable(
UINT nBins,
bool bAllocNow = true);
Parâmetros
nBins
O número de compartimentos usados pela tabela de hash. Confira CAtlMap::CAtlMap para obter uma explicação.
bAllocNow
Uma indicação de sinalizador de quando a memória deve ser alocada.
Valor de Devolução
Retorna TRUE em caso de inicialização com êxito e FALSE em caso de falha.
Comentários
O InitHashTable deve ser chamado antes que todos os elementos sejam armazenados na tabela de hash. Se esse método não for chamado explicitamente, ele será chamado automaticamente na primeira vez em que um elemento for adicionado usando a contagem de compartimentos especificada pelo construtor CAtlMap. Caso contrário, o mapa será inicializado usando a nova contagem de compartimentos especificada pelo parâmetro nBins.
Se o parâmetro bAllocNow for falso, a memória exigida pela tabela de hash não será alocada até que seja necessária pela primeira vez. Isso poderá ser útil se não for possível saber se o mapa será usado.
Exemplo
Confira o exemplo de CAtlMap::CAtlMap.
CAtlMap::IsEmpty
Chame esse método para testar um objeto de mapa vazio.
bool IsEmpty() const throw();
Valor de Devolução
Retornará TRUE se o mapa estiver vazio. Caso contrário, retornará FALSE.
CAtlMap::KINARGTYPE
O tipo usado quando uma chave é passada como um argumento de entrada.
typedef KTraits::INARGTYPE KINARGTYPE;
CAtlMap::KOUTARGTYPE
O tipo usado quando uma chave é retornada como um argumento de saída.
typedef KTraits::OUTARGTYPE KOUTARGTYPE;
CAtlMap::Lookup
Chame esse método para pesquisar chaves ou valores no objeto CAtlMap.
bool Lookup(KINARGTYPE key, VOUTARGTYPE value) const;
const CPair* Lookup(KINARGTYPE key) const throw();
CPair* Lookup(KINARGTYPE key) throw();
Parâmetros
chave
Especifica a chave que identifica o elemento a ser pesquisado.
value
Variável que recebe o valor pesquisado.
Valor de Devolução
A primeira forma do método retornará true se a chave for encontrada, caso contrário, false. O segundo e o terceiro formulários retornam um ponteiro para um CPair, que pode ser usado como uma posição para chamadas para CAtlMap::GetNext e assim por diante.
Comentários
O Lookup usa um algoritmo de hash para localizar rapidamente o elemento de mapa que contém uma chave que corresponde exatamente ao parâmetro de chave fornecido.
CAtlMap::operator []
Substitui ou adiciona um novo elemento a CAtlMap.
V& operator[](kinargtype key) throw();
Parâmetros
chave
A chave do elemento a ser adicionada ou substituída.
Valor de Devolução
Retorna uma referência ao valor associado à chave fornecida.
Exemplo
Se a chave já existir, o elemento será substituído. Se a chave não existir, um novo elemento será adicionado. Confira o exemplo de CAtlMap::CAtlMap.
CAtlMap::Rehash
Chame esse método para um novo hash do objeto CAtlMap.
void Rehash(UINT nBins = 0);
Parâmetros
nBins
O novo número de compartimentos a serem usados na tabela de hash. Confira CAtlMap::CAtlMap para obter uma explicação.
Comentários
Se nBins for 0, CAtlMap calculará um número razoável com base no número de elementos no mapa e na configuração de carga ideal. Normalmente, o processo de redirecionamento é automático, mas se CAtlMap::DisableAutoRehash tiver sido chamado, esse método executará o redimensionamento necessário.
CAtlMap::RemoveAll
Chame esse método para remover todos os elementos do objeto CAtlMap.
void RemoveAll() throw();
Comentários
Limpa o objeto CAtlMap, liberando a memória usada para armazenar os elementos.
CAtlMap::RemoveAtPos
Chame esse método para remover o elemento na posição determinada no objeto CAtlMap.
void RemoveAtPos(POSITION pos) throw();
Parâmetros
pos
O contador de posição, retornado por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.
Comentários
Remove o par key/value armazenado na posição especificada. A memória usada para armazenar o elemento é liberada. A POSITION referenciada pelo pos se torna inválida e, embora a POSITION de quaisquer outros elementos no mapa permaneça válida, elas não necessariamente mantêm a mesma ordem.
CAtlMap::RemoveKey
Chame esse método para remover um elemento do objeto CAtlMap, dada a chave.
bool RemoveKey(KINARGTYPE key) throw();
Parâmetros
chave
A chave correspondente ao par de elementos que você deseja remover.
Valor de Devolução
Retorna TRUE se a chave for encontrada e removida e FALSE no caso de falha.
Exemplo
Confira o exemplo de CAtlMap::CAtlMap.
CAtlMap::SetAt
Chame esse método para inserir um par de elementos no mapa.
POSITION SetAt(
KINARGTYPE key,
VINARGTYPE value);
Parâmetros
chave
O valor da chave a ser adicionado ao objeto CAtlMap.
value
O valor a ser adicionado ao objeto CAtlMap.
Valor de Devolução
Retorna a posição do par de elementos chave/valor no objeto CAtlMap.
Comentários
SetAt substitui um elemento existente se uma chave correspondente for encontrada. Se a chave não for encontrada, um novo par chave/valor será criado.
CAtlMap::SetOptimalLoad
Chame esse método para definir a carga ideal do objeto CAtlMap.
void SetOptimalLoad(
float fOptimalLoad,
float fLoThreshold,
float fHiThreshold,
bool bRehashNow = false);
Parâmetros
fOptimalLoad
A taxa de carga ideal.
fLoThreshold
O limite inferior da taxa de carga.
fHiThreshold
O limite superior da taxa de carga.
bRehashNow
Sinalizador indicando se a tabela de hash deve ser recalculada.
Comentários
Esse método redefine o valor de carga ideal para o objeto CAtlMap. Confira CAtlMap::CAtlMap para ver uma discussão sobre os diversos parâmetros. Se bRehashNow for true e o número de elementos estiver fora dos valores mínimo e máximo, a tabela de hash será recalculada.
CAtlMap::SetValueAt
Chame esse método para alterar o valor armazenado em uma determinada posição no objeto CAtlMap.
void SetValueAt(
POSITION pos,
VINARGTYPE value);
Parâmetros
pos
O contador de posição, retornado por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.
value
O valor a ser adicionado ao objeto CAtlMap.
Comentários
Altera o elemento de valor armazenado na posição determinada no objeto CAtlMap.
CAtlMap::VINARGTYPE
O tipo usado quando um valor é passado como um argumento de entrada.
typedef VTraits::INARGTYPE VINARGTYPE;
CAtlMap::VOUTARGTYPE
O tipo usado quando um valor é passado como um argumento de saída.
typedef VTraits::OUTARGTYPE VOUTARGTYPE;
CAtlMap::CPair::m_key
O membro de dados que armazena o elemento key.
const K m_key;
Parâmetros
K
O tipo de elemento key.
CAtlMap::CPair::m_value
O membro de dados que armazena o elemento value.
V m_value;
Parâmetros
V
O tipo de elemento valor.
Confira também
Amostra de letreiro
Amostra de UpdatePV
Visão geral da classe
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários