Класс `CMap`

Статья
10/12/2023

Класс коллекции словарей, который сопоставляет уникальные ключи значениям.

Синтаксис

template<class KEY, class ARG_KEY, class VALUE, class ARG_VALUE>class CMap : public CObject

Параметры

KEY
Класс объекта, используемого в качестве ключа для карты.

ARG_KEY
Тип данных, используемый для KEY аргументов; обычно ссылка на KEY.

VALUE
Класс объекта, хранящегося на карте.

ARG_VALUE
Тип данных, используемый для VALUE аргументов; обычно ссылка на VALUE.

Участники

Общедоступные структуры

Имя	Описание
`CMap::CPair`	Вложенная структура, содержащая значение ключа и значение связанного объекта.

Открытые конструкторы

Имя	Описание
`CMap::CMap`	Создает коллекцию, которая сопоставляет ключи со значениями.

Открытые методы

Имя	Описание
`CMap::GetCount`	Возвращает количество элементов в этой карте.
`CMap::GetHashTableSize`	Возвращает количество элементов в хэш-таблице.
`CMap::GetNextAssoc`	Возвращает следующий элемент для итерации.
`CMap::GetSize`	Возвращает количество элементов в этой карте.
`CMap::GetStartPosition`	Возвращает положение первого элемента.
`CMap::InitHashTable`	Инициализирует хэш-таблицу и задает его размер.
`CMap::IsEmpty`	Проверяет условие пустой карты (без элементов).
`CMap::Lookup`	Ищет значение, сопоставленное с заданным ключом.
`CMap::PGetFirstAssoc`	Возвращает указатель на первый элемент.
`CMap::PGetNextAssoc`	Возвращает указатель на следующий элемент для итерации.
`CMap::PLookup`	Возвращает указатель на ключ, значение которого соответствует указанному значению.
`CMap::RemoveAll`	Удаляет все элементы из этой карты.
`CMap::RemoveKey`	Удаляет элемент, указанный ключом.
`CMap::SetAt`	Вставляет элемент в карту; заменяет существующий элемент, если найден соответствующий ключ.

Открытые операторы

Имя	Описание
`CMap::operator [ ]`	Вставляет элемент в карту — подстановку `SetAt`оператора.

Замечания

После вставки пары "ключ-значение" (элемент) в карту можно эффективно извлекать или удалять пару с помощью ключа для доступа к ней. Вы также можете выполнить итерацию по всем элементам карты.

Переменная типа POSITION используется для альтернативного доступа к записям. Вы можете использовать POSITION запись "запоминать" и выполнять итерацию по карте. Вы можете подумать, что эта итерация является последовательной по значению ключа; Нет. Последовательность извлеченных элементов является неопределенной.

Некоторые функции-члены этого класса вызывают глобальные вспомогательные функции, которые необходимо настроить для большинства использования CMap класса. Справочные материалы по классам коллекции см. в разделе "Макросы и глобальные" справочника по MFC.

CMap переопределяется CObject::Serialize для поддержки сериализации и дампа его элементов. Если карта хранится в архиве с помощью Serialize, каждый элемент карты сериализуется в свою очередь. Реализация вспомогательной SerializeElements функции по умолчанию выполняет побитовую запись. Сведения о сериализации элементов коллекции указателей, производных от CObject определенных пользователем типов, см. в статье "Практическое руководство. Создание коллекции с типом Сейф".

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

CMap При удалении объекта или при удалении его элементов ключи и значения удаляются.

Производный класс карты аналогичен выводу списка. См. статью "Коллекции" для иллюстрации производных класса списка специального назначения.

Иерархия наследования

CObject

CMap

Требования

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

`CMap::CMap`

Создает пустую карту.

CMap(INT_PTR nBlockSize = 10);

Параметры

nBlockSize
Указывает степень детализации выделения памяти для расширения карты.

Замечания

По мере роста карты память выделяется в единицах nBlockSize записей.

Пример

// declares a map of ints to points
CMap<int, int, CPoint, CPoint> myMap(16);

`CMap::CPair`

Содержит значение ключа и значение связанного объекта.

Замечания

Это вложенная структура в классе CMap.

Структура состоит из двух полей:

key Фактическое значение типа ключа.
value Значение связанного объекта.

Он используется для хранения возвращаемых значений из CMap::PLookup, CMap::PGetFirstAssocи CMap::PGetNextAssoc.

Пример

Пример использования см. в примере.CMap::PLookup

`CMap::GetCount`

Извлекает количество элементов в карте.

INT_PTR GetCount() const;

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

Число элементов.

Пример

Пример см. в примере CMap::Lookup.

`CMap::GetHashTableSize`

Определяет количество элементов в хэш-таблице карты.

UINT GetHashTableSize() const;

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

Количество элементов в хэш-таблице.

Пример

CMap<int, int, CPoint, CPoint> myMap;

UINT uTableSize = myMap.GetHashTableSize();

`CMap::GetNextAssoc`

Извлекает элемент rNextPositionкарты по адресу, а затем обновляется rNextPosition , чтобы ссылаться на следующий элемент в карте.

void GetNextAssoc(
    POSITION& rNextPosition,
    KEY& rKey,
    VALUE& rValue) const;

Параметры

rNextPosition
Указывает ссылку на POSITION значение, возвращаемое предыдущим GetNextAssoc или GetStartPosition вызовом.

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

rKey
Указывает возвращаемый ключ извлеченного элемента.

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

rValue
Указывает возвращаемое значение извлеченного элемента.

Замечания

Эта функция наиболее полезна для итерации всех элементов в карте. Обратите внимание, что последовательность позиций не обязательно совпадает с последовательностью значений ключа.

Если извлеченный элемент является последним в карте, то для нового значения rNextPosition задано значение NULL.

Пример

Пример см. в примере CMap::SetAt.

`CMap::GetSize`

Возвращает количество элементов карты.

INT_PTR GetSize() const;

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

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

Замечания

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

Пример

CMap<int, int, CPoint, CPoint> myMap;

myMap.InitHashTable(257);

// Add 200 elements to the map.
for (int i = 0; i < 200; i++)
{
   myMap[i] = CPoint(i, i);
}

// Remove the elements with even key values.
CPoint pt;
for (int i = 0; myMap.Lookup(i, pt); i += 2)
{
   myMap.RemoveKey(i);
}

ASSERT(myMap.GetSize() == 100);
TRACE(_T("myMap with %d elements:\n"), myMap.GetCount());
POSITION pos = myMap.GetStartPosition();
int iKey;
CPoint ptVal;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, iKey, ptVal);
   TRACE(_T("\t[%d] = (%d,%d)\n"), iKey, ptVal.x, ptVal.y);
}

`CMap::GetStartPosition`

Запускает итерацию карты, возвращая POSITION значение, которое можно передать вызову GetNextAssoc .

POSITION GetStartPosition() const;

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

POSITION Значение, указывающее начальную позицию для итерации карты; или NULL если карта пуста.

Замечания

Последовательность итерации не предсказуема; Таким образом, "первый элемент в карте" не имеет особого значения.

Пример

Пример см. в примере CMap::SetAt.

`CMap::InitHashTable`

Инициализирует хэш-таблицу.

void InitHashTable(UINT hashSize, BOOL  bAllocNow = TRUE);

Параметры

hashSize
Количество записей в хэш-таблице.

bAllocNow
Если TRUE, выделяет хэш-таблицу при инициализации; в противном случае таблица выделяется при необходимости.

Замечания

Для оптимальной производительности хэш-таблица должна быть простым числом. Чтобы свести к минимуму столкновения, размер должен быть примерно на 20 процентов больше, чем самый большой ожидаемый набор данных.

Пример

Пример см. в примере CMap::Lookup.

`CMap::IsEmpty`

Определяет, является ли карта пустой.

BOOL IsEmpty() const;

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

Ненулевое значение, если эта карта не содержит элементов; в противном случае — 0.

Пример

Пример см. в примере CMap::RemoveAll.

`CMap::Lookup`

Ищет значение, сопоставленное с заданным ключом.

BOOL Lookup(ARG_KEY key, VALUE& rValue) const;

Параметры

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

key
Указывает ключ, определяющий элемент для поиска.

VALUE
Указывает тип значения для поиска.

rValue
Получает значение подстановки.

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

Ненулевое значение, если элемент найден; в противном случае — 0.

Замечания

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

Пример

CMap<int, int, CPoint, CPoint> myMap;

myMap.InitHashTable(257);

// Add 200 elements to the map.
for (int i = 0; i < 200; i++)
{
   myMap[i] = CPoint(i, i);
}

// Remove the elements with even key values.
CPoint pt;
for (int i = 0; myMap.Lookup(i, pt); i += 2)
{
   myMap.RemoveKey(i);
}

ASSERT(myMap.GetSize() == 100);
TRACE(_T("myMap with %d elements:\n"), myMap.GetCount());
POSITION pos = myMap.GetStartPosition();
int iKey;
CPoint ptVal;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, iKey, ptVal);
   TRACE(_T("\t[%d] = (%d,%d)\n"), iKey, ptVal.x, ptVal.y);
}

`CMap::operator [ ]`

Удобная замена SetAt функции-члена.

VALUE& operator[](arg_key key);

Параметры

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

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

key
Ключ, используемый для получения значения из карты.

Замечания

Таким образом, его можно использовать только в левой части инструкции назначения (l-value). Если элемент map с указанным ключом отсутствует, создается новый элемент.

Нет эквивалента "правой стороны" (r-value) этому оператору, так как существует вероятность того, что ключ не найден на карте. Используйте функцию-член Lookup для извлечения элементов.

Пример

Пример см. в примере CMap::Lookup.

`CMap::PGetFirstAssoc`

Возвращает первую запись объекта map.

const CPair* PGetFirstAssoc() const;
CPair* PGetFirstAssoc();

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

Указатель на первую запись в карте; см. раздел CMap::CPair. Если карта не содержит записей, значение равно NULL.

Замечания

Вызовите эту функцию, чтобы вернуть указатель на первый элемент в объекте map.

Пример

typedef CMap<int, int, CPoint, CPoint> CMyMap;
CMyMap myMap;

myMap.InitHashTable(257);

// Add 10 elements to the map.
for (int i = 0; i <= 10; i++)
   myMap.SetAt(i, CPoint(i, i));

// Print the element value with even key values.
int nKey = 0;
CPoint pt;
CMyMap::CPair *pCurVal;

pCurVal = myMap.PGetFirstAssoc();
while (pCurVal != NULL)
{
   if ((nKey % 2) == 0)
   {
      _tprintf_s(_T("Current key value at %d: %d,%d\n"),
                 pCurVal->key, pCurVal->value.x, pCurVal->value.y);
   }
   pCurVal = myMap.PGetNextAssoc(pCurVal);
   nKey++;
}

`CMap::PGetNextAssoc`

Извлекает элемент карты, на который указывает pAssocRec.

const CPair *PGetNextAssoc(const CPair* pAssocRet) const;

CPair *PGetNextAssoc(const CPair* pAssocRet);

Параметры

pAssocRet
Указывает на запись карты, возвращаемую предыдущим PGetNextAssoc или CMap::PGetFirstAssoc вызовом.

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

Указатель на следующую запись в карте; см. раздел CMap::CPair. Если элемент является последним в карте, значение равно NULL.

Замечания

Вызовите этот метод для итерации всех элементов карты. Извлеките первый элемент с вызовом PGetFirstAssoc , а затем выполните итерацию по карте с последовательными вызовами PGetNextAssoc.

Пример

Пример см. в примере CMap::PGetFirstAssoc.

`CMap::PLookup`

Находит значение, сопоставленное с заданным ключом.

const CPair* PLookup(ARG_KEY key) const;
CPair* PLookup(ARG_KEY key);

Параметры

key
Ключ для поиска элемента.

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

Указатель на ключевую структуру; см. раздел CMap::CPair. Если совпадение не найдено, CMap::PLookup возвращается NULL.

Замечания

Вызовите этот метод для поиска элемента карты с ключом, который точно соответствует заданному ключу.

Пример

typedef CMap<int, int, CPoint, CPoint> CMyMap;
CMyMap myMap;

myMap.InitHashTable(257);

// Add 10 elements to the map.
for (int i = 0; i <= 10; i++)
   myMap[i] = CPoint(i, i);

// Print the element values with even key values.
CMyMap::CPair *pCurVal;

for (int i = 0; i <= myMap.GetCount(); i += 2)
{
   pCurVal = myMap.PLookup(i);
   _tprintf_s(_T("Current key value at %d: %d,%d\n"),
              pCurVal->key, pCurVal->value.x, pCurVal->value.y);
}

`CMap::RemoveAll`

Удаляет все значения из этой карты путем вызова функции DestructElementsглобального вспомогательного средства.

void RemoveAll();

Замечания

Функция работает правильно, если карта уже пуста.

Пример

CMap<int, int, CPoint, CPoint> myMap;

// Add 10 elements to the map.
for (int i = 0; i < 10; i++)
   myMap.SetAt(i, CPoint(i, i));

myMap.RemoveAll();

ASSERT(myMap.IsEmpty());

`CMap::RemoveKey`

Ищет запись карты, соответствующую предоставленному ключу; Затем, если ключ найден, удаляет запись.

BOOL RemoveKey(ARG_KEY key);

Параметры

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

key
Ключ для удаления элемента.

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

Ненулевое значение, если запись найдена и успешно удалена; в противном случае — 0.

Замечания

Вспомогательные DestructElements функции используются для удаления записи.

Пример

Пример см. в примере CMap::SetAt.

`CMap::SetAt`

Основное средство вставки элемента в карту.

void SetAt(ARG_KEY key, ARG_VALUE newValue);

Параметры

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

key
Указывает ключ нового элемента.

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

newValue
Указывает значение нового элемента.

Замечания

Во-первых, ключ ищется. Если ключ найден, соответствующее значение изменяется; в противном случае создается новая пара "ключ-значение".

Пример

CMap<int, int, CPoint, CPoint> myMap;

// Add 10 elements to the map.
for (int i = 0; i < 10; i++)
   myMap.SetAt(i, CPoint(i, i));

// Remove the elements with even key values.
POSITION pos = myMap.GetStartPosition();
int nKey;
CPoint pt;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, nKey, pt);

   if ((nKey % 2) == 0)
      myMap.RemoveKey(nKey);
}

// Print the element values.
pos = myMap.GetStartPosition();
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, nKey, pt);
   _tprintf_s(_T("Current key value at %d: %d,%d\n"),
              nKey, pt.x, pt.y);
}

См. также

Пример MFC COLLECT
CObject Класса
Диаграмма иерархии

Класс CMap

Синтаксис

Параметры

Участники

Общедоступные структуры

Открытые конструкторы

Открытые методы

Открытые операторы

Замечания

Иерархия наследования

Требования

CMap::CMap

Параметры

Замечания

Пример

CMap::CPair

Замечания

Пример

CMap::GetCount

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

Пример

CMap::GetHashTableSize

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

Пример

CMap::GetNextAssoc

Параметры

Замечания

Пример

CMap::GetSize

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

Замечания

Пример

CMap::GetStartPosition

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

Замечания

Пример

CMap::InitHashTable

Параметры

Замечания

Пример

CMap::IsEmpty

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

Пример

CMap::Lookup

Параметры

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

Замечания

Пример

CMap::operator [ ]

Параметры

Замечания

Пример

CMap::PGetFirstAssoc

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

Замечания

Пример

CMap::PGetNextAssoc

Параметры

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

Замечания

Пример

CMap::PLookup

Параметры

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

Замечания

Пример

CMap::RemoveAll

Замечания

Пример

CMap::RemoveKey

Параметры

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

Замечания

Пример

CMap::SetAt

Параметры

Замечания

Пример

См. также

Обратная связь

Класс `CMap`

`CMap::CMap`

`CMap::CPair`

`CMap::GetCount`

`CMap::GetHashTableSize`

`CMap::GetNextAssoc`

`CMap::GetSize`

`CMap::GetStartPosition`

`CMap::InitHashTable`

`CMap::IsEmpty`

`CMap::Lookup`

`CMap::operator [ ]`

`CMap::PGetFirstAssoc`

`CMap::PGetNextAssoc`

`CMap::PLookup`

`CMap::RemoveAll`

`CMap::RemoveKey`

`CMap::SetAt`