CMap Classe

Uma classe de coleção de dicionário que mapeia chaves únicas para valores.

Sintaxe

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

Parâmetros

KEY
Classe do objeto usada como chave para o mapa.

ARG_KEY
Tipo de dado usado para KEY argumentos; normalmente uma referência a KEY.

VALUE
Classe do objeto armazenado no mapa.

ARG_VALUE
Tipo de dado usado para VALUE argumentos; normalmente uma referência a VALUE.

Membros

Estruturas Públicas

Construtores Públicos

Métodos Públicos

Operadores Públicos

Observações

Depois de inserir um par chave-valor (elemento) no mapa, pode recuperar ou eliminar o par de forma eficiente usando a chave para aceder a ele. Também podes iterar sobre todos os elementos do mapa.

Uma variável do tipo POSITION é usada para acesso alternativo às entradas. Podes usar um POSITION para "lembrar" uma entrada e iterar pelo mapa. Pode pensar que esta iteração é sequencial por valor-chave; Não é. A sequência dos elementos recuperados é indeterminada.

Certas funções membros desta classe chamam funções auxiliares globais que têm de ser personalizadas para a maioria dos usos da CMap classe. Consulte Ajudantes de Classe de Coleção na secção Macros e Globais da Referência MFC.

CMap overries CObject::Serialize para suportar serialização e despejo dos seus elementos. Se um mapa for armazenado num arquivo usando Serialize, cada elemento do mapa é serializado por sua vez. A implementação padrão da SerializeElements função auxiliar faz uma escrita bit a bit. Para informações sobre a serialização de itens da coleção de ponteiros derivados de CObject ou outros tipos definidos pelo utilizador, veja Como: Criar uma Coleção Type-Safe.

Se precisar de um dump de diagnóstico dos elementos individuais no mapa (as chaves e valores), deve definir a profundidade do contexto do dump para 1 ou superior.

Quando um CMap objeto é eliminado, ou quando os seus elementos são removidos, tanto as chaves como os valores são removidos.

A derivação de classes de mapa é semelhante à derivação por lista. Consulte o artigo Coleções para uma ilustração da derivação de uma classe de lista de uso especial.

Hierarquia de herança

CObject

CMap

Requerimentos

Cabeçalho:afxtempl.h

CMap::CMap

Constrói um mapa vazio.

CMap(INT_PTR nBlockSize = 10);

Parâmetros

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

Observações

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

Example

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

CMap::CPair

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

Observações

Esta é 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.

É usado para armazenar os valores de retorno de CMap::PLookup, CMap::PGetFirstAssoc, e CMap::PGetNextAssoc.

Example

Para um exemplo de uso, veja o exemplo para CMap::PLookup.

CMap::GetCount

Recupera o número de elementos no mapa.

INT_PTR GetCount() const;

Valor de retorno

O número de elementos.

Example

Veja o exemplo para 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.

Example

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

UINT uTableSize = myMap.GetHashTableSize();

CMap::GetNextAssoc

Recupera o elemento do mapa em rNextPosition, depois atualiza rNextPosition para se referir ao próximo elemento do mapa.

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

Parâmetros

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

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

rKey
Especifica a chave devolvida do elemento recuperado.

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

rValue
Especifica o valor devolvido do elemento recuperado.

Observações

Esta função é mais útil para iterar por todos os elementos do mapa. Note que a sequência de posições não é necessariamente a mesma que a sequência de valor-chave.

Se o elemento recuperado for o último no mapa, então o novo valor de rNextPosition é definido para NULL.

Example

Veja o exemplo para CMap::SetAt.

CMap::GetSize

Devolve o número de elementos do mapa.

INT_PTR GetSize() const;

Valor de retorno

O número de itens no mapa.

Observações

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

Example

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 do mapa ao devolver um POSITION valor que pode ser passado para uma GetNextAssoc chamada.

POSITION GetStartPosition() const;

Valor de retorno

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

Observações

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

Example

Veja o exemplo para CMap::SetAt.

CMap::InitHashTable

Inicializa a tabela de hash.

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

Parâmetros

hashSize
Número de entradas na tabela de hash.

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

Observações

Para melhor desempenho, o tamanho da tabela de hash deve ser um número primo. Para minimizar colisões, o tamanho deverá ser cerca de 20 por cento maior do que o maior conjunto de dados antecipado.

Example

Veja o exemplo para CMap::Lookup.

CMap::IsEmpty

Determina se o mapa está vazio.

BOOL IsEmpty() const;

Valor de retorno

Não nulo se esta aplicação não contiver elementos; caso contrário, 0.

Example

Veja o exemplo para CMap::RemoveAll.

CMap::Lookup

Procura o valor mapeado para uma dada chave.

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

Parâmetros

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

key
Especifica a chave que identifica o elemento a consultar.

VALUE
Especifica o tipo de valor a consultar.

rValue
Recebe o valor pesquisado.

Valor de retorno

Não nulo se o elemento fosse encontrado; caso contrário, 0.

Observações

Lookup utiliza um algoritmo de hash para encontrar rapidamente o elemento do mapa com uma chave que corresponde exatamente à chave dada.

Example

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 SetAt função de membro.

VALUE& operator[](arg_key key);

Parâmetros

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

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

key
A chave usada para recuperar o valor do mapa.

Observações

Assim, só pode ser usado no lado esquerdo de uma instrução de atribuição (um valor l). Se não existir nenhum elemento de mapa com a chave especificada, então é criado um novo elemento.

Não existe um equivalente "lado direito" (valor r) a este operador porque existe a possibilidade de uma chave não ser encontrada no mapa. Use a Lookup função membro para recuperação de elementos.

Example

Veja o exemplo para CMap::Lookup.

CMap::PGetFirstAssoc

Devolve a primeira entrada do objeto do mapa.

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

Valor de retorno

Um indicador para a primeira entrada no mapa; ver CMap::CPair. Se a aplicação não contiver entradas, o valor é NULL.

Observações

Chama esta função para devolver um ponteiro ao primeiro elemento do objeto do mapa.

Example

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 do mapa apontado para por pAssocRec.

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

CPair *PGetNextAssoc(const CPair* pAssocRet);

Parâmetros

pAssocRet
Aponta para uma entrada no mapa devolvida por uma chamada anterior PGetNextAssoc ou CMap::PGetFirstAssoc chamada.

Valor de retorno

Um apontador para a próxima entrada no mapa; ver CMap::CPair. Se o elemento for o último no mapa, o valor é NULL.

Observações

Chame este método para iterar por todos os elementos do mapa. Recuperar o primeiro elemento com uma chamada para PGetFirstAssoc e depois iterar pelo mapa com chamadas sucessivas para PGetNextAssoc.

Example

Veja o exemplo para CMap::PGetFirstAssoc.

CMap::PLookup

Encontra o valor mapeado para uma dada chave.

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

Parâmetros

key
Fundamental para o elemento a procurar.

Valor de retorno

Um apontador para uma estrutura de chaves; ver CMap::CPair. Se não for encontrada correspondência, CMap::PLookup devolve NULL.

Observações

Chame este método para procurar um elemento de mapa com uma chave que corresponda exatamente à chave dada.

Example

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 deste mapa chamando a função DestructElementsauxiliar global .

void RemoveAll();

Observações

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

Example

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

Procura a entrada do mapa correspondente à chave fornecida; depois, se a chave for encontrada, remove a entrada.

BOOL RemoveKey(ARG_KEY key);

Parâmetros

ARG_KEY
Parâmetro template que especifica o tipo da chave.

key
Fundamental para o elemento ser removido.

Valor de retorno

Diferente de zero se a entrada foi encontrada e removida com sucesso; caso contrário, 0.

Observações

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

Example

Veja o exemplo para CMap::SetAt.

CMap::SetAt

O principal meio para inserir um elemento num mapa.

void SetAt(ARG_KEY key, ARG_VALUE newValue);

Parâmetros

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

key
Especifica a tonalidade do novo elemento.

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

newValue
Especifica o valor do novo elemento.

Observações

Primeiro, procura-se a chave. Se a chave for encontrada, então o valor correspondente é alterado; caso contrário, é criado um novo par chave-valor.

Example

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);
}

Consulte também

Exemplo MFC COLLECT
CObject Classe
Gráfico de Hierarquia