Класс 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.
См. также
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по