Прочитать на английском

Поделиться через

Класс CMap

  • Статья

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

Синтаксис

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 Класс
Диаграмма иерархии