CMapStringToOb Classe

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

Sintaxe

class CMapStringToOb : public CObject

Membros

Construtores Públicos

Métodos Públicos

Operadores Públicos

Observações

Depois de inserir um CString- CObject* par (elemento) no mapa, você pode recuperar ou excluir o par usando uma cadeia de caracteres ou um CString valor como chave. Você também pode iterar sobre 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 através do mapa. Você pode pensar que essa iteração é sequencial por valor de chave; Não é. A sequência de elementos recuperados é indeterminada.

CMapStringToOb incorpora a macro para suportar a IMPLEMENT_SERIAL serialização e o despejo de seus elementos. Cada elemento é serializado por sua vez se um mapa é armazenado em um arquivo, seja com o operador de inserção sobrecarregado ( <<) ou com a Serialize função de membro.

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

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

A derivação de classe de mapa é semelhante à derivação de lista. Consulte o artigo Coleções para obter uma ilustração da derivação de uma classe de lista para fins especiais.

Hierarquia de herança

CObject

CMapStringToOb

Requerimentos

Cabeçalho:afxcoll.h

CMapStringToOb::CMapStringToOb

Constrói um mapa vazioCStringCObject*.

CMapStringToOb(INT_PTR nBlockSize = 10);

Parâmetros

nBlockSize
Especifica a granularidade de 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.

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

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 lista da CAge classe 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 neste mapa.

Observações

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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.

Observações

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

CMapStringToOb::GetNextAssoc

Recupera o elemento de mapa em e, em rNextPositionseguida, atualiza rNextPosition para fazer referência 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 anterior GetNextAssoc ou GetStartPosition chamada.

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

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

Observações

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

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

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

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

Isso não é verdade GetNextAssoc para mapas baseados em modelos.

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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.

Observações

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

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

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 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 está vazio.

Observações

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

Exemplo

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

Observações

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

CMapStringToOb::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 de hash na inicialização, caso contrário, a tabela é alocada quando necessário.

Observações

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

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

CMapStringToOb::IsEmpty

Determina se o mapa está vazio.

BOOL IsEmpty() const;

Valor de retorno

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

Exemplo

Veja o exemplo para RemoveAll.

Observações

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

CMapStringToOb::Lookup

Retorna um CObject ponteiro com base em um CString valor.

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

Diferente de zero se o elemento foi encontrado; caso contrário, 0.

Observações

Lookup usa um algoritmo de hash para localizar rapidamente o elemento map com uma chave que corresponde exatamente (CString value).

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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

Diferente de zero se a chave foi encontrada; caso contrário, 0.

Observações

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

CMapStringToOb::operator [ ]

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

CObject*& operator[ ](lpctstr key);

Valor de retorno

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

Observações

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

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

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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 CString objetos chave.

void RemoveAll();

Observações

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

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

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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

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

BOOL RemoveKey(LPCTSTR key);

Parâmetros

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

Valor de retorno

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

Observações

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

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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

O principal 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 CObject ponteiro que é o valor do novo elemento.

Observações

Primeiro, a chave é procurada. 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 ao CMapStringToOb::SetAt.

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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

Ver também

CObject Classe
Gráfico de Hierarquia
CMapPtrToPtr Classe
CMapPtrToWord Classe
CMapStringToPtr Classe
CMapStringToString Classe
CMapWordToOb Classe
CMapWordToPtr Classe