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


Класс CAtlMap

Этот класс предоставляет методы для создания объекта карты и управления ими.

Синтаксис

template <typename K,
          typename V,
          class KTraits = CElementTraits<K>,
          class VTraits = CElementTraits<V>>
class CAtlMap

Параметры

K
Тип ключевого элемента.

V
Тип элемента value.

KTraits
Код, используемый для копирования или перемещения ключевых элементов. Дополнительные сведения см. в классе CElementTraits.

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

Участники

Общедоступные определения типов

Имя Описание
CAtlMap::KINARGTYPE Тип, используемый при передаче ключа в качестве входного аргумента
CAtlMap::KOUTARGTYPE Тип, используемый при возврате ключа в качестве выходного аргумента.
CAtlMap::VINARGTYPE Тип, используемый при передаче значения в качестве входного аргумента.
CAtlMap::VOUTARGTYPE Тип, используемый при передаче значения в качестве выходного аргумента.

Открытые классы

Имя Описание
Класс CAtlMap::CPair Класс, содержащий элементы ключа и значения.

Члены данных CPair

Имя Описание
CPair::m_key Элемент данных, в котором хранится ключевой элемент.
CPair::m_value Элемент данных, в котором хранится элемент value.

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

Имя Описание
CAtlMap::CAtlMap Конструктор.
CAtlMap::~CAtlMap Деструктор

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

Имя Описание
CAtlMap::AssertValid Вызовите этот метод, чтобы вызвать УТВЕРЖДЕНИЕ, если CAtlMap недопустимо.
CAtlMap::D isableAutoRehash Вызовите этот метод, чтобы отключить автоматическую перенашивание CAtlMap объекта.
CAtlMap::EnableAutoRehash Вызовите этот метод, чтобы включить автоматическую перенашивание CAtlMap объекта.
CAtlMap::GetAt Вызовите этот метод, чтобы вернуть элемент по заданной позиции в карте.
CAtlMap::GetCount Вызовите этот метод, чтобы получить количество элементов в карте.
CAtlMap::GetHashTableSize Вызовите этот метод, чтобы определить количество ячеек в хэш-таблице карты.
CAtlMap::GetKeyAt Вызовите этот метод, чтобы получить ключ, хранящийся в заданной позиции в объекте CAtlMap .
CAtlMap::GetNext Вызовите этот метод, чтобы получить указатель на следующую пару элементов, хранящуюся в объекте CAtlMap .
CAtlMap::GetNextAssoc Возвращает следующий элемент для итерации.
CAtlMap::GetNextKey Вызовите этот метод, чтобы получить следующий ключ из CAtlMap объекта.
CAtlMap::GetNextValue Вызовите этот метод, чтобы получить следующее CAtlMap значение из объекта.
CAtlMap::GetStartPosition Вызовите этот метод, чтобы запустить итерацию карты.
CAtlMap::GetValueAt Вызовите этот метод, чтобы получить значение, хранящееся в заданной позиции в объекте CAtlMap .
CAtlMap::InitHashTable Вызовите этот метод для инициализации хэш-таблицы.
CAtlMap::IsEmpty Вызовите этот метод для проверки пустого объекта карты.
CAtlMap::Lookup Вызовите этот метод для поиска ключей или значений в объекте CAtlMap .
CAtlMap::Rehash Вызовите этот метод, чтобы перенашить CAtlMap объект.
CAtlMap::RemoveAll Вызовите этот метод, чтобы удалить все элементы из CAtlMap объекта.
CAtlMap::RemoveAtPos Вызовите этот метод, чтобы удалить элемент в заданной позиции в объекте CAtlMap .
CAtlMap::RemoveKey Вызовите этот метод, чтобы удалить элемент из CAtlMap объекта, учитывая ключ.
CAtlMap::SetAt Вызовите этот метод, чтобы вставить пару элементов в карту.
CAtlMap::SetOptimalLoad Вызовите этот метод, чтобы задать оптимальную нагрузку CAtlMap объекта.
CAtlMap::SetValueAt Вызовите этот метод, чтобы изменить значение, хранящееся в заданной позиции в объекте CAtlMap .

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

Имя Описание
CAtlMap::operator[] Заменяет или добавляет новый элемент в элемент CAtlMap.

Замечания

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

Параметры KTraits и VTraits — это классы признаков, содержащие любой дополнительный код, необходимый для копирования или перемещения элементов.

CAtlMap Альтернатива предоставляется классом CRBMap. CRBMap также хранит пары "ключ-значение", но демонстрирует различные характеристики производительности. Время, затраченное на вставку элемента, поиск ключа или удаление ключа из CRBMap объекта, имеет журнал порядка (n), где n — количество элементов. Для CAtlMapвсех этих операций обычно требуется постоянное время, хотя худшие сценарии могут быть порядка n. Таким образом, в типичном случае это CAtlMap быстрее.

Другая разница между CRBMap и CAtlMap становится очевидной при итерации хранимых элементов. В элементе CRBMap, элементы посещаются в отсортированного порядке. В элементе CAtlMap, элементы не упорядочены, и порядок не может быть выведен.

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

Дополнительные сведения см. в разделе "Классы коллекций ATL".

Требования

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

CAtlMap::AssertValid

Вызовите этот метод, чтобы вызвать УТВЕРЖДЕНИЕ, если CAtlMap объект недопустим.

void AssertValid() const;

Замечания

В отладочных сборках этот метод приведет к возникновению ошибки ASSERT, если CAtlMap объект недопустим.

Пример

См. пример CAtlMap ::CAtlMap.

CAtlMap::CAtlMap

Конструктор.

CAtlMap(
    UINT nBins = 17,
    float fOptimalLoad = 0.75f,
    float fLoThreshold = 0.25f,
    float fHiThreshold = 2.25f,
    UINT nBlockSize = 10) throw ();

Параметры

nBins
Количество ячеек, предоставляющих указатели на сохраненные элементы. Дополнительные сведения о ячейках см. далее в этом разделе.

fOptimalLoad
Оптимальное соотношение нагрузки.

fLoThreshold
Меньшее пороговое значение для коэффициента нагрузки.

fHiThreshold
Верхний порог для коэффициента нагрузки.

nBlockSize
Размер блока.

Замечания

CAtlMap ссылается на все сохраненные элементы, сначала создав индекс с помощью хэширования алгоритма ключа. Этот индекс ссылается на "bin", содержащий указатель на сохраненные элементы. Если ячейка уже используется, создается связанный список для доступа к последующим элементам. Обход списка медленнее, чем напрямую доступ к правильному элементу, поэтому структура карты должна сбалансировать требования к хранилищу с учетом производительности. Параметры по умолчанию были выбраны для получения хороших результатов в большинстве случаев.

Коэффициент нагрузки — это соотношение количества ячеек к количеству элементов, хранящихся в объекте карты. При перерасчете структуры карты значение параметра fOptimalLoad будет использоваться для вычисления количества необходимых ячеек. Это значение можно изменить с помощью метода CAtlMap::SetOptimalLoad .

Параметр fLoThreshold — это меньшее значение, которое может достичь коэффициента нагрузки, прежде чем CAtlMap пересчитывать оптимальный размер карты.

Параметр fHiThreshold является верхним значением, которое может достичь коэффициента нагрузки, прежде чем CAtlMap объект перерасчетет оптимальный размер карты.

Этот процесс пересчета (известный как перенашивание) включен по умолчанию. Если вы хотите отключить этот процесс, возможно, при вводе большого количества данных одновременно вызовите метод CAtlMap::D isableAutoRehash . Повторно активируйте его с помощью метода CAtlMap::EnableAutoRehash .

Параметр nBlockSize — это мера объема памяти, выделенного при необходимости нового элемента. Более крупные размеры блоков сокращают вызовы подпрограмм выделения памяти, но используют больше ресурсов.

Перед сохранением любых данных необходимо инициализировать хэш-таблицу с вызовом CAtlMap::InitHashTable.

Пример

// Create a map which stores a double
// value using an integer key

CAtlMap<int, double> mySinTable;
int i;

// Initialize the Hash Table
mySinTable.InitHashTable(257);

// Add items to the map
for (i = 0; i < 90; i++)
   mySinTable[i] = sin((double)i);

// Confirm the map is valid
mySinTable.AssertValid();

// Confirm the number of elements in the map
ATLASSERT(mySinTable.GetCount() == 90);

// Remove elements with even key values
for (i = 0; i < 90; i += 2)
   mySinTable.RemoveKey(i);

// Confirm the number of elements in the map
ATLASSERT(mySinTable.GetCount() == 45);

// Walk through all the elements in the map.
// First, get start position.
POSITION pos;
int key;
double value;
pos = mySinTable.GetStartPosition();

// Now iterate the map, element by element
while (pos != NULL) 
{
   key = mySinTable.GetKeyAt(pos);
   value = mySinTable.GetNextValue(pos);
}

CAtlMap::~CAtlMap

Деструктор

~CAtlMap() throw();

Замечания

Освобождает все выделенные ресурсы.

Класс CAtlMap::CPair

Класс, содержащий элементы ключа и значения.

class CPair : public __POSITION

Замечания

Этот класс используется методами CAtlMap::GetNext и CAtlMap::Lookup для доступа к элементам ключа и значения, хранящимся в структуре сопоставления.

CAtlMap::D isableAutoRehash

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

void DisableAutoRehash() throw();

Замечания

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

DisableAutoRehash наиболее полезно, если в карту будет добавлено большое количество элементов одновременно. Вместо активации процесса повторного кэширования при каждом превышении ограничений эффективнее DisableAutoRehashвызывать, добавлять элементы и, наконец, вызывать CAtlMap::EnableAutoRehash.

CAtlMap::EnableAutoRehash

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

void EnableAutoRehash() throw();

Замечания

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

EnableAutoRefresh чаще всего используется после вызова CAtlMap::D isableAutoRehash.

CAtlMap::GetAt

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

void GetAt(
    POSITION pos,
    KOUTARGTYPE key,
    VOUTARGTYPE value) const;

CPair* GetAt(POSITION& pos) throw();

Параметры

pos
Счетчик позиции, возвращаемый предыдущим вызовом CAtlMap::GetNextAssoc или CAtlMap::GetStartPosition.

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

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

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

Возвращает указатель на текущую пару элементов key/value, хранящихся на карте.

Замечания

В отладочных сборках ошибка утверждения будет возникать, если pos равно NULL.

CAtlMap::GetCount

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

size_t GetCount() const throw();

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

Возвращает количество элементов в объекте карты. Один элемент — это пара "ключ-значение".

Пример

См. пример CAtlMap ::CAtlMap.

CAtlMap::GetHashTableSize

Вызовите этот метод, чтобы определить количество ячеек в хэш-таблице карты.

UINT GetHashTableSize() const throw();

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

Возвращает количество ячеек в хэш-таблице. Описание см. в CAtlMap::CAtlMap .

CAtlMap::GetKeyAt

Вызовите этот метод, чтобы получить ключ, хранящийся в заданной позиции в объекте CAtlMap .

const K& GetKeyAt(POSITION pos) const throw();

Параметры

pos
Счетчик позиции, возвращаемый предыдущим вызовом CAtlMap::GetNextAssoc или CAtlMap::GetStartPosition.

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

Возвращает ссылку на ключ, хранящийся в заданной позиции объекта CAtlMap .

Пример

См. пример CAtlMap ::CAtlMap.

CAtlMap::GetNext

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

CPair* GetNext(POSITION& pos) throw();
const CPair* GetNext(POSITION& pos) const throw();

Параметры

pos
Счетчик позиции, возвращаемый предыдущим вызовом CAtlMap::GetNextAssoc или CAtlMap::GetStartPosition.

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

Возвращает указатель на следующую пару элементов key/value, хранящихся в карте. Счетчик позиции pos обновляется после каждого вызова. Если извлеченный элемент является последним в карте, pos имеет значение NULL.

CAtlMap::GetNextAssoc

Возвращает следующий элемент для итерации.

void GetNextAssoc(
    POSITION& pos,
    KOUTARGTYPE key,
    VOUTARGTYPE value) const;

Параметры

pos
Счетчик позиции, возвращаемый предыдущим вызовом CAtlMap::GetNextAssoc или CAtlMap::GetStartPosition.

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

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

Замечания

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

CAtlMap::GetNextKey

Вызовите этот метод, чтобы получить следующий ключ из CAtlMap объекта.

const K& GetNextKey(POSITION& pos) const throw();

Параметры

pos
Счетчик позиции, возвращаемый предыдущим вызовом CAtlMap::GetNextAssoc или CAtlMap::GetStartPosition.

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

Возвращает ссылку на следующий ключ в карте.

Замечания

Обновляет счетчик текущей позиции, pos. Если в карте нет дополнительных записей, счетчик позиций имеет значение NULL.

CAtlMap::GetNextValue

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

V& GetNextValue(POSITION& pos) throw();
const V& GetNextValue(POSITION& pos) const throw();

Параметры

pos
Счетчик позиции, возвращаемый предыдущим вызовом CAtlMap::GetNextAssoc или CAtlMap::GetStartPosition.

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

Возвращает ссылку на следующее значение в карте.

Замечания

Обновляет счетчик текущей позиции, pos. Если в карте нет дополнительных записей, счетчик позиций имеет значение NULL.

Пример

См. пример CAtlMap ::CAtlMap.

CAtlMap::GetStartPosition

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

POSITION GetStartPosition() const throw();

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

Возвращает начальную позицию или возвращает значение NULL, если карта пуста.

Замечания

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

Примечание.

Последовательность итерации не предсказуема

Пример

См. пример CAtlMap ::CAtlMap.

CAtlMap::GetValueAt

Вызовите этот метод, чтобы получить значение, хранящееся в заданной позиции в объекте CAtlMap .

V& GetValueAt(POSITION pos) throw();
const V& GetValueAt(POSITION pos) const throw();

Параметры

pos
Счетчик позиции, возвращаемый предыдущим вызовом CAtlMap::GetNextAssoc или CAtlMap::GetStartPosition.

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

Возвращает ссылку на значение, хранящееся в заданной позиции объекта CAtlMap .

CAtlMap::InitHashTable

Вызовите этот метод для инициализации хэш-таблицы.

bool InitHashTable(
    UINT nBins,
    bool bAllocNow = true);

Параметры

nBins
Количество ячеек, используемых хэш-таблицей. Описание см. в CAtlMap::CAtlMap .

bAllocNow
Флаг указывает, когда следует выделить память.

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

Возвращает ЗНАЧЕНИЕ TRUE при успешной инициализации, false при сбое.

Замечания

InitHashTable необходимо вызвать перед сохранением элементов в хэш-таблице. Если этот метод не вызывается явным образом, он будет вызываться автоматически при первом добавлении элемента с помощью счетчика двоичных объектов, указанных конструктором CAtlMap . В противном случае карта будет инициализирована с помощью нового количества двоичных объектов, указанных параметром nBins .

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

Пример

См. пример CAtlMap ::CAtlMap.

CAtlMap::IsEmpty

Вызовите этот метод для проверки пустого объекта карты.

bool IsEmpty() const throw();

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

Возвращает значение TRUE, если карта пуста, значение FALSE в противном случае.

CAtlMap::KINARGTYPE

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

typedef KTraits::INARGTYPE KINARGTYPE;

CAtlMap::KOUTARGTYPE

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

typedef KTraits::OUTARGTYPE KOUTARGTYPE;

CAtlMap::Lookup

Вызовите этот метод для поиска ключей или значений в объекте CAtlMap .

bool Lookup(KINARGTYPE key, VOUTARGTYPE value) const;
const CPair* Lookup(KINARGTYPE key) const throw();
CPair* Lookup(KINARGTYPE key) throw();

Параметры

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

значение
Переменная, получающая значение подстановки.

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

Первая форма метода возвращает значение true, если ключ найден, в противном случае — false. Второй и третий формы возвращают указатель на CPair , который можно использовать в качестве позиции для вызовов CAtlMap::GetNext и т. д.

Замечания

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

CAtlMap::operator []

Заменяет или добавляет новый элемент в элемент CAtlMap.

V& operator[](kinargtype key) throw();

Параметры

key
Ключ элемента для добавления или замены.

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

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

Пример

Если ключ уже существует, элемент заменяется. Если ключ не существует, добавляется новый элемент. См. пример CAtlMap ::CAtlMap.

CAtlMap::Rehash

Вызовите этот метод, чтобы перенашить CAtlMap объект.

void Rehash(UINT nBins = 0);

Параметры

nBins
Новое число ячеек, используемых в хэш-таблице. Описание см. в CAtlMap::CAtlMap .

Замечания

Если nBins равно 0, CAtlMap вычисляет разумное число на основе количества элементов в карте и оптимального параметра нагрузки. Обычно процесс повторного кэширования выполняется автоматически, но если вызывается CAtlMap::D isableAutoRehash , этот метод выполнит необходимый размер.

CAtlMap::RemoveAll

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

void RemoveAll() throw();

Замечания

Очищает CAtlMap объект, освобождая память, используемую для хранения элементов.

CAtlMap::RemoveAtPos

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

void RemoveAtPos(POSITION pos) throw();

Параметры

pos
Счетчик позиции, возвращаемый предыдущим вызовом CAtlMap::GetNextAssoc или CAtlMap::GetStartPosition.

Замечания

Удаляет пару "ключ-значение", хранящуюся в указанной позиции. Память, используемая для хранения элемента, освобождается. Позиция, на которую ссылается pos, становится недопустимой, и в то время как позиция любых других элементов в карте остается допустимой, они не обязательно сохраняют тот же порядок.

CAtlMap::RemoveKey

Вызовите этот метод, чтобы удалить элемент из CAtlMap объекта, учитывая ключ.

bool RemoveKey(KINARGTYPE key) throw();

Параметры

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

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

Возвращает значение TRUE, если ключ найден и удален, false при сбое.

Пример

См. пример CAtlMap ::CAtlMap.

CAtlMap::SetAt

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

POSITION SetAt(
    KINARGTYPE key,
    VINARGTYPE value);

Параметры

key
Значение ключа для добавления в CAtlMap объект.

значение
Значение, добавляемое в CAtlMap объект.

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

Возвращает позицию пары элементов key/value в объекте CAtlMap .

Замечания

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

CAtlMap::SetOptimalLoad

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

void SetOptimalLoad(
    float fOptimalLoad,
    float fLoThreshold,
    float fHiThreshold,
    bool bRehashNow = false);

Параметры

fOptimalLoad
Оптимальное соотношение нагрузки.

fLoThreshold
Меньшее пороговое значение для коэффициента нагрузки.

fHiThreshold
Верхний порог для коэффициента нагрузки.

bRehashNow
Флаг, указывающий, следует ли пересчитывать хэш-таблицу.

Замечания

Этот метод переопределяет оптимальное значение нагрузки для CAtlMap объекта. Сведения о различных параметрах см. в CAtlMap::CAtlMap . Если bRehashNow имеет значение true, а количество элементов выходит за пределы минимального и максимального значений, хэш-таблица вычисляется повторно.

CAtlMap::SetValueAt

Вызовите этот метод, чтобы изменить значение, хранящееся в заданной позиции в объекте CAtlMap .

void SetValueAt(
    POSITION pos,
    VINARGTYPE value);

Параметры

pos
Счетчик позиции, возвращаемый предыдущим вызовом CAtlMap::GetNextAssoc или CAtlMap::GetStartPosition.

значение
Значение, добавляемое в CAtlMap объект.

Замечания

Изменяет элемент значения, хранящийся в заданной позиции в объекте CAtlMap .

CAtlMap::VINARGTYPE

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

typedef VTraits::INARGTYPE VINARGTYPE;

CAtlMap::VOUTARGTYPE

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

typedef VTraits::OUTARGTYPE VOUTARGTYPE;

CAtlMap::CPair::m_key

Элемент данных, в котором хранится ключевой элемент.

const K m_key;

Параметры

K
Тип ключевого элемента.

CAtlMap::CPair::m_value

Элемент данных, в котором хранится элемент value.

V  m_value;

Параметры

V
Тип элемента value.

См. также

Пример marquee
Пример обновленияPV
Общие сведения о классе