CMap Klasa

Klasa kolekcji słowników, która mapuje unikatowe klucze na wartości.

Składnia

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

Parametry

KEY
Klasa obiektu używana jako klucz do mapy.

ARG_KEY
Typ danych używany dla KEY argumentów; zwykle odwołanie do KEYelementu .

VALUE
Klasa obiektu przechowywanego na mapie.

ARG_VALUE
Typ danych używany dla VALUE argumentów; zwykle odwołanie do VALUEelementu .

Członkowie

Struktury publiczne

Nazwa/nazwisko	opis
CMap::CPair	Zagnieżdżona struktura zawierająca wartość klucza i wartość skojarzonego obiektu.

Konstruktory publiczne

Nazwa/nazwisko	opis
CMap::CMap	Tworzy kolekcję, która mapuje klucze na wartości.

Metody publiczne

Nazwa/nazwisko	opis
CMap::GetCount	Zwraca liczbę elementów na tej mapie.
CMap::GetHashTableSize	Zwraca liczbę elementów w tabeli skrótów.
CMap::GetNextAssoc	Pobiera następny element do iteracji.
CMap::GetSize	Zwraca liczbę elementów na tej mapie.
CMap::GetStartPosition	Zwraca pozycję pierwszego elementu.
CMap::InitHashTable	Inicjuje tabelę skrótów i określa jej rozmiar.
CMap::IsEmpty	Testy warunku pustej mapy (brak elementów).
CMap::Lookup	Wyszukuje wartość zamapowana na dany klucz.
CMap::PGetFirstAssoc	Zwraca wskaźnik do pierwszego elementu.
CMap::PGetNextAssoc	Pobiera wskaźnik do następnego elementu na potrzeby iteracji.
CMap::PLookup	Zwraca wskaźnik do klucza, którego wartość jest zgodna z określoną wartością.
CMap::RemoveAll	Usuwa wszystkie elementy z tej mapy.
CMap::RemoveKey	Usuwa element określony przez klucz.
CMap::SetAt	Wstawia element do mapy; zastępuje istniejący element, jeśli zostanie znaleziony pasujący klucz.

Operatory publiczne

Nazwa/nazwisko	opis
CMap::operator [ ]	Wstawia element do mapy — podstawianie operatora dla SetAtelementu .

Uwagi

Po wstawieniu pary klucz-wartość (element) do mapy można efektywnie pobrać lub usunąć parę przy użyciu klucza, aby uzyskać do niej dostęp. Można również iterować wszystkie elementy na mapie.

Zmienna typu POSITION jest używana do dostępu alternatywnego do wpisów. Możesz użyć elementu POSITION , aby "zapamiętać" wpis i wykonać iterację po mapie. Można pomyśleć, że ta iteracja jest sekwencja według wartości klucza; to nie jest. Sekwencja pobranych elementów jest nieokreślona.

Niektóre funkcje składowe tej klasy wywołają globalne funkcje pomocnika, które muszą być dostosowane do większości zastosowań CMap klasy. Zobacz Pomocnicy klas kolekcji w sekcji Makra i globals w dokumentacji MFC.

CMap zastępuje obsługę CObject::Serialize serializacji i dumpingu jej elementów. Jeśli mapa jest przechowywana w archiwum przy użyciu Serializeelementu , każdy element mapy jest serializowany z kolei. Domyślna implementacja SerializeElements funkcji pomocnika wykonuje bitowe zapisy. Aby uzyskać informacje o serializacji elementów kolekcji wskaźników pochodzących z CObject lub innych typów zdefiniowanych przez użytkownika, zobacz How to: Make a Type-Sejf Collection (Instrukcje: tworzenie kolekcji typu Sejf).

Jeśli potrzebujesz zrzutu diagnostycznego poszczególnych elementów na mapie (klucze i wartości), musisz ustawić głębokość kontekstu zrzutu na 1 lub większą.

CMap Gdy obiekt zostanie usunięty lub gdy jego elementy zostaną usunięte, oba klucze i wartości zostaną usunięte.

Wyprowadzanie klas map jest podobne do wyprowadzania listy. Zobacz artykuł Kolekcje , aby zapoznać się z ilustracją wyprowadzania klasy listy specjalnego przeznaczenia.

Hierarchia dziedziczenia

CObject

CMap

Wymagania

Nagłówka:afxtempl.h

CMap::CMap

Tworzy pustą mapę.

CMap(INT_PTR nBlockSize = 10);

Parametry

nBlockSize
Określa stopień szczegółowości alokacji pamięci na potrzeby rozszerzania mapy.

Uwagi

Wraz ze wzrostem mapy pamięć jest przydzielana w jednostkach nBlockSize wpisów.

Przykład

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

CMap::CPair

Zawiera wartość klucza i wartość skojarzonego obiektu.

Uwagi

Jest to struktura zagnieżdżona w klasie CMap.

Struktura składa się z dwóch pól:

• key Rzeczywista wartość typu klucza.

• value Wartość skojarzonego obiektu.

Służy do przechowywania wartości zwracanych z CMap::PLookup, CMap::PGetFirstAssoci CMap::PGetNextAssoc.

Przykład

Przykład użycia można znaleźć w przykładzie .CMap::PLookup

CMap::GetCount

Pobiera liczbę elementów na mapie.

INT_PTR GetCount() const;

Wartość zwracana

Liczba elementów.

Przykład

Zobacz przykład dla elementu CMap::Lookup.

CMap::GetHashTableSize

Określa liczbę elementów w tabeli skrótów dla mapy.

UINT GetHashTableSize() const;

Wartość zwracana

Liczba elementów w tabeli skrótów.

Przykład

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

UINT uTableSize = myMap.GetHashTableSize();

CMap::GetNextAssoc

Pobiera element mapy w rNextPositionlokalizacji , a następnie aktualizuje rNextPosition , aby odwołać się do następnego elementu na mapie.

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

Parametry

rNextPosition
Określa odwołanie do POSITION wartości zwracanej przez poprzednie GetNextAssoc lub GetStartPosition wywołanie.

KEY
Parametr szablonu określający typ klucza mapy.

rKey
Określa zwrócony klucz pobranego elementu.

VALUE
Parametr szablonu określający typ wartości mapy.

rValue
Określa zwracaną wartość pobranego elementu.

Uwagi

Ta funkcja jest najbardziej przydatna do iterowania wszystkich elementów na mapie. Należy pamiętać, że sekwencja pozycji nie musi być taka sama jak sekwencja wartości klucza.

Jeśli pobrany element jest ostatnim elementem na mapie, nowa wartość parametru jest ustawiona rNextPosition na NULLwartość .

Przykład

Zobacz przykład dla elementu CMap::SetAt.

CMap::GetSize

Zwraca liczbę elementów mapy.

INT_PTR GetSize() const;

Wartość zwracana

Liczba elementów na mapie.

Uwagi

Wywołaj tę metodę, aby pobrać liczbę elementów na mapie.

Przykład

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

Uruchamia iterację mapy, zwracając POSITION wartość, którą można przekazać do wywołania GetNextAssoc .

POSITION GetStartPosition() const;

Wartość zwracana

POSITION Wartość wskazująca pozycję początkową do iterowania mapy lub NULL jeśli mapa jest pusta.

Uwagi

Sekwencja iteracji nie jest przewidywalna; dlatego "pierwszy element na mapie" nie ma specjalnego znaczenia.

Przykład

Zobacz przykład dla elementu CMap::SetAt.

CMap::InitHashTable

Inicjuje tabelę skrótów.

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

Parametry

hashSize
Liczba wpisów w tabeli skrótów.

bAllocNow
Jeśli TRUEwartość , przydziela tabelę skrótów podczas inicjowania; w przeciwnym razie tabela zostanie przydzielona w razie potrzeby.

Uwagi

Aby uzyskać najlepszą wydajność, rozmiar tabeli skrótu powinien być liczbą pierwszą. Aby zminimalizować kolizje, rozmiar powinien być około 20 procent większy niż największy przewidywany zestaw danych.

Przykład

Zobacz przykład dla elementu CMap::Lookup.

CMap::IsEmpty

Określa, czy mapa jest pusta.

BOOL IsEmpty() const;

Wartość zwracana

Niezerowe, jeśli ta mapa nie zawiera żadnych elementów; w przeciwnym razie 0.

Przykład

Zobacz przykład dla elementu CMap::RemoveAll.

CMap::Lookup

Wyszukuje wartość zamapowana na dany klucz.

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

Parametry

ARG_KEY
Parametr szablonu określający typ key wartości.

key
Określa klucz, który identyfikuje element do wyszukania.

VALUE
Określa typ wartości do wyszukania.

rValue
Odbiera wyszukaną wartość.

Wartość zwracana

Niezero, jeśli element został znaleziony; w przeciwnym razie 0.

Uwagi

Lookup Używa algorytmu tworzenia skrótów, aby szybko znaleźć element mapy z kluczem, który dokładnie pasuje do danego klucza.

Przykład

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 [ ]

Wygodny zamiennik funkcji składowej SetAt .

VALUE& operator[](arg_key key);

Parametry

VALUE
Parametr szablonu określający typ wartości mapy.

ARG_KEY
Parametr szablonu określający typ wartości klucza.

key
Klucz używany do pobierania wartości z mapy.

Uwagi

W związku z tym można go używać tylko po lewej stronie instrukcji przypisania (l-value). Jeśli nie ma elementu mapy z określonym kluczem, zostanie utworzony nowy element.

Nie ma "prawej strony" (r-value) równoważnej temu operatorowi, ponieważ istnieje możliwość, że klucz może nie zostać znaleziony na mapie. Użyj funkcji składowej do pobierania Lookup elementów.

Przykład

Zobacz przykład dla elementu CMap::Lookup.

CMap::PGetFirstAssoc

Zwraca pierwszy wpis obiektu mapy.

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

Wartość zwracana

Wskaźnik do pierwszego wpisu na mapie; zobacz CMap::CPair. Jeśli mapa nie zawiera żadnych wpisów, wartość to NULL.

Uwagi

Wywołaj tę funkcję, aby zwrócić wskaźnik pierwszego elementu w obiekcie mapy.

Przykład

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

Pobiera element mapy wskazywany przez pAssocRecelement .

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

CPair *PGetNextAssoc(const CPair* pAssocRet);

Parametry

pAssocRet
Wskazuje wpis mapy zwrócony przez poprzednie PGetNextAssoc wywołanie lub CMap::PGetFirstAssoc .

Wartość zwracana

Wskaźnik do następnego wpisu na mapie; zobacz CMap::CPair. Jeśli element jest ostatnim elementem na mapie, wartość to NULL.

Uwagi

Wywołaj tę metodę, aby iterować wszystkie elementy na mapie. Pobierz pierwszy element z wywołaniem metody , PGetFirstAssoc a następnie wykonaj iterację po mapie z kolejnymi wywołaniami metody PGetNextAssoc.

Przykład

Zobacz przykład dla elementu CMap::PGetFirstAssoc.

CMap::PLookup

Znajduje wartość zamapowana na dany klucz.

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

Parametry

key
Klucz do wyszukania elementu.

Wartość zwracana

Wskaźnik do kluczowej struktury; zobacz CMap::CPair. Jeśli nie zostanie znalezione dopasowanie, CMap::PLookup zwraca wartość NULL.

Uwagi

Wywołaj tę metodę, aby wyszukać element mapy z kluczem, który dokładnie pasuje do danego klucza.

Przykład

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

Usuwa wszystkie wartości z tej mapy, wywołując funkcję DestructElementspomocnika globalnego .

void RemoveAll();

Uwagi

Funkcja działa poprawnie, jeśli mapa jest już pusta.

Przykład

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

Wyszukuje wpis mapy odpowiadający podanemu kluczowi; następnie, jeśli klucz zostanie znaleziony, usunie wpis.

BOOL RemoveKey(ARG_KEY key);

Parametry

ARG_KEY
Parametr szablonu określający typ klucza.

key
Klucz do usunięcia elementu.

Wartość zwracana

Nonzero, jeśli wpis został znaleziony i pomyślnie usunięty; w przeciwnym razie 0.

Uwagi

Funkcja DestructElements pomocnika służy do usuwania wpisu.

Przykład

Zobacz przykład dla elementu CMap::SetAt.

CMap::SetAt

Podstawowa oznacza wstawienie elementu na mapie.

void SetAt(ARG_KEY key, ARG_VALUE newValue);

Parametry

ARG_KEY
Parametr szablonu określający typ parametru key .

key
Określa klucz nowego elementu.

ARG_VALUE
Parametr szablonu określający typ parametru newValue .

newValue
Określa wartość nowego elementu.

Uwagi

Najpierw szukany jest klucz. Jeśli klucz zostanie znaleziony, odpowiednia wartość zostanie zmieniona; w przeciwnym razie zostanie utworzona nowa para klucz-wartość.

Przykład

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);
}

Zobacz też

Przykład MFC COLLECT
CObject Klasa
Wykres hierarchii