Partilhar via


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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 aula