Classe CMap

Uma classe de coleção de dicionários que mapeia chaves exclusivas para valores.

Sintaxe

template<class KEY, class ARG_KEY, class VALUE, class ARG_VALUE>class CMap : public CObject

Parâmetros

KEY
Classe do objeto usado como a chave para o mapa.

ARG_KEY
Tipo de dados usado para argumentos KEY; geralmente uma referência a KEY.

VALUE
Classe do objeto armazenado no mapa.

ARG_VALUE
Tipo de dados usado para argumentos VALUE; geralmente uma referência a VALUE.

Membros

Estruturas públicas

Nome	Descrição
CMap::CPair	Uma estrutura aninhada que contém um valor de chave e o valor do objeto associado.

Construtores públicos

Nome	Descrição
CMap::CMap	Constrói uma coleção que mapeia chaves para valores.

Métodos públicos

Nome	Descrição
CMap::GetCount	Retorna o número de elementos no mapa.
CMap::GetHashTableSize	Retorna o número de elementos na tabela de hash.
CMap::GetNextAssoc	Obtém o próximo elemento para iteração.
CMap::GetSize	Retorna o número de elementos no mapa.
CMap::GetStartPosition	Retorna a posição do primeiro elemento.
CMap::InitHashTable	Inicializa a tabela de hash e especifica seu tamanho.
CMap::IsEmpty	Testa a condição de mapa vazio (sem elementos).
CMap::Lookup	Pesquisa o valor mapeado para uma determinada chave.
CMap::PGetFirstAssoc	Retorna um ponteiro para o primeiro elemento.
CMap::PGetNextAssoc	Obtém um ponteiro para o próximo elemento para iteração.
CMap::PLookup	Retorna um ponteiro para uma chave cujo valor corresponde ao valor especificado.
CMap::RemoveAll	Remove todos os elementos desse mapa.
CMap::RemoveKey	Remove um elemento especificado por uma chave.
CMap::SetAt	Insere um elemento no mapa; substituirá um elemento se uma chave correspondente for encontrada.

Operadores públicos

Nome	Descrição
CMap::operator [ ]	Insere um elemento no mapa – substituição do operador por SetAt.

Comentários

Depois de inserir um par chave-valor (elemento) no mapa, você poderá recuperar ou excluir com eficiência o par usando a chave para acessá-lo. Você também pode iterar por todos os elementos no mapa.

Uma variável de tipo POSITION é usada para acesso alternativo a entradas. Você pode usar um POSITION para "lembrar" uma entrada e iterar por meio do mapa. Você pode pensar que essa iteração é sequencial por valor de chave; ela não é. A sequência de elementos recuperados é indeterminada.

Determinadas funções membro dessa classe chamam funções auxiliares globais que precisam ser personalizadas para a maioria dos usos da classe CMap. Confira Auxiliares de classe de coleção na seção Macros e globais da Referência do MFC.

CMap substitui CObject::Serialize para dar suporte para serialização e despejo de seus elementos. Se um mapa for armazenado em um arquivo morto usando Serialize, cada elemento de mapa será serializado individualmente. A implementação padrão da função SerializeElements auxiliar faz uma gravação bit a bit. Para informações sobre a serialização de itens de coleção de ponteiros derivados de CObject ou de outros tipos definidos pelo usuário, confira Como tornar uma coleção fortemente tipada.

Se você precisar de um despejo de diagnóstico dos elementos individuais no mapa (as chaves e os valores), deverá definir a profundidade do contexto do despejo como 1 ou maior.

Quando um objeto CMap é excluído ou seus elementos são removidos, as chaves e os valores são removidos.

A derivação de classe de mapa é semelhante à derivação de lista. Confira o artigo Coleções para uma ilustração da derivação de uma classe de lista de finalidade especial.

Hierarquia de herança

CObject

CMap

Requisitos

Cabeçalho: afxtempl.h

CMap::CMap

Constrói um mapa vazio.

CMap(INT_PTR nBlockSize = 10);

Parâmetros

nBlockSize
Especifica a granularidade de alocação de memória para estender o mapa.

Comentários

À medida que o mapa cresce, a memória é alocada em unidades de entradas nBlockSize.

Exemplo

// declares a map of ints to points
CMap<int, int, CPoint, CPoint> myMap(16);

CMap::CPair

Contém um valor de chave e o valor do objeto associado.

Comentários

Essa é uma estrutura aninhada dentro da classe CMap.

A estrutura é composta por dois campos:

• key O valor real do tipo de chave.

• value O valor do objeto associado.

Ela é usada para armazenar os valores retornados de CMap::PLookup, CMap::PGetFirstAssoc e CMap::PGetNextAssoc.

Exemplo

Para um exemplo de uso, confira o exemplo de CMap::PLookup.

CMap::GetCount

Recupera o número de elementos no mapa.

INT_PTR GetCount() const;

Valor de retorno

O número de elementos.

Exemplo

Confira o exemplo de CMap::Lookup.

CMap::GetHashTableSize

Determina o número de elementos na tabela de hash do mapa.

UINT GetHashTableSize() const;

Valor de retorno

O número de elementos na tabela de hash.

Exemplo

CMap<int, int, CPoint, CPoint> myMap;

UINT uTableSize = myMap.GetHashTableSize();

CMap::GetNextAssoc

Recupera o elemento de mapa em rNextPosition, em seguida, atualiza rNextPosition para se referir ao próximo elemento no mapa.

void GetNextAssoc(
    POSITION& rNextPosition,
    KEY& rKey,
    VALUE& rValue) const;

Parâmetros

rNextPosition
Especifica uma referência a um valor POSITION retornado por uma chamada GetNextAssoc ou GetStartPosition anterior.

KEY
Parâmetro de modelo que especifica o tipo da chave do mapa.

rKey
Especifica a chave retornada do elemento recuperado.

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

rValue
Especifica o valor retornado do elemento recuperado.

Comentários

Essa função é mais útil para iterar todos os elementos no mapa. Observe que a sequência de posição não é necessariamente a mesma que a sequência de valor de chave.

Se o elemento recuperado for o último no mapa, o novo valor de rNextPosition será definido como NULL.

Exemplo

Confira o exemplo de CMap::SetAt.

CMap::GetSize

Retorna o número de elementos de mapa.

INT_PTR GetSize() const;

Valor de retorno

O número de itens no mapa.

Comentários

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

Exemplo

CMap<int, int, CPoint, CPoint> myMap;

myMap.InitHashTable(257);

// Add 200 elements to the map.
for (int i = 0; i < 200; i++)
{
   myMap[i] = CPoint(i, i);
}

// Remove the elements with even key values.
CPoint pt;
for (int i = 0; myMap.Lookup(i, pt); i += 2)
{
   myMap.RemoveKey(i);
}

ASSERT(myMap.GetSize() == 100);
TRACE(_T("myMap with %d elements:\n"), myMap.GetCount());
POSITION pos = myMap.GetStartPosition();
int iKey;
CPoint ptVal;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, iKey, ptVal);
   TRACE(_T("\t[%d] = (%d,%d)\n"), iKey, ptVal.x, ptVal.y);
}

CMap::GetStartPosition

Inicia uma iteração de mapa retornando um valor POSITION que pode ser passado para uma chamada GetNextAssoc.

POSITION GetStartPosition() const;

Valor de retorno

Um valor POSITION que indica uma posição inicial para iterar o mapa; ou NULL se o mapa estiver vazio.

Comentários

A sequência de iteração não é previsível; portanto, o "primeiro elemento no mapa" não tem significado especial.

Exemplo

Confira o exemplo de CMap::SetAt.

CMap::InitHashTable

Inicializa a tabela de hash.

void InitHashTable(UINT hashSize, BOOL  bAllocNow = TRUE);

Parâmetros

hashSize
O número de entradas na tabela de hash.

bAllocNow
Se TRUE, aloca a tabela de hash após a inicialização; caso contrário, a tabela é alocada quando necessário.

Comentários

Para obter o melhor desempenho, o tamanho da tabela de hash deve ser um número primo. Para minimizar colisões, o tamanho deve ser aproximadamente 20% maior do que o maior conjunto de dados previsto.

Exemplo

Confira o exemplo de CMap::Lookup.

CMap::IsEmpty

Determina se o mapa está vazio.

BOOL IsEmpty() const;

Valor de retorno

Não zero se este mapa não contiver elementos; caso contrário, 0.

Exemplo

Confira o exemplo de CMap::RemoveAll.

CMap::Lookup

Pesquisa o valor mapeado para uma determinada chave.

BOOL Lookup(ARG_KEY key, VALUE& rValue) const;

Parâmetros

ARG_KEY
Parâmetro de modelo que especifica o tipo do valor key.

key
Especifica a chave que identifica o elemento a ser pesquisado.

VALUE
Especifica o tipo do valor a ser pesquisado.

rValue
Recebe o valor pesquisado.

Valor de retorno

Não zero se o elemento foi encontrado; caso contrário, 0.

Comentários

Lookup usa um algoritmo de hash para localizar com rapidez o elemento de mapa com uma chave que corresponde exatamente à chave fornecida.

Exemplo

CMap<int, int, CPoint, CPoint> myMap;

myMap.InitHashTable(257);

// Add 200 elements to the map.
for (int i = 0; i < 200; i++)
{
   myMap[i] = CPoint(i, i);
}

// Remove the elements with even key values.
CPoint pt;
for (int i = 0; myMap.Lookup(i, pt); i += 2)
{
   myMap.RemoveKey(i);
}

ASSERT(myMap.GetSize() == 100);
TRACE(_T("myMap with %d elements:\n"), myMap.GetCount());
POSITION pos = myMap.GetStartPosition();
int iKey;
CPoint ptVal;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, iKey, ptVal);
   TRACE(_T("\t[%d] = (%d,%d)\n"), iKey, ptVal.x, ptVal.y);
}

CMap::operator [ ]

Um substituto conveniente para a função de membro SetAt.

VALUE& operator[](arg_key key);

Parâmetros

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

ARG_KEY
Parâmetro de modelo que especifica o tipo do valor da chave.

key
A chave usada para recuperar o valor do mapa.

Comentários

Assim, ele só pode ser usado no lado esquerdo de uma instrução de atribuição (um l-value). Se não houver nenhum elemento de mapa com a chave especificada, um novo elemento será criado.

Não há nenhum equivalente "lado direito" (r-value) a esse operador porque há a possibilidade de que uma chave não seja encontrada no mapa. Use a função de membro Lookup para recuperação de elemento.

Exemplo

Confira o exemplo de CMap::Lookup.

CMap::PGetFirstAssoc

Retorna a primeira entrada do objeto de mapa.

const CPair* PGetFirstAssoc() const;
CPair* PGetFirstAssoc();

Valor de retorno

Um ponteiro para a primeira entrada no mapa; confira CMap::CPair. Se o mapa não contiver entradas, o valor será NULL.

Comentários

Chame essa função para retornar um ponteiro do primeiro elemento no objeto de mapa.

Exemplo

typedef CMap<int, int, CPoint, CPoint> CMyMap;
CMyMap myMap;

myMap.InitHashTable(257);

// Add 10 elements to the map.
for (int i = 0; i <= 10; i++)
   myMap.SetAt(i, CPoint(i, i));

// Print the element value with even key values.
int nKey = 0;
CPoint pt;
CMyMap::CPair *pCurVal;

pCurVal = myMap.PGetFirstAssoc();
while (pCurVal != NULL)
{
   if ((nKey % 2) == 0)
   {
      _tprintf_s(_T("Current key value at %d: %d,%d\n"),
                 pCurVal->key, pCurVal->value.x, pCurVal->value.y);
   }
   pCurVal = myMap.PGetNextAssoc(pCurVal);
   nKey++;
}

CMap::PGetNextAssoc

Recupera o elemento de mapa apontado por pAssocRec.

const CPair *PGetNextAssoc(const CPair* pAssocRet) const;

CPair *PGetNextAssoc(const CPair* pAssocRet);

Parâmetros

pAssocRet
Aponta para uma entrada de mapa retornada por uma chamada a PGetNextAssoc ou CMap::PGetFirstAssoc anterior.

Valor de retorno

Um ponteiro para a próxima entrada no mapa; confira CMap::CPair. Se o elemento for o último no mapa, o valor será NULL.

Comentários

Chame esse método para iterar todos os elementos no mapa. Recupere o primeiro elemento com uma chamada para PGetFirstAssoc e itere pelo mapa com chamadas sucessivas para PGetNextAssoc.

Exemplo

Confira o exemplo de CMap::PGetFirstAssoc.

CMap::PLookup

Localiza o valor mapeado para uma determinada chave.

const CPair* PLookup(ARG_KEY key) const;
CPair* PLookup(ARG_KEY key);

Parâmetros

key
Chave para o elemento a ser pesquisado.

Valor de retorno

Um ponteiro para uma estrutura de chave; confira CMap::CPair. Se nenhuma correspondência for encontrada, CMap::PLookup retornará NULL.

Comentários

Chame esse método para pesquisar um elemento de mapa com uma chave que corresponda exatamente à chave fornecida.

Exemplo

typedef CMap<int, int, CPoint, CPoint> CMyMap;
CMyMap myMap;

myMap.InitHashTable(257);

// Add 10 elements to the map.
for (int i = 0; i <= 10; i++)
   myMap[i] = CPoint(i, i);

// Print the element values with even key values.
CMyMap::CPair *pCurVal;

for (int i = 0; i <= myMap.GetCount(); i += 2)
{
   pCurVal = myMap.PLookup(i);
   _tprintf_s(_T("Current key value at %d: %d,%d\n"),
              pCurVal->key, pCurVal->value.x, pCurVal->value.y);
}

CMap::RemoveAll

Remove todos os valores desse mapa chamando a função auxiliar global DestructElements.

void RemoveAll();

Comentários

A função funcionará corretamente se o mapa já estiver vazio.

Exemplo

CMap<int, int, CPoint, CPoint> myMap;

// Add 10 elements to the map.
for (int i = 0; i < 10; i++)
   myMap.SetAt(i, CPoint(i, i));

myMap.RemoveAll();

ASSERT(myMap.IsEmpty());

CMap::RemoveKey

Pesquisa a entrada do mapa correspondente à chave fornecida; em seguida, se a chave for encontrada, removerá a entrada.

BOOL RemoveKey(ARG_KEY key);

Parâmetros

ARG_KEY
Parâmetro de modelo que especifica o tipo da chave.

key
Chave para o elemento a ser removido.

Valor de retorno

Não zero se a entrada foi encontrada e removida com êxito; caso contrário, 0.

Comentários

A função auxiliar DestructElements é usada para remover a entrada.

Exemplo

Confira o exemplo de CMap::SetAt.

CMap::SetAt

A primária significa inserir um elemento em um mapa.

void SetAt(ARG_KEY key, ARG_VALUE newValue);

Parâmetros

ARG_KEY
Parâmetro de modelo que especifica o tipo do parâmetro key.

key
Especifica a chave do novo elemento.

ARG_VALUE
Parâmetro de modelo que especifica o tipo do parâmetro newValue.

newValue
Especifica o valor do novo elemento.

Comentários

Primeiro, a chave é pesquisada. Se a chave for encontrada, o valor correspondente será alterado; caso contrário, um novo par chave-valor será criado.

Exemplo

CMap<int, int, CPoint, CPoint> myMap;

// Add 10 elements to the map.
for (int i = 0; i < 10; i++)
   myMap.SetAt(i, CPoint(i, i));

// Remove the elements with even key values.
POSITION pos = myMap.GetStartPosition();
int nKey;
CPoint pt;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, nKey, pt);

   if ((nKey % 2) == 0)
      myMap.RemoveKey(nKey);
}

// Print the element values.
pos = myMap.GetStartPosition();
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, nKey, pt);
   _tprintf_s(_T("Current key value at %d: %d,%d\n"),
              nKey, pt.x, pt.y);
}

Confira também

Exemplo de MFC COLLECT
Classe CObject
Gráfico da hierarquia