Класс CMapStringToOb

Класс коллекции словаря, который сопоставляет уникальные объекты CString с указателями CObject .

Синтаксис

class CMapStringToOb : public CObject

Участники

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

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

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

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

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

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

Замечания

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

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

CMapStringToOb использует макрос IMPLEMENT_SERIAL для поддержки сериализации и записи элементов в дамп. Каждый элемент сериализуется в свою очередь, если карта хранится в архиве, либо с перегруженным оператором вставки ( <<) или функцией-членом Serialize .

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

CMapStringToOb При удалении объекта или при удалении CString его элементов удаляются объекты и CObject указатели. Объекты, на которые CObject ссылаются указатели, не уничтожаются.

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

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

CObject

CMapStringToOb

Требования

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

CMapStringToOb::CMapStringToOb

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

CMapStringToOb(INT_PTR nBlockSize = 10);

Параметры

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

Замечания

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

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb:: CMapStringToObна .

Класс	Функция-член
CMapPtrToPtr	CMapPtrToPtr( INT_PTR nBlockSize = 10 );
CMapPtrToWord	CMapPtrToWord( INT_PTR nBlockSize = 10 );
CMapStringToPtr	CMapStringToPtr( INT_PTR nBlockSize = 10 );
CMapStringToString	CMapStringToString( INT_PTR nBlockSize = 10 );
CMapWordToOb	CMapWordToOb( INT_PTR nBlockSize = 10 );
CMapWordToPtr	MapWordToPtr( INT_PTR nBlockSize = 10 );

Пример

CMapStringToOb map(20); // Map on the stack with blocksize of 20

CMapStringToOb *pm = new CMapStringToOb; // Map on the heap
                                         // with default blocksize

См CObList::CObList . описание класса, используемого CAge во всех примерах коллекции.

CMapStringToOb::GetCount

Определяет, сколько элементов находятся на карте.

INT_PTR GetCount() const;

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

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

Замечания

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb::GetCountна .

Класс	Функция-член
CMapPtrToPtr	INT_PTR GetCount() const;
CMapPtrToWord	INT_PTR GetCount() const;
CMapStringToPtr	INT_PTR GetCount() const;
CMapStringToString	INT_PTR GetCount() const;
CMapWordToOb	INT_PTR GetCount() const;
CMapWordToPtr	INT_PTR GetCount() const;

Пример

См CObList::CObList . описание класса, используемого CAge во всех примерах коллекции.

CMapStringToOb map;

map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Homer"), new CAge(36));
ASSERT(map.GetCount() == 2);

CMapStringToOb::GetHashTableSize

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

UINT GetHashTableSize() const;

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

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

Замечания

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb::GetHashTableSizeна .

Класс	Функция-член
CMapPtrToPtr	UINT GetHashTableSize() const;
CMapPtrToWord	UINT GetHashTableSize() const;
CMapStringToPtr	UINT GetHashTableSize() const;
CMapStringToString	UINT GetHashTableSize() const;
CMapWordToOb	UINT GetHashTableSize() const;
CMapWordToPtr	UINT GetHashTableSize() const;

CMapStringToOb::GetNextAssoc

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

void GetNextAssoc(
    POSITION& rNextPosition,
    CString& rKey,
    CObject*& rValue) const;

Параметры

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

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

rValue
Указывает возвращаемое значение извлеченного элемента ( CObject указатель). Дополнительные сведения об этом параметре см . в примечаниях .

Замечания

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

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

rValue Для параметра обязательно приведите тип CObject*&объекта к тому, что требует компилятор, как показано в следующем примере:

CObject *ob;
map.GetNextAssoc(pos, key, (CObject *&)ob);

Это не верно GetNextAssoc для карт на основе шаблонов.

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb::GetNextAssocна .

Класс	Функция-член
CMapPtrToPtr	void GetNextAssoc( POSITION& rNextPosition , void*& rKey , void*& rValue ) const;
CMapPtrToWord	void GetNextAssoc( POSITION& rNextPosition , void*& rKey , WORD& rValue ) const;
CMapStringToPtr	void GetNextAssoc( POSITION& rNextPosition , CString& rKey , void*& rValue ) const;
CMapStringToString	void GetNextAssoc( POSITION& rNextPosition , CString& rKey , CString& rValue ) const;
CMapWordToOb	void GetNextAssoc( POSITION& rNextPosition , WORD& rKey , CObject*& rValue ) const;
CMapWordToPtr	void GetNextAssoc( POSITION& rNextPosition , WORD& rKey , void*& rValue ) const;

Пример

См CObList::CObList . описание класса, используемого CAge во всех примерах коллекции.

CMapStringToOb map;
POSITION pos;
CString key;
CAge *pa;

map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Lisa"), new CAge(11));
map.SetAt(_T("Homer"), new CAge(36));
map.SetAt(_T("Marge"), new CAge(35));
// Iterate through the entire map, dumping both name and age.
for (pos = map.GetStartPosition(); pos != NULL;)
{
   map.GetNextAssoc(pos, key, (CObject *&)pa);
#ifdef _DEBUG
   afxDump << key << _T(" : ") << pa << _T("\n");
#endif
}

Результаты этой программы приведены следующим образом:

Lisa : a CAge at $4724 11
Marge : a CAge at $47A8 35
Homer : a CAge at $4766 36
Bart : a CAge at $45D4 13

CMapStringToOb::GetSize

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

INT_PTR GetSize() const;

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

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

Замечания

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

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb::GetSizeна .

Класс	Функция-член
CMapPtrToPtr	INT_PTR GetSize() const;
CMapPtrToWord	INT_PTR GetSize() const;
CMapStringToPtr	INT_PTR GetSize() const;
CMapStringToString	INT_PTR GetSize() const;
CMapWordToOb	INT_PTR GetSize() const;
CMapWordToPtr	INT_PTR GetSize() const;

Пример

CMapStringToOb map;

map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Homer"), new CAge(36));
ASSERT(map.GetSize() == 2);

CMapStringToOb::GetStartPosition

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

POSITION GetStartPosition() const;

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

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

Замечания

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

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb::GetStartPositionна .

Класс	Функция-член
CMapPtrToPtr	POSITION GetStartPosition() const;
CMapPtrToWord	POSITION GetStartPosition() const;
CMapStringToPtr	POSITION GetStartPosition() const;
CMapStringToString	POSITION GetStartPosition() const;
CMapWordToOb	POSITION GetStartPosition() const;
CMapWordToPtr	POSITION GetStartPosition() const;

Пример

Пример см. в примере CMapStringToOb::GetNextAssoc.

CMapStringToOb::HashKey

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

UINT HashKey(LPCTSTR key) const;

Параметры

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

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

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

Замечания

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb::HashKeyна .

Класс	Функция-член
CMapPtrToPtr	UINT HashKey( void *key ) const;
CMapPtrToWord	UINT HashKey( void *key ) const;
CMapStringToString	UINT HashKey( LPCTSTR key ) const;
CMapStringToPtr	UINT HashKey( LPCTSTR key ) const;
CMapWordToOb	UINT HashKey( WORD key ) const;
CMapWordToPtr	UINT HashKey( WORD key ) const;

CMapStringToOb::InitHashTable

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

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

Параметры

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

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

Замечания

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

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb::InitHashTableна .

Класс	Функция-член
CMapPtrToPtr	void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapPtrToWord	void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapStringToString	void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapStringToPtr	void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapWordToOb	void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapWordToPtr	void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );

CMapStringToOb::IsEmpty

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

BOOL IsEmpty() const;

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

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

Пример

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

Замечания

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb:: IsEmptyна .

Класс	Функция-член
CMapPtrToPtr	BOOL IsEmpty() const;
CMapPtrToWord	BOOL IsEmpty() const;
CMapStringToPtr	BOOL IsEmpty() const;
CMapStringToString	BOOL IsEmpty() const;
CMapWordToOb	BOOL IsEmpty() const;
CMapWordToPtr	BOOL IsEmpty() const;

CMapStringToOb::Lookup

CObject Возвращает указатель на CString основе значения.

BOOL Lookup(
    LPCTSTR key,
    CObject*& rValue) const;

Параметры

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

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

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

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

Замечания

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

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb::LookUpна .

Класс	Функция-член
CMapPtrToPtr	BOOL Lookup( void *key , void*& rValue ) const;
CMapPtrToWord	BOOL Lookup( void *key , WORD& rValue ) const;
CMapStringToPtr	BOOL Lookup( LPCTSTR key , void*& rValue ) const;
CMapStringToString	BOOL Lookup( LPCTSTR key , CString& rValue ) const;
CMapWordToOb	BOOL Lookup( WORD key , CObject*& rValue ) const;
CMapWordToPtr	BOOL Lookup( WORD key , void*& rValue ) const;

Пример

См CObList::CObList . описание класса, используемого CAge во всех примерах коллекции.

CMapStringToOb map;
CAge *pa;

map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Lisa"), new CAge(11));
map.SetAt(_T("Homer"), new CAge(36));
map.SetAt(_T("Marge"), new CAge(35));
ASSERT(map.Lookup(_T("Lisa"), (CObject *&)pa)); // Is "Lisa" in the map?
ASSERT(*pa == CAge(11));                        // Is she 11?

CMapStringToOb::LookupKey

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

BOOL LookupKey(
    LPCTSTR key,
    LPCTSTR& rKey) const;

Параметры

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

rKey
Ссылка на связанный ключ.

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

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

Замечания

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

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb:: LookupKeyна .

Класс	Функция-член
CMapStringToPtr	BOOL LookupKey( LPCTSTR key , LPCTSTR& rKey ) const;
CMapStringToString	BOOL LookupKey( LPCTSTR key , LPCTSTR& rKey ) const;

CMapStringToOb::operator [ ]

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

CObject*& operator[ ](lpctstr key);

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

Ссылка на указатель CObject на объект; или NULL если карта пуста или key не находится в диапазоне.

Замечания

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

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

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb::operator []на .

Класс	Функция-член
CMapPtrToPtr	void*& operator[](void *key );
CMapPtrToWord	WORD& operator[](void *key );
CMapStringToPtr	void*& operator[](lpctstr key );
CMapStringToString	CString& operator[](lpctstr key );
CMapWordToOb	CObject*& operator[](word key );
CMapWordToPtr	void*& operator[](word key );

Пример

См CObList::CObList . описание класса, используемого CAge во всех примерах коллекции.

CMapStringToOb map;

map[_T("Bart")] = new CAge(13);
map[_T("Lisa")] = new CAge(11);
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("Operator [] example: ") << &map << _T("\n");
#endif

Результаты этой программы приведены следующим образом:

Operator [] example: A CMapStringToOb with 2 elements
[Lisa] = a CAge at $4A02 11
[Bart] = a CAge at $497E 13

CMapStringToOb::RemoveAll

Удаляет все элементы из этой карты и уничтожает ключевые CString объекты.

void RemoveAll();

Замечания

Объекты CObject , на которые ссылается каждый ключ, не уничтожаются. Функция RemoveAll может привести к утечке памяти, если вы не гарантируете, что указанные CObject объекты уничтожены.

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

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb::RemoveAllна .

Класс	Функция-член
CMapPtrToPtr	void RemoveAll();
CMapPtrToWord	void RemoveAll();
CMapStringToPtr	void RemoveAll();
CMapStringToString	void RemoveAll();
CMapWordToOb	void RemoveAll();
CMapWordToPtr	void RemoveAll();

Пример

См CObList::CObList . описание класса, используемого CAge во всех примерах коллекции.

{
   CMapStringToOb map;

   CAge age1(13); // Two objects on the stack
   CAge age2(36);
   map.SetAt(_T("Bart"), &age1);
   map.SetAt(_T("Homer"), &age2);
   ASSERT(map.GetCount() == 2);
   map.RemoveAll(); // CObject pointers removed; objects not removed.
   ASSERT(map.GetCount() == 0);
   ASSERT(map.IsEmpty());
} // The two CAge objects are deleted when they go out of scope.

CMapStringToOb::RemoveKey

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

BOOL RemoveKey(LPCTSTR key);

Параметры

key
Указывает строку, используемую для поиска карты.

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

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

Замечания

Это может привести к утечке памяти, если CObject объект не удаляется в другом месте.

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb::RemoveKeyна .

Класс	Функция-член
CMapPtrToPtr	BOOL RemoveKey( void *key );
CMapPtrToWord	BOOL RemoveKey( void *key );
CMapStringToPtr	BOOL RemoveKey( LPCTSTR key );
CMapStringToString	BOOL RemoveKey( LPCTSTR key );
CMapWordToOb	BOOL RemoveKey( WORD key );
CMapWordToPtr	BOOL RemoveKey( WORD key );

Пример

См CObList::CObList . описание класса, используемого CAge во всех примерах коллекции.

CMapStringToOb map;

map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Lisa"), new CAge(11));
map.SetAt(_T("Homer"), new CAge(36));
map.SetAt(_T("Marge"), new CAge(35));
map.RemoveKey(_T("Lisa")); // Memory leak: CAge object not
                           // deleted.
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("RemoveKey example: ") << &map << _T("\n");
#endif

Результаты этой программы приведены следующим образом:

RemoveKey example: A CMapStringToOb with 3 elements
[Marge] = a CAge at $49A0 35
[Homer] = a CAge at $495E 36
[Bart] = a CAge at $4634 13

CMapStringToOb::SetAt

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

void SetAt(
    LPCTSTR key,
    CObject* newValue);

Параметры

key
Указывает строку, которая является ключом нового элемента.

newValue
Указывает CObject указатель, который является значением нового элемента.

Замечания

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

В следующей таблице показаны другие функции-члены, которые похожи CMapStringToOb::SetAtна .

Класс	Функция-член
CMapPtrToPtr	void SetAt( void *key , void *newValue );
CMapPtrToWord	void SetAt( void *key , WORD newValue );
CMapStringToPtr	void SetAt( LPCTSTR key , void *newValue );
CMapStringToString	void SetAt( LPCTSTR key , LPCTSTR newValue );
CMapWordToOb	void SetAt( WORD key , CObject *newValue );
CMapWordToPtr	void SetAt( WORD key , void *newValue );

Пример

См CObList::CObList . описание класса, используемого CAge во всех примерах коллекции.

CMapStringToOb map;
CAge *pa;

map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Lisa"), new CAge(11)); // Map contains 2
                                     // elements.
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("before Lisa's birthday: ") << &map << _T("\n");
#endif
if (map.Lookup(_T("Lisa"), (CObject *&)pa))
{ // CAge 12 pointer replaces CAge 11 pointer.
   map.SetAt(_T("Lisa"), new CAge(12));
   delete pa; // Must delete CAge 11 to avoid memory leak.
}
#ifdef _DEBUG
afxDump << _T("after Lisa's birthday: ") << &map << _T("\n");
#endif

Результаты этой программы приведены следующим образом:

before Lisa's birthday: A CMapStringToOb with 2 elements
[Lisa] = a CAge at $493C 11
[Bart] = a CAge at $4654 13
after Lisa's birthday: A CMapStringToOb with 2 elements
[Lisa] = a CAge at $49C0 12
[Bart] = a CAge at $4654 13

См. также

CObject Класс
Диаграмма иерархии
CMapPtrToPtr Класс
CMapPtrToWord Класс
CMapStringToPtr Класс
CMapStringToString Класс
CMapWordToOb Класс
CMapWordToPtr Класс