Classe CAtlMap

Esta classe fornece métodos para criar e gerir 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-chave.

V
O tipo de elemento valor.

KTraits
O código usado para copiar ou mover elementos-chave. Consulte a Classe CElementTraits para mais detalhes.

VTraits
O código usado para copiar ou mover elementos de valor.

Membros

Definições de Tipos Públicas

Aulas Públicas

Membros de Dados CPair

Construtores Públicos

Métodos Públicos

Operadores Públicos

Observações

CAtlMap fornece suporte para um array de mapeamento de qualquer tipo, gerindo um array não ordenado de elementos-chave e os seus valores associados. Os elementos (constituídos por uma chave e um valor) são armazenados através de um algoritmo de hash, permitindo que uma grande quantidade de dados seja armazenada e recuperada de forma eficiente.

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 CAtlMap é oferecida pela classe CRBMap . CRBMap também armazena pares chave/valor, mas apresenta características de desempenho diferentes. O tempo necessário para inserir um item, procurar uma chave ou eliminar uma chave de um CRBMap objeto é de ordem log(n), onde n é o número de elementos. Para CAtlMap, todas estas operações normalmente demoram um tempo constante, embora os piores cenários possam ser da ordem n. Portanto, num caso típico, CAtlMap é mais rápido.

A outra diferença entre CRBMap e CAtlMap torna-se evidente ao iterar pelos elementos armazenados. Num CRBMap, os elementos são visitados por ordem ordenada. Num CAtlMap, os elementos não estão ordenados, e nenhuma ordem pode ser inferida.

Quando um pequeno número de elementos precisa de ser armazenado, considere usar a classe CSimpleMap em vez disso.

Para mais informações, consulte Aulas de Coleção ATL.

Requerimentos

Cabeçalho: atlcoll.h

CAtlMap::AssertValid

Chame este método para causar um ASSERT se o CAtlMap objeto não for válido.

void AssertValid() const;

Observações

Em builds de depuração, este método causará um ASSERT se o CAtlMap objeto não for válido.

Example

Veja o exemplo do 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 bins que fornecem ponteiros para os elementos armazenados. Veja Observações mais adiante neste tópico para uma explicação sobre contentores.

fOptimalLoad
A relação de carga ideal.

fLoThreshold
O limiar inferior para a relação de carga.

fHiThreshold
O limiar superior para a relação de carga.

nBlockSize
O tamanho do bloco.

Observações

CAtlMap referencia-se todos os seus elementos armazenados criando primeiro um índice usando um algoritmo de hash na chave. Este índice refere-se a um "bin" que contém um ponteiro para os elementos armazenados. Se o bin já estiver em uso, é criada uma lista ligada para aceder aos elementos subsequentes. Percorrer uma lista é mais lento do que aceder diretamente ao elemento correto, pelo que a estrutura do mapa precisa de equilibrar os requisitos de armazenamento com o desempenho. Os parâmetros padrão foram escolhidos para dar bons resultados na maioria dos casos.

A razão de carga é a razão entre o número de bins e o número de elementos armazenados no objeto do mapa. Quando a estrutura do mapa é recalculada, o valor do parâmetro fOptimalLoad será usado para calcular o número de bins necessários. Este valor pode ser alterado usando o método CAtlMap::SetOptimalLoad .

O parâmetro fLoThreshold é o valor mais baixo que a razão de carga pode atingir antes CAtlMap de recalcular o tamanho ótimo do mapa.

O parâmetro fHiThreshold é o valor superior que a razão de carga pode atingir antes de o CAtlMap objeto recalcular o tamanho ótimo do mapa.

Este processo de recálculo (conhecido como rehashing) é ativado por defeito. Se quiser desativar este processo, talvez ao introduzir muitos dados de uma só vez, chame o método CAtlMap::D isableAutoRehash . Reative-o com o método CAtlMap::EnableAutoRehash .

O parâmetro nBlockSize é uma medida da quantidade de memória alocada quando um novo elemento é necessário. Blocos maiores reduzem chamadas para rotinas de alocação de memória, mas consomem mais recursos.

Antes de qualquer dado poder ser armazenado, é necessário inicializar a tabela de hash com uma chamada para CAtlMap::InitHashTable.

Example

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

Observações

Liberta quaisquer recursos alocados.

CAtlMap::CPair Class

Uma classe que contém os elementos chave e valor.

class CPair : public __POSITION

Observações

Esta classe é utilizada pelos métodos CAtlMap::GetNext e CAtlMap::Lookup para aceder aos elementos-chave e valor armazenados na estrutura de mapeamento.

CAtlMap::D isableAutoRehash

Chame este método para desativar a reciclagem automática do CAtlMap objeto.

void DisableAutoRehash() throw();

Observações

Quando o rehashing automático é ativado (o que é por defeito), o número de bins na tabela de hash será automaticamente recalculado se o valor de carga (a razão entre o número de bins e o número de elementos armazenados no array) exceder os valores máximos ou mínimos especificados na altura em que o mapa foi criado.

DisableAutoRehash é mais útil quando um grande número de elementos será adicionado ao mapa ao mesmo tempo. Em vez de desencadear o processo de rehashing sempre que os limites são ultrapassados, é mais eficiente chamar DisableAutoRehash, adicionar os elementos e, finalmente, chamar CAtlMap::EnableAutoRehash.

CAtlMap::EnableAutoRehash

Chame este método para permitir a reciclagem automática do CAtlMap objeto.

void EnableAutoRehash() throw();

Observações

Quando o rehashing automático está ativado (o que é por defeito), o número de bins na tabela de hash será automaticamente recalculado se o valor de carga (a razão entre o número de bins e o número de elementos armazenados no array) exceder os valores máximos ou mínimos especificados no momento em que o mapa é criado.

EnableAutoRefresh é mais frequentemente usado após uma chamada para CAtlMap::D isableAutoRehash.

CAtlMap::GetAt

Chame este método para devolver o elemento numa posição especificada no mapa.

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

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

Parâmetros

Ponto de venda
O contador de posição, devolvido por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.

chave
Parâmetro template que especifica o tipo da chave do mapa.

value
Parâmetro modelo que especifica o tipo de valor do mapa.

Valor de retorno

Devolve um ponteiro para o par atual de elementos chave/valor armazenados no mapa.

Observações

Em builds de depuração, ocorrerá um erro de asserção se pos for igual a NULL.

CAtlMap::GetCount

Chame este método para recuperar o número de elementos no mapa.

size_t GetCount() const throw();

Valor de retorno

Devolve o número de elementos no objeto do mapa. Um único elemento é um par chave/valor.

Example

Veja o exemplo do CAtlMap::CAtlMap.

CAtlMap::GetHashTableSize

Chame este método para determinar o número de bins na tabela de hash do mapa.

UINT GetHashTableSize() const throw();

Valor de retorno

Devolve o número de bins na tabela hash. Veja CAtlMap::CAtlMap para uma explicação.

CAtlMap::GetKeyAt

Chame este método para recuperar a chave armazenada na posição dada no CAtlMap objeto.

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

Parâmetros

Ponto de venda
O contador de posição, devolvido por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.

Valor de retorno

Devolve uma referência à chave armazenada na posição dada no CAtlMap objeto.

Example

Veja o exemplo do CAtlMap::CAtlMap.

CAtlMap::GetNext

Chame este método para obter um ponteiro para o próximo par de elementos armazenado no CAtlMap objeto.

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

Parâmetros

Ponto de venda
O contador de posição, devolvido por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.

Valor de retorno

Devolve um ponteiro para o próximo par de elementos-chave/valor armazenados no mapa. O contador de posições pos é atualizado após cada chamada. Se o elemento recuperado for o último no mapa, pos é 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

Ponto de venda
O contador de posição, devolvido por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.

chave
Parâmetro template que especifica o tipo da chave do mapa.

value
Parâmetro modelo que especifica o tipo de valor do mapa.

Observações

O contador de posições pos é atualizado após cada chamada. Se o elemento recuperado for o último no mapa, pos é definido como NULL.

CAtlMap::GetNextKey

Chame este método para recuperar a próxima chave do CAtlMap objeto.

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

Parâmetros

Ponto de venda
O contador de posição, devolvido por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.

Valor de retorno

Devolve uma referência à próxima tecla no mapa.

Observações

Atualiza o contador de posição atual, pos. Se não houver mais entradas no mapa, o contador de posição é definido como NULL.

CAtlMap::GetNextValue

Chame este método para obter o valor seguinte do CAtlMap objeto.

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

Parâmetros

Ponto de venda
O contador de posição, devolvido por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.

Valor de retorno

Devolve uma referência ao valor seguinte no mapa.

Observações

Atualiza o contador de posição atual, pos. Se não houver mais entradas no mapa, o contador de posição é definido como NULL.

Example

Veja o exemplo do CAtlMap::CAtlMap.

CAtlMap::GetStartPosition

Chame este método para iniciar uma iteração de mapa.

POSITION GetStartPosition() const throw();

Valor de retorno

Devolve a posição inicial, ou NULL é devolvido se o mapa estiver vazio.

Observações

Chame este método para iniciar uma iteração de mapeamento, retornando um valor POSITION que pode ser passado ao GetNextAssoc método.

Example

Veja o exemplo do CAtlMap::CAtlMap.

CAtlMap::GetValueAt

Chame este método para recuperar o valor armazenado numa posição dada no CAtlMap objeto.

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

Parâmetros

Ponto de venda
O contador de posição, devolvido por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.

Valor de retorno

Devolve uma referência ao valor armazenado na posição dada no CAtlMap objeto.

CAtlMap::InitHashTable

Chame este método para inicializar a tabela de hash.

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

Parâmetros

nBins
O número de bins usados pela tabela de hash. Veja CAtlMap::CAtlMap para uma explicação.

bAllocNow
Uma indicação de indicação de quando a memória deve ser alocada.

Valor de retorno

Retorna TRUE na inicialização bem-sucedida, FALSE na falha.

Observações

InitHashTable deve ser chamado antes de quaisquer elementos serem armazenados na tabela de hash. Se este método não for chamado explicitamente, será chamado automaticamente na primeira vez que um elemento for adicionado usando a contagem de bins especificada pelo CAtlMap construtor. Caso contrário, o mapa será inicializado usando a nova contagem de bins 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é ser inicialmente exigida. Isto pode ser útil se não houver certeza se o mapa será utilizado.

Example

Veja o exemplo do CAtlMap::CAtlMap.

CAtlMap::IsEmpty

Chame este método para testar um objeto de mapa vazio.

bool IsEmpty() const throw();

Valor de retorno

Retorna TRUE se o mapa estiver vazio, FALSE caso contrário.

CAtlMap::KINARGTYPE

Tipo usado quando uma chave é passada como argumento de entrada.

typedef KTraits::INARGTYPE KINARGTYPE;

CAtlMap::KOUTARGTYPE

Tipo usado quando uma chave é devolvida como argumento de saída.

typedef KTraits::OUTARGTYPE KOUTARGTYPE;

CAtlMap::Procurar

Chame este método para procurar chaves ou valores no CAtlMap objeto.

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 consultar.

value
Variável que recebe o valor consultado.

Valor de retorno

A primeira forma do método retorna verdadeira se a chave for encontrada, caso contrário falsa. A segunda e terceira formas retornam um ponteiro para um CPair que pode ser usado como posição para chamadas para CAtlMap::GetNext e assim sucessivamente.

Observações

Lookup utiliza um algoritmo de hash para encontrar rapidamente o elemento de mapa que contém uma chave que corresponde exatamente ao parâmetro de chave dado.

CAtlMap::operator []

Substitui ou adiciona um novo elemento ao CAtlMap.

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

Parâmetros

chave
A chave do elemento a adicionar ou substituir.

Valor de retorno

Devolve uma referência ao valor associado à chave dada.

Example

Se a chave já existir, o elemento é substituído. Se a chave não existir, é adicionado um novo elemento. Veja o exemplo do CAtlMap::CAtlMap.

CAtlMap::Refazer

Chame este método para repetir o CAtlMap objeto.

void Rehash(UINT nBins = 0);

Parâmetros

nBins
O novo número de bins a usar na tabela de hash. Veja CAtlMap::CAtlMap para uma explicação.

Observações

Se nBins for 0, CAtlMap calcula um número razoável com base no número de elementos no mapa e na definição ótima de carga. Normalmente, o processo de rehashing é automático, mas se o CAtlMap::D isableAutoRehash for chamado, este método realizará o redimensionamento necessário.

CAtlMap::RemoveAll

Chame este método para remover todos os elementos do CAtlMap objeto.

void RemoveAll() throw();

Observações

Limpa o CAtlMap objeto, libertando a memória usada para armazenar os elementos.

CAtlMap::RemoveAtPos

Chame este método para remover o elemento na posição dada no CAtlMap objeto.

void RemoveAtPos(POSITION pos) throw();

Parâmetros

Ponto de venda
O contador de posição, devolvido por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.

Observações

Remove o par chave/valor armazenado na posição especificada. A memória usada para armazenar o elemento é libertada. A POSIÇÃO referenciada por pos torna-se inválida e, embora a POSIÇÃO de quaisquer outros elementos no mapa permaneça válida, não mantêm necessariamente a mesma ordem.

CAtlMap::RemoveKey

Chame este método para remover um elemento do CAtlMap objeto, dada a chave.

bool RemoveKey(KINARGTYPE key) throw();

Parâmetros

chave
A chave correspondente ao par de elementos que queres remover.

Valor de retorno

Retorna TRUE se a chave for encontrada e removida, FALSE em caso de falha.

Example

Veja o exemplo do CAtlMap::CAtlMap.

CAtlMap::SetAt

Chame este método para inserir um par de elementos no mapa.

POSITION SetAt(
    KINARGTYPE key,
    VINARGTYPE value);

Parâmetros

chave
O valor-chave a acrescentar ao CAtlMap objeto.

value
O valor a acrescentar ao CAtlMap objeto.

Valor de retorno

Devolve a posição do par chave/valor no CAtlMap objeto.

Observações

SetAt substitui um elemento existente se for encontrada uma chave correspondente. Se a chave não for encontrada, é criado um novo par chave/valor.

CAtlMap::SetOptimalLoad

Chame este método para definir a carga ótima do CAtlMap objeto.

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

Parâmetros

fOptimalLoad
A relação de carga ideal.

fLoThreshold
O limiar inferior para a relação de carga.

fHiThreshold
O limiar superior para a relação de carga.

bRehashNow
Flag indica se a tabela de hash deve ser recalculada.

Observações

Este método redefine o valor ótimo de carga para o CAtlMap objeto. Consulte CAtlMap::CAtlMap para uma discussão sobre os vários parâmetros. Se o bRehashNow for verdadeiro, e o número de elementos estiver fora dos valores mínimos e máximos, a tabela de hash é recalculada.

CAtlMap::SetValueAt

Chame este método para alterar o valor armazenado numa dada posição no CAtlMap objeto.

void SetValueAt(
    POSITION pos,
    VINARGTYPE value);

Parâmetros

Ponto de venda
O contador de posição, devolvido por uma chamada anterior para CAtlMap::GetNextAssoc ou CAtlMap::GetStartPosition.

value
O valor a acrescentar ao CAtlMap objeto.

Observações

Altera o elemento de valor armazenado na posição dada no CAtlMap objeto.

CAtlMap::VINARGTYPE

Tipo usado quando um valor é passado como argumento de entrada.

typedef VTraits::INARGTYPE VINARGTYPE;

CAtlMap::VOUTARGTYPE

Tipo usado quando um valor é passado como argumento de saída.

typedef VTraits::OUTARGTYPE VOUTARGTYPE;

CAtlMap::CPair::m_key

O membro de dados armazena o elemento chave.

const K m_key;

Parâmetros

K
O tipo de elemento-chave.

CAtlMap::CPair::m_value

O elemento de dados armazena o elemento valor.

V  m_value;

Parâmetros

V
O tipo de elemento valor.

Consulte também

Amostra de Destaque
Exemplo UpdatePV
Visão geral da classe