Classe CMapStringToOb

Uma classe de coleção de dicionários que mapeia objetos CString exclusivos para ponteiros CObject.

Sintaxe

class CMapStringToOb : public CObject

Membros

Construtores públicos

Nome	Descrição
CMapStringToOb::CMapStringToOb	Construtor.

Métodos públicos

Nome	Descrição
CMapStringToOb::GetCount	Retorna o número de elementos no mapa.
CMapStringToOb::GetHashTableSize	Determina o número atual de elementos na tabela de hash.
CMapStringToOb::GetNextAssoc	Obtém o próximo elemento para iteração.
CMapStringToOb::GetSize	Retorna o número de elementos no mapa.
CMapStringToOb::GetStartPosition	Retorna a posição do primeiro elemento.
CMapStringToOb::HashKey	Calcula o valor de hash de uma chave especificada.
CMapStringToOb::InitHashTable	Inicializa a tabela de hash.
CMapStringToOb::IsEmpty	Testa a condição de mapa vazio (sem elementos).
CMapStringToOb::Lookup	Procura um ponteiro nulo com base na tecla de ponteiro nulo. O valor do ponteiro, não a entidade para a qual ele aponta, é usado para a comparação de chaves.
CMapStringToOb::LookupKey	Retorna uma referência à chave associada ao valor de chave especificado.
CMapStringToOb::RemoveAll	Remove todos os elementos desse mapa.
CMapStringToOb::RemoveKey	Remove um elemento especificado por uma chave.
CMapStringToOb::SetAt	Insere um elemento no mapa; substituirá um elemento se uma chave correspondente for encontrada.

Operadores públicos

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

Comentários

Depois de inserir um par CString- CObject* (elemento) no mapa, você pode recuperar ou excluir com eficiência o par usando uma cadeia de caracteres ou um valor CString como chave. Você também pode iterar por todos os elementos no mapa.

Uma variável de tipo POSITION é usada para acesso de entrada alternativa em todas as variações de mapa. 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.

A CMapStringToOb incorpora a macro IMPLEMENT_SERIAL para suportar serialização e despejo de seus elementos. Se um mapa for armazenado em um arquivo, seja com o operador de inserção (<<) sobrecarregado ou com a função de membro Serialize, cada elemento será serializado por vez.

Se você precisar de um despejo de diagnóstico dos elementos individuais no mapa (o valor CString e o conteúdo CObject), deverá definir a profundidade do contexto do despejo como 1 ou maior.

Quando um objeto CMapStringToOb é excluído ou quando seus elementos são removidos, os objetos CString e os ponteiros CObject são removidos. Os objetos referenciados pelos ponteiros CObject não são destruídos.

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

CMapStringToOb

Requisitos

Cabeçalho: afxcoll.h

CMapStringToOb::CMapStringToOb

Constrói um mapa CString a CObject* vazio.

CMapStringToOb(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.

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb:: CMapStringToOb.

Classe	Função membro
CMapPtrToPtr	CMapPtrToPtr( INT_PTR nBlockSize = 10 );
CMapPtrToWord	CMapPtrToWord( INT_PTR nBlockSize = 10 );
CMapStringToPtr	CMapStringToPtr( INT_PTR nBlockSize = 10 );
CMapStringToString	CMapStringToString( INT_PTR nBlockSize = 10 );
CMapWordToOb	CMapWordToOb( INT_PTR nBlockSize = 10 );
CMapWordToPtr	MapWordToPtr( INT_PTR nBlockSize = 10 );

Exemplo

CMapStringToOb map(20); // Map on the stack with blocksize of 20

CMapStringToOb *pm = new CMapStringToOb; // Map on the heap
                                         // with default blocksize

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CMapStringToOb::GetCount

Determina quantos elementos estão no mapa.

INT_PTR GetCount() const;

Valor de retorno

O número de elementos no mapa.

Comentários

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb::GetCount.

Classe	Função membro
CMapPtrToPtr	INT_PTR GetCount() const;
CMapPtrToWord	INT_PTR GetCount() const;
CMapStringToPtr	INT_PTR GetCount() const;
CMapStringToString	INT_PTR GetCount() const;
CMapWordToOb	INT_PTR GetCount() const;
CMapWordToPtr	INT_PTR GetCount() const;

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CMapStringToOb map;

map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Homer"), new CAge(36));
ASSERT(map.GetCount() == 2);

CMapStringToOb::GetHashTableSize

Determina o número atual de elementos na tabela de hash.

UINT GetHashTableSize() const;

Valor de retorno

Retorna o número de elementos na tabela de hash.

Comentários

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb::GetHashTableSize.

Classe	Função membro
CMapPtrToPtr	UINT GetHashTableSize() const;
CMapPtrToWord	UINT GetHashTableSize() const;
CMapStringToPtr	UINT GetHashTableSize() const;
CMapStringToString	UINT GetHashTableSize() const;
CMapWordToOb	UINT GetHashTableSize() const;
CMapWordToPtr	UINT GetHashTableSize() const;

CMapStringToOb::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,
    CString& rKey,
    CObject*& rValue) const;

Parâmetros

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

rKey
Especifica a chave retornada do elemento recuperado (uma cadeia de caracteres).

rValue
Especifica o valor retornado do elemento recuperado (um ponteiro CObject). Consulte Comentários para obter mais informações sobre esse parâmetro.

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.

Para o parâmetro rValue, certifique-se de converter seu tipo de objeto em CObject*&, que é o que o compilador requer, conforme mostrado no exemplo a seguir:

CObject *ob;
map.GetNextAssoc(pos, key, (CObject *&)ob);

Isso não vale para GetNextAssoc em mapas com base em modelos.

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb::GetNextAssoc.

Classe	Função membro
CMapPtrToPtr	void GetNextAssoc( POSITION& rNextPosition , void*& rKey , void*& rValue ) const;
CMapPtrToWord	void GetNextAssoc( POSITION& rNextPosition , void*& rKey , WORD& rValue ) const;
CMapStringToPtr	void GetNextAssoc( POSITION& rNextPosition , CString& rKey , void*& rValue ) const;
CMapStringToString	void GetNextAssoc( POSITION& rNextPosition , CString& rKey , CString& rValue ) const;
CMapWordToOb	void GetNextAssoc( POSITION& rNextPosition , WORD& rKey , CObject*& rValue ) const;
CMapWordToPtr	void GetNextAssoc( POSITION& rNextPosition , WORD& rKey , void*& rValue ) const;

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CMapStringToOb map;
POSITION pos;
CString key;
CAge *pa;

map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Lisa"), new CAge(11));
map.SetAt(_T("Homer"), new CAge(36));
map.SetAt(_T("Marge"), new CAge(35));
// Iterate through the entire map, dumping both name and age.
for (pos = map.GetStartPosition(); pos != NULL;)
{
   map.GetNextAssoc(pos, key, (CObject *&)pa);
#ifdef _DEBUG
   afxDump << key << _T(" : ") << pa << _T("\n");
#endif
}

Os resultados deste programa são os seguintes:

Lisa : a CAge at $4724 11
Marge : a CAge at $47A8 35
Homer : a CAge at $4766 36
Bart : a CAge at $45D4 13

CMapStringToOb::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.

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb::GetSize.

Classe	Função membro
CMapPtrToPtr	INT_PTR GetSize() const;
CMapPtrToWord	INT_PTR GetSize() const;
CMapStringToPtr	INT_PTR GetSize() const;
CMapStringToString	INT_PTR GetSize() const;
CMapWordToOb	INT_PTR GetSize() const;
CMapWordToPtr	INT_PTR GetSize() const;

Exemplo

CMapStringToOb map;

map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Homer"), new CAge(36));
ASSERT(map.GetSize() == 2);

CMapStringToOb::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.

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb::GetStartPosition.

Classe	Função membro
CMapPtrToPtr	POSITION GetStartPosition() const;
CMapPtrToWord	POSITION GetStartPosition() const;
CMapStringToPtr	POSITION GetStartPosition() const;
CMapStringToString	POSITION GetStartPosition() const;
CMapWordToOb	POSITION GetStartPosition() const;
CMapWordToPtr	POSITION GetStartPosition() const;

Exemplo

Confira o exemplo de CMapStringToOb::GetNextAssoc.

CMapStringToOb::HashKey

Calcula o valor de hash de uma chave especificada.

UINT HashKey(LPCTSTR key) const;

Parâmetros

key
A chave cujo valor de hash deve ser calculado.

Valor de retorno

O valor de hash da chave

Comentários

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb::HashKey.

Classe	Função membro
CMapPtrToPtr	UINT HashKey( void *key ) const;
CMapPtrToWord	UINT HashKey( void *key ) const;
CMapStringToString	UINT HashKey( LPCTSTR key ) const;
CMapStringToPtr	UINT HashKey( LPCTSTR key ) const;
CMapWordToOb	UINT HashKey( WORD key ) const;
CMapWordToPtr	UINT HashKey( WORD key ) const;

CMapStringToOb::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.

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb::InitHashTable.

Classe	Função membro
CMapPtrToPtr	void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapPtrToWord	void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapStringToString	void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapStringToPtr	void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapWordToOb	void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapWordToPtr	void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );

CMapStringToOb::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 RemoveAll.

Comentários

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb:: IsEmpty.

Classe	Função membro
CMapPtrToPtr	BOOL IsEmpty() const;
CMapPtrToWord	BOOL IsEmpty() const;
CMapStringToPtr	BOOL IsEmpty() const;
CMapStringToString	BOOL IsEmpty() const;
CMapWordToOb	BOOL IsEmpty() const;
CMapWordToPtr	BOOL IsEmpty() const;

CMapStringToOb::Lookup

Retorna um ponteiro CObject com base em um valor CString.

BOOL Lookup(
    LPCTSTR key,
    CObject*& rValue) const;

Parâmetros

key
Especifica a chave de cadeia de caracteres que identifica o elemento a ser pesquisado.

rValue
Especifica o valor retornado do elemento 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 rapidamente o elemento de mapa com uma chave que corresponde exatamente a ele (valor CString).

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb::LookUp.

Classe	Função membro
CMapPtrToPtr	BOOL Lookup( void *key , void*& rValue ) const;
CMapPtrToWord	BOOL Lookup( void *key , WORD& rValue ) const;
CMapStringToPtr	BOOL Lookup( LPCTSTR key , void*& rValue ) const;
CMapStringToString	BOOL Lookup( LPCTSTR key , CString& rValue ) const;
CMapWordToOb	BOOL Lookup( WORD key , CObject*& rValue ) const;
CMapWordToPtr	BOOL Lookup( WORD key , void*& rValue ) const;

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CMapStringToOb map;
CAge *pa;

map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Lisa"), new CAge(11));
map.SetAt(_T("Homer"), new CAge(36));
map.SetAt(_T("Marge"), new CAge(35));
ASSERT(map.Lookup(_T("Lisa"), (CObject *&)pa)); // Is "Lisa" in the map?
ASSERT(*pa == CAge(11));                        // Is she 11?

CMapStringToOb::LookupKey

Retorna uma referência à chave associada ao valor de chave especificado.

BOOL LookupKey(
    LPCTSTR key,
    LPCTSTR& rKey) const;

Parâmetros

key
Especifica a chave de cadeia de caracteres que identifica o elemento a ser pesquisado.

rKey
A referência à chave associada.

Valor de retorno

Não zero se a chave foi encontrada; caso contrário, 0.

Comentários

Usar uma referência a uma chave não é seguro se usado depois que o elemento associado foi removido do mapa ou depois que o mapa foi destruído.

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb:: LookupKey.

Classe	Função membro
CMapStringToPtr	BOOL LookupKey( LPCTSTR key , LPCTSTR& rKey ) const;
CMapStringToString	BOOL LookupKey( LPCTSTR key , LPCTSTR& rKey ) const;

CMapStringToOb::operator [ ]

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

CObject*& operator[ ](lpctstr key);

Valor de retorno

Uma referência a um ponteiro para um objeto CObject; ou NULL se o mapa estiver vazio ou key estiver fora do intervalo.

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.

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb::operator [].

Classe	Função membro
CMapPtrToPtr	void*& operator[](void *key );
CMapPtrToWord	WORD& operator[](void *key );
CMapStringToPtr	void*& operator[](lpctstr key );
CMapStringToString	CString& operator[](lpctstr key );
CMapWordToOb	CObject*& operator[](word key );
CMapWordToPtr	void*& operator[](word key );

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CMapStringToOb map;

map[_T("Bart")] = new CAge(13);
map[_T("Lisa")] = new CAge(11);
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("Operator [] example: ") << &map << _T("\n");
#endif

Os resultados deste programa são os seguintes:

Operator [] example: A CMapStringToOb with 2 elements
[Lisa] = a CAge at $4A02 11
[Bart] = a CAge at $497E 13

CMapStringToOb::RemoveAll

Remove todos os elementos deste mapa e destrói os objetos-chave CString.

void RemoveAll();

Comentários

Os objetos CObject referenciados por cada chave não são destruídos. A função RemoveAll poderá causar vazamentos de memória se você não garantir que os objetos CObject referenciados sejam destruídos.

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

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb::RemoveAll.

Classe	Função membro
CMapPtrToPtr	void RemoveAll();
CMapPtrToWord	void RemoveAll();
CMapStringToPtr	void RemoveAll();
CMapStringToString	void RemoveAll();
CMapWordToOb	void RemoveAll();
CMapWordToPtr	void RemoveAll();

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

{
   CMapStringToOb map;

   CAge age1(13); // Two objects on the stack
   CAge age2(36);
   map.SetAt(_T("Bart"), &age1);
   map.SetAt(_T("Homer"), &age2);
   ASSERT(map.GetCount() == 2);
   map.RemoveAll(); // CObject pointers removed; objects not removed.
   ASSERT(map.GetCount() == 0);
   ASSERT(map.IsEmpty());
} // The two CAge objects are deleted when they go out of scope.

CMapStringToOb::RemoveKey

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

BOOL RemoveKey(LPCTSTR key);

Parâmetros

key
Especifica a cadeia de caracteres usada para pesquisa de mapa.

Valor de retorno

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

Comentários

Isso poderá causar vazamentos de memória se o objeto CObject não for excluído em outro lugar.

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb::RemoveKey.

Classe	Função membro
CMapPtrToPtr	BOOL RemoveKey( void *key );
CMapPtrToWord	BOOL RemoveKey( void *key );
CMapStringToPtr	BOOL RemoveKey( LPCTSTR key );
CMapStringToString	BOOL RemoveKey( LPCTSTR key );
CMapWordToOb	BOOL RemoveKey( WORD key );
CMapWordToPtr	BOOL RemoveKey( WORD key );

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CMapStringToOb map;

map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Lisa"), new CAge(11));
map.SetAt(_T("Homer"), new CAge(36));
map.SetAt(_T("Marge"), new CAge(35));
map.RemoveKey(_T("Lisa")); // Memory leak: CAge object not
                           // deleted.
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("RemoveKey example: ") << &map << _T("\n");
#endif

Os resultados deste programa são os seguintes:

RemoveKey example: A CMapStringToOb with 3 elements
[Marge] = a CAge at $49A0 35
[Homer] = a CAge at $495E 36
[Bart] = a CAge at $4634 13

CMapStringToOb::SetAt

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

void SetAt(
    LPCTSTR key,
    CObject* newValue);

Parâmetros

key
Especifica a cadeia de caracteres que é a chave do novo elemento.

newValue
Especifica o ponteiro CObject que é 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 elemento chave-valor será criado.

A tabela a seguir mostra outras funções de membro semelhantes a CMapStringToOb::SetAt.

Classe	Função membro
CMapPtrToPtr	void SetAt( void *key , void *newValue );
CMapPtrToWord	void SetAt( void *key , WORD newValue );
CMapStringToPtr	void SetAt( LPCTSTR key , void *newValue );
CMapStringToString	void SetAt( LPCTSTR key , LPCTSTR newValue );
CMapWordToOb	void SetAt( WORD key , CObject *newValue );
CMapWordToPtr	void SetAt( WORD key , void *newValue );

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CMapStringToOb map;
CAge *pa;

map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Lisa"), new CAge(11)); // Map contains 2
                                     // elements.
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("before Lisa's birthday: ") << &map << _T("\n");
#endif
if (map.Lookup(_T("Lisa"), (CObject *&)pa))
{ // CAge 12 pointer replaces CAge 11 pointer.
   map.SetAt(_T("Lisa"), new CAge(12));
   delete pa; // Must delete CAge 11 to avoid memory leak.
}
#ifdef _DEBUG
afxDump << _T("after Lisa's birthday: ") << &map << _T("\n");
#endif

Os resultados deste programa são os seguintes:

before Lisa's birthday: A CMapStringToOb with 2 elements
[Lisa] = a CAge at $493C 11
[Bart] = a CAge at $4654 13
after Lisa's birthday: A CMapStringToOb with 2 elements
[Lisa] = a CAge at $49C0 12
[Bart] = a CAge at $4654 13

Confira também

Classe CObject
Gráfico da hierarquia
Classe CMapPtrToPtr
Classe CMapPtrToWord
Classe CMapStringToPtr
Classe CMapStringToString
Classe CMapWordToOb
Classe CMapWordToPtr