Classe CRBMultiMap

Essa classe representa uma estrutura de mapeamento que permite que cada chave possa ser associada a mais de um valor, usando uma árvore binária Red-Black.

Sintaxe

template<typename K,
         typename V,
         class KTraits = CElementTraits<K>,
         class VTraits = CElementTraits<V>>
class CRBMultiMap : public CRBTree<K, V, KTraits, VTraits>

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

Construtores públicos

Nome	Descrição
CRBMultiMap::CRBMultiMap	O construtor .
CRBMultiMap::~CRBMultiMap	O destruidor.

Métodos públicos

Nome	Descrição
CRBMultiMap::FindFirstWithKey	Chame esse método para localizar a posição do primeiro elemento com uma determinada chave.
CRBMultiMap::GetNextValueWithKey	Chame esse método para obter o valor associado a uma determinada chave e atualize o valor da posição.
CRBMultiMap::GetNextWithKey	Chame esse método para obter o elemento associado a uma determinada chave e atualize o valor da posição.
CRBMultiMap::Insert	Chame esse método para inserir um par de elementos no mapa.
CRBMultiMap::RemoveKey	Chame esse método para remover todos os elementos chave/valor de uma determinada chave.

Comentários

A CRBMultiMap fornece suporte para uma matriz de mapeamento de qualquer tipo específico, gerenciando uma matriz ordenada de elementos de chave e valores. Ao contrário da classe CRBMap, cada chave pode ser associada a mais de um valor.

Os elementos (que consistem em uma chave e um valor) são armazenados em uma estrutura de árvore binária, usando o método CRBMultiMap::Insert. Os elementos podem ser removidos usando o método CRBMultiMap::RemoveKey, que exclui todos os elementos que correspondem à chave fornecida.

A passagem pela árvore é possível com métodos como CRBTree::GetHeadPosition, CRBTree::GetNext e CRBTree::GetNextValue. É possível acessar os valores potencialmente múltiplos por chave usando os métodos CRBMultiMap::FindFirstWithKey, CRBMultiMap::GetNextValueWithKey e CRBMultiMap::GetNextWithKey. Consulte o exemplo de CRBMultiMap::CRBMultiMap para obter uma ilustração disso na prática.

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.

A CRBMultiMap é derivada da CRBTree, que implementa uma árvore binária usando o algoritmo Red-Black. Uma alternativa para CRBMultiMap e CRBMap é oferecida pela classe CAtlMap. Quando apenas um pequeno número de elementos precisar ser armazenado, considere usar a classe CSimpleMap.

Para obter uma discussão mais completa sobre as várias classes de coleção e seus recursos e características de desempenho, confira Classes de coleção da ATL.

Hierarquia de herança

CRBTree

CRBMultiMap

Requisitos

Cabeçalho: atlcoll.h

CRBMultiMap::CRBMultiMap

O construtor .

explicit CRBMultiMap(size_t nBlockSize = 10) throw();

Parâmetros

nBlockSize
O tamanho do bloco.

Comentários

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. O padrão alocará espaço para 10 elementos por vez.

Confira a documentação da classe base CRBTree para obter informações sobre os outros métodos disponíveis.

Exemplo

// Define a multimap object which has an integer
// key, a double value, and a block size of 5
CRBMultiMap<int, double> myMap(5);

// Add some key/values. Notice how three
// different values are associated with 
// one key. In a CRBMap object, the values
// would simply overwrite each other.
myMap.Insert(0, 1.1);
myMap.Insert(0, 1.2);
myMap.Insert(0, 1.3);
myMap.Insert(1, 2.1);

// Look up a key and iterate through
// all associated values

double v;
POSITION myPos = myMap.FindFirstWithKey(0);

while (myPos != NULL)
{
   v = myMap.GetNextValueWithKey(myPos,0);
   // As the loop iterates, v 
   // contains the values 1.3, 1.2, 1.1
}

// Remove all of the values associated with that key
size_t i = myMap.RemoveKey(0);

// Confirm all three values were deleted
ATLASSERT(i == 3);

CRBMultiMap::~CRBMultiMap

O destruidor.

~CRBMultiMap() throw();

Comentários

Libera todos os recursos alocados.

Confira a documentação da classe base CRBTree para obter informações sobre os outros métodos disponíveis.

CRBMultiMap::FindFirstWithKey

Chame esse método para localizar a posição do primeiro elemento com uma determinada chave.

POSITION FindFirstWithKey(KINARGTYPE key) const throw();

Parâmetros

chave
Especifica a chave que identifica o elemento a ser encontrado.

Valor de retorno

Retorna a POSIÇÃO do primeiro elemento chave/valor se a chave for encontrada, caso contrário, NULL.

Comentários

Uma chave no CRBMultiMap pode ter um ou mais valores associados. Esse método fornecerá o valor de posição do primeiro valor (que pode, de fato, ser o único valor) associado a essa chave específica. O valor da posição retornado pode ser usado com CRBMultiMap::GetNextValueWithKey ou CRBMultiMap::GetNextWithKey para obter o valor e atualizar a posição.

Confira a documentação da classe base CRBTree para obter informações sobre os outros métodos disponíveis.

Exemplo

Consulte o exemplo de CRBMultiMap::CRBMultiMap.

CRBMultiMap::GetNextValueWithKey

Chame esse método para obter o valor associado a uma determinada chave e atualize o valor da posição.

const V& GetNextValueWithKey(
    POSITION& pos,
    KINARGTYPE key) const throw();
V& GetNextValueWithKey(
    POSITION& pos,
    KINARGTYPE key) throw();

Parâmetros

pos
O valor da posição, obtido com uma chamada para CRBMultiMap::FindFirstWithKey ou CRBMultiMap::GetNextWithKey ou uma chamada anterior para GetNextValueWithKey.

chave
Especifica a chave que identifica o elemento a ser encontrado.

Valor de retorno

Retorna o par de elementos associado à chave fornecida.

Comentários

O valor da posição é atualizado para apontar para o próximo valor associado à chave. Se não existirem mais valores, o valor da posição será definido como NULL.

Confira a documentação da classe base CRBTree para obter informações sobre os outros métodos disponíveis.

Exemplo

Consulte o exemplo de CRBMultiMap::CRBMultiMap.

CRBMultiMap::GetNextWithKey

Chame esse método para obter o elemento associado a uma determinada chave e atualize o valor da posição.

const CPair* GetNextWithKey(
    POSITION& pos,
    KINARGTYPE key) const throw();
CPair* GetNextWithKey(
    POSITION& pos,
    KINARGTYPE key) throw();

Parâmetros

pos
O valor da posição, obtido com uma chamada para CRBMultiMap::FindFirstWithKey ou CRBMultiMap::GetNextValueWithKey ou uma chamada anterior para GetNextWithKey.

chave
Especifica a chave que identifica o elemento a ser encontrado.

Valor de retorno

Retorna o próximo elemento da classe CRBTree::CPair associado à chave fornecida.

Comentários

O valor da posição é atualizado para apontar para o próximo valor associado à chave. Se não existirem mais valores, o valor da posição será definido como NULL.

Confira a documentação da classe base CRBTree para obter informações sobre os outros métodos disponíveis.

CRBMultiMap::Insert

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

POSITION Insert(KINARGTYPE key, VINARGTYPE value) throw(...);

Parâmetros

chave
O valor da chave a ser adicionado ao objeto CRBMultiMap.

value
O valor a ser adicionado ao objeto CRBMultiMap, associado à chave.

Valor de retorno

Retorna a posição do par de elementos chave/valor no objeto CRBMultiMap.

Comentários

Confira a documentação da classe base CRBTree para obter informações sobre os outros métodos disponíveis.

Exemplo

Consulte o exemplo de CRBMultiMap::CRBMultiMap.

CRBMultiMap::RemoveKey

Chame esse método para remover todos os elementos chave/valor de uma determinada chave.

size_t RemoveKey(KINARGTYPE key) throw();

Parâmetros

chave
Especifica a chave que identifica os elementos a serem excluídos.

Valor de retorno

Retorna o número de valores associados à chave determinada.

Comentários

RemoveKey exclui todos os elementos chave/valor que têm uma chave que corresponde à chave.

Confira a documentação da classe base CRBTree para obter informações sobre os outros métodos disponíveis.

Exemplo

Consulte o exemplo de CRBMultiMap::CRBMultiMap.

Confira também

Classe CRBTree
Classe CAtlMap
Classe CRBMap
Visão geral da aula