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
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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de