`CMap` Klasa

Artykuł
10/12/2023

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 .

Elementy członkowskie

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 `SetAt`elementu .

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 na temat serializacji elementów kolekcji wskaźników pochodzących z CObject lub innych typów zdefiniowanych przez użytkownika, zobacz Instrukcje: tworzenie kolekcji bezpiecznej typu.

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łówek: 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

Udostępnij za pośrednictwem

CMap Klasa

Składnia

Parametry

Elementy członkowskie

Struktury publiczne

Konstruktory publiczne

Metody publiczne

Operatory publiczne

Uwagi

Hierarchia dziedziczenia

Wymagania

CMap::CMap

Parametry

Uwagi

Przykład

CMap::CPair

Uwagi

Przykład

CMap::GetCount

Wartość zwracana

Przykład

CMap::GetHashTableSize

Wartość zwracana

Przykład

CMap::GetNextAssoc

Parametry

Uwagi

Przykład

CMap::GetSize

Wartość zwracana

Uwagi

Przykład

CMap::GetStartPosition

Wartość zwracana

Uwagi

Przykład

CMap::InitHashTable

Parametry

Uwagi

Przykład

CMap::IsEmpty

Wartość zwracana

Przykład

CMap::Lookup

Parametry

Wartość zwracana

Uwagi

Przykład

CMap::operator [ ]

Parametry

Uwagi

Przykład

CMap::PGetFirstAssoc

Wartość zwracana

Uwagi

Przykład

CMap::PGetNextAssoc

Parametry

Wartość zwracana

Uwagi

Przykład

CMap::PLookup

Parametry

Wartość zwracana

Uwagi

Przykład

CMap::RemoveAll

Uwagi

Przykład

CMap::RemoveKey

Parametry

Wartość zwracana

Uwagi

Przykład

CMap::SetAt

Parametry

Uwagi

Przykład

Zobacz też

`CMap` Klasa

`CMap::CMap`

`CMap::CPair`

`CMap::GetCount`

`CMap::GetHashTableSize`

`CMap::GetNextAssoc`

`CMap::GetSize`

`CMap::GetStartPosition`

`CMap::InitHashTable`

`CMap::IsEmpty`

`CMap::Lookup`

`CMap::operator [ ]`

`CMap::PGetFirstAssoc`

`CMap::PGetNextAssoc`

`CMap::PLookup`

`CMap::RemoveAll`

`CMap::RemoveKey`

`CMap::SetAt`