Auxiliares da classe de coleção

  • Artigo

As classes de coleção CMap, CList e CArray usam funções auxiliares globais com modelos para fins como comparar, copiar e serializar elementos. Como parte da implementação de classes baseadas em CMap, CList e CArray, você precisa substituir essas funções conforme necessário por versões adaptadas ao tipo de dados armazenados no mapa, na lista ou na matriz. Para obter informações sobre como substituir funções auxiliares, como SerializeElements, consulte o artigo Coleções: como criar uma coleção fortemente tipada. Observe que ConstructElements e DestructElements foram preteridos.

A biblioteca Microsoft Foundation Class fornece as seguintes funções globais em afxtempl.h para ajudar você a personalizar suas classes de coleção:

Auxiliares da classe de coleção

Nome Descrição
CompareElements Indica se os itens são iguais.
Elementos de cópia Copia elementos de uma matriz para outra.
DumpElements Fornece saída de diagnóstico orientada pelo fluxo.
HashKey Calcula uma chave de hash.
SerializeElements Armazena elementos em um arquivo ou recupera elementos dele.

CompareElements

Chamado diretamente por CList::Find e indiretamente por CMap::Lookup e CMap::operator[].

template<class TYPE, class ARG_TYPE>
BOOL AFXAPI
CompareElements(
    const TYPE* pElement1,
    const ARG_TYPE* pElement2);

Parâmetros

TYPE
O tipo do primeiro elemento a ser comparado.

pElement1
Ponteiro para o primeiro elemento a ser comparado.

ARG_TYPE
O tipo do segundo elemento a ser comparado.

pElement2
Ponteiro para o segundo elemento a ser comparado.

Valor de Devolução

Diferente de zero se o objeto apontado por pElement1 for igual ao objeto apontado por pElement2; caso contrário, 0.

Comentários

As chamadas CMap usam os parâmetros de modelo CMapKEY e ARG_KEY.

A implementação padrão retorna o resultado da comparação de *pElement1 e *pElement2. Substitua essa função para que ela compare os elementos de maneira apropriada para o aplicativo.

A linguagem C++ define o operador de comparação (==) para tipos simples (char, int, float e assim por diante), mas não define um operador de comparação para classes e estruturas. Se quiser usar CompareElements ou instanciar uma das classes de coleção que o usa, defina o operador de comparação ou sobrecarregue CompareElements com uma versão que retorne valores apropriados.

Requisitos

Cabeçalho: afxtempl.h

Elementos de cópia

Essa função é chamada diretamente por CArray::Append e CArray::Copy.

template<class TYPE>
void AFXAPI CopyElements(
    TYPE* pDest,
    const TYPE* pSrc,
    INT_PTR nCount);

Parâmetros

TYPE
Parâmetro de modelo que especifica o tipo dos elementos a serem copiados.

pDest
Ponteiro para o destino em que os elementos serão copiados.

pSrc
Ponteiro para a origem dos elementos a serem copiados.

nCount
Número de elementos a serem copiados.

Comentários

A implementação padrão usa o operador de atribuição simples (=) para executar a operação de cópia. Se o tipo sendo copiado não tiver um operador = sobrecarregado, a implementação padrão executará uma cópia bit a bit.

Para obter informações sobre como implementar essa e outras funções auxiliares, consulte o artigo Coleções: como criar uma coleção fortemente tipada.

Requisitos

Cabeçalho: afxtempl.h

DumpElements

Fornece saída de diagnóstico orientada pelo fluxo em forma de texto para os elementos da coleção quando substituído.

template<class TYPE>
void  AFXAPI DumpElements(
    CDumpContext& dc,
    const TYPE* pElements,
    INT_PTR nCount);

Parâmetros

dc
Contexto de despejo para o despejo de elementos.

TYPE
Parâmetro de modelo que especifica o tipo dos elementos.

pElements
Ponteiro para os elementos a serem despejados.

nCount
Número de elementos a serem despejados.

Comentários

As funções CArray::Dump, CList::Dump e CMap::Dump o chamarão se a profundidade do despejo for maior que 0.

A implementação padrão não tem ação. Se os elementos da coleção forem derivados de CObject, a substituição normalmente iterará nos elementos da coleção, chamando Dump para cada elemento por vez.

Requisitos

Cabeçalho: afxtempl.h

HashKey

Calcula um valor de hash para a chave fornecida.

template<class ARG_KEY>
AFX_INLINE UINT AFXAPI HashKey(ARG_KEY  key);

Parâmetros

ARG_KEY
Parâmetro de modelo que especifica o tipo de dados usado para acessar chaves de mapa.

chave
A chave cujo valor de hash deve ser calculado.

Valor de Devolução

O valor de hash da chave.

Comentários

Essa função é chamada diretamente por CMap::RemoveKey e indiretamente por CMap::Lookup e CMap::operator[].

A implementação padrão cria um valor de hash deslocando a chave para a direita em quatro posições. Substitua essa função para que ela retorne os valores de hash apropriados para seu aplicativo.

Exemplo

template <> UINT AFXAPI HashKey(unsigned __int64 key)
{
   // Generate the hash value by XORing the lower 32 bits of the number
   // with the upper 32 bits
   return(UINT(key) ^ UINT(key >> 32));
}

Requisitos

Cabeçalho: afxtempl.h

SerializeElements

CArray, CList e CMap chamam essa função para serializar elementos.

template<class TYPE>
void AFXAPI SerializeElements(CArchive& ar, TYPE* pElements, INT_PTR nCount);

Parâmetros

TYPE
Parâmetro de modelo que especifica o tipo dos elementos.

ar
Um objeto de arquivo do qual ou no qual arquivar.

pElements
Ponteiro para os elementos que estão sendo arquivados.

nCount
Número de elementos sendo arquivados

Comentários

A implementação padrão faz uma leitura ou gravação bit a bit.

Para obter informações sobre como implementar essa e outras funções auxiliares, consulte o artigo Coleções: como criar uma coleção fortemente tipada.

Exemplo

Veja o exemplo no artigo Coleções: como criar uma coleção fortemente tipada.

Requisitos

Cabeçalho: afxtempl.h

Confira também

Macros e Globais
Classe CMap
Classe CList
Classe CArray