Вспомогательные функции классов коллекции

  • Статья

Классы CMapCListколлекции и CArray использование шаблонных глобальных вспомогательных функций для таких целей, как сравнение, копирование и сериализация элементов. В рамках реализации классов на CMapоснове , CListи CArrayнеобходимо переопределить эти функции при необходимости с версиями, адаптированными к типу данных, хранящихся в карте, списке или массиве. Дополнительные сведения о переопределении вспомогательных функций, таких как SerializeElements, см. в статьях " Коллекции: как создать коллекцию типов Сейф". Обратите внимание, что ConstructElements и DestructElements не рекомендуется.

Библиотека классов Microsoft Foundation предоставляет следующие глобальные функции в afxtempl.h для настройки классов коллекции:

Вспомогательные функции классов коллекции

Имя Описание
CompareElements Указывает, совпадают ли элементы.
CopyElements Копирует элементы из одного массива в другой.
DumpElements Предоставляет выходные данные диагностики, ориентированные на поток.
HashKey Вычисляет хэш-ключ.
SerializeElements Хранит или извлекает элементы из архива.

CompareElements

Вызывается напрямую CList::Find и косвенно.CMap::LookupCMap::operator[]

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

Параметры

TYPE
Тип первого элемента, который необходимо сравнить.

pElement1
Указатель на первый элемент для сравнения.

ARG_TYPE
Тип второго элемента, который необходимо сравнить.

pElement2
Указатель на второй элемент для сравнения.

Возвращаемое значение

Ненулевое значение, если объект, на который указывает pElement1, равен объекту, на который указывает pElement2; в противном случае — 0.

Замечания

Вызовы CMap используют CMap параметры шаблона KEY и ARG_KEY.

Реализация по умолчанию возвращает результат сравнения *pElement1 и *pElement2. Переопределите эту функцию, чтобы она сравнивала элементы таким образом, чтобы оно соответствовало вашему приложению.

Язык C++ определяет оператор ==сравнения () для простых типов (char, и intfloatт. д.), но не определяет оператор сравнения для классов и структур. Если вы хотите использовать CompareElements или создать экземпляр одного из классов коллекции, использующих его, необходимо определить оператор сравнения или перегрузку CompareElements с версией, которая возвращает соответствующие значения.

Требования

Заголовок: afxtempl.h

CopyElements

Эта функция вызывается непосредственно CArray::Append и CArray::Copy.

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

Параметры

TYPE
Параметр шаблона, указывающий тип скопированных элементов.

pDest
Указатель на место, в котором будут скопированы элементы.

Psrc
Указатель на источник скопированных элементов.

Ncount
Количество скопированных элементов.

Замечания

Реализация по умолчанию использует простой оператор назначения ( = ) для выполнения операции копирования. Если скопированный тип не имеет перегруженного оператора=, реализация по умолчанию выполняет побитовую копию.

Сведения о реализации этих и других вспомогательных функций см. в статьях Collections: How to Make a Type-Сейф Collection.

Требования

Заголовок afxtempl.h

DumpElements

Предоставляет потокоориентированные диагностические выходные данные в текстовой форме для элементов коллекции при переопределении.

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

Параметры

dc
Контекст дампа для элементов дампа.

TYPE
Параметр шаблона, указывающий тип элементов.

pElements
Указатель на элементы для дампа.

Ncount
Количество элементов для дампа.

Замечания

Функция CArray::Dump, CList::Dumpи CMap::Dump функции вызывают это, если глубина дампа больше 0.

Реализация по умолчанию не выполняет никаких действий. Если элементы коллекции являются производными CObject, переопределение обычно будет итерировать через элементы коллекции, вызывая Dump каждый элемент в свою очередь.

Требования

Заголовок afxtempl.h

HashKey

Вычисляет хэш-значение для заданного ключа.

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

Параметры

ARG_KEY
Параметр шаблона, указывающий тип данных, используемый для доступа к ключам карты.

key
Ключ, хэш-значение которого требуется вычислить.

Возвращаемое значение

Хэш-значение ключа.

Замечания

Эта функция вызывается напрямую CMap::RemoveKey и косвенно.CMap::LookupCMap::operator[]

Реализация по умолчанию создает хэш-значение путем перемещения ключа вправо на четыре позиции. Переопределите эту функцию, чтобы она возвращала хэш-значения, соответствующие приложению.

Пример

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));
}

Требования

Заголовок afxtempl.h

SerializeElements

CArray, CList и CMap вызывают эту функцию для сериализации элементов.

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

Параметры

TYPE
Параметр шаблона, указывающий тип элементов.

Ar
Архивный объект для архивации в или из нее.

pElements
Указатель на элементы, архивируемые.

Ncount
Число архивируемых элементов

Замечания

Реализация по умолчанию выполняет побитовое чтение или запись.

Сведения о реализации этих и других вспомогательных функций см. в статьях Collections: How to Make a Type-Сейф Collection.

Пример

См. пример в статьях Collections: How to Make a Type-Сейф Collection.

Требования

Заголовок afxtempl.h

См. также

Макросы и глобальные
Класс CMap
Класс CList
Класс CArray