CMap-Klasse

Eine Wörterbuchauflistungsklasse, die eindeutigen Schlüsseln Werte zuordnet.

Syntax

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

Parameter

KEY
Klasse des Objekts, das als Schlüssel für die Karte verwendet wird.

ARG_KEY
Datentyp, der für KEY Argumente verwendet wird; in der Regel ein Verweis auf KEY.

VALUE
Klasse des objekts, das in der Karte gespeichert ist.

ARG_VALUE
Datentyp, der für VALUE Argumente verwendet wird; in der Regel ein Verweis auf VALUE.

Member

Öffentliche Strukturen

Name	Beschreibung
CMap::CPair	Eine geschachtelte Struktur, die einen Schlüsselwert und den Wert des zugeordneten Objekts enthält.

Öffentliche Konstruktoren

Name	Beschreibung
CMap::CMap	Erstellt eine Auflistung, die Schlüssel zu Werten zuordnet.

Öffentliche Methoden

Name	Beschreibung
CMap::GetCount	Gibt die Anzahl der Elemente in dieser Karte zurück.
CMap::GetHashTableSize	Gibt die Anzahl der Elemente in der Hashtabelle zurück.
CMap::GetNextAssoc	Ruft das nächste Element zum Durchlaufen ab.
CMap::GetSize	Gibt die Anzahl der Elemente in dieser Karte zurück.
CMap::GetStartPosition	Gibt die Position des ersten Elements zurück.
CMap::InitHashTable	Initialisiert die Hashtabelle und gibt die Größe an.
CMap::IsEmpty	Testet auf die Bedingung für leere Karten (keine Elemente).
CMap::Lookup	Sucht nach dem Wert, der einem bestimmten Schlüssel zugeordnet ist.
CMap::PGetFirstAssoc	Gibt einen Zeiger auf das erste Element zurück.
CMap::PGetNextAssoc	Ruft einen Zeiger auf das nächste Element zum Durchlaufen ab.
CMap::PLookup	Gibt einen Zeiger auf einen Schlüssel zurück, dessen Wert dem angegebenen Wert entspricht.
CMap::RemoveAll	Entfernt alle Elemente aus dieser Karte.
CMap::RemoveKey	Entfernt ein durch einen Schlüssel angegebenes Element.
CMap::SetAt	Fügt ein Element in die Karte ein; ersetzt ein vorhandenes Element, wenn ein übereinstimmende Schlüssel gefunden wird.

Öffentliche Operatoren

Name	Beschreibung
CMap::operator [ ]	Fügt ein Element in die Karte ein – Operatorenersetzung für SetAt.

Hinweise

Nachdem Sie ein Schlüssel-Wert-Paar (Element) in die Karte eingefügt haben, können Sie das Paar mithilfe des Schlüssels effizient abrufen oder löschen, um darauf zuzugreifen. Sie können auch alle Elemente in der Karte durchlaufen.

Eine Variable vom Typ POSITION wird für den alternativen Zugriff auf Einträge verwendet. Sie können einen Eintrag verwenden, um einen POSITION Eintrag zu "speichern" und die Karte zu durchlaufen. Möglicherweise denken Sie, dass diese Iteration nach Schlüsselwert sequenziell ist; Es ist nicht. Die Abfolge der abgerufenen Elemente ist unbestimmt.

Bestimmte Memberfunktionen dieser Klasse rufen globale Hilfsfunktionen auf, die für die meisten Verwendungen der CMap Klasse angepasst werden müssen. Siehe Sammlungsklassenhilfsprogramme im Abschnitt "Makros und Globals" der MFC-Referenz.

CMap Außerkraftsetzungen CObject::Serialize zur Unterstützung der Serialisierung und des Dumpings ihrer Elemente. Wenn eine Karte in einem Archiv gespeichert wird, Serializewird jedes Kartenelement wiederum serialisiert. Die Standardimplementierung der SerializeElements Hilfsfunktion schreibt etwas nach. Informationen zur Serialisierung von Zeigerauflistungselementen, die von CObject oder anderen benutzerdefinierten Typen abgeleitet wurden, finden Sie unter How to: Make a Type-Tresor Collection.

Wenn Sie ein Diagnoseabbild der einzelnen Elemente in der Karte (die Schlüssel und Werte) benötigen, müssen Sie die Tiefe des Speicherabbildkontexts auf 1 oder höher festlegen.

Wenn ein CMap Objekt gelöscht wird oder dessen Elemente entfernt werden, werden die Schlüssel und Werte entfernt.

Die Zuordnung von Klassenableitungen ähnelt der Listenableitung. Eine Abbildung der Ableitung einer speziellen Listenklasse finden Sie im Artikel "Sammlungen ".

Vererbungshierarchie

CObject

CMap

Anforderungen

Headerafxtempl.h:

CMap::CMap

Erstellt eine leere Karte.

CMap(INT_PTR nBlockSize = 10);

Parameter

nBlockSize
Gibt die Granularität der Speicherzuweisung für die Erweiterung der Karte an.

Hinweise

Wenn die Karte wächst, wird Speicher in Einheiten von nBlockSize Einträgen zugeordnet.

Beispiel

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

CMap::CPair

Enthält einen Schlüsselwert und den Wert des zugeordneten Objekts.

Hinweise

Dies ist eine geschachtelte Struktur innerhalb der Klasse CMap.

Die Struktur besteht aus zwei Feldern:

• key Der tatsächliche Wert des Schlüsseltyps.

• value Der Wert des zugeordneten Objekts.

Es wird verwendet, um die Rückgabewerte aus CMap::PLookup, , CMap::PGetFirstAssocund CMap::PGetNextAssoc.

Beispiel

Ein Beispiel für die Verwendung finden Sie im Beispiel für CMap::PLookup.

CMap::GetCount

Ruft die Anzahl der Elemente in der Karte ab.

INT_PTR GetCount() const;

Rückgabewert

Die Anzahl der Elemente.

Beispiel

Sehen Sie sich das Beispiel für CMap::Lookup.

CMap::GetHashTableSize

Bestimmt die Anzahl der Elemente in der Hashtabelle für die Karte.

UINT GetHashTableSize() const;

Rückgabewert

Die Anzahl der Elemente in der Hashtabelle.

Beispiel

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

UINT uTableSize = myMap.GetHashTableSize();

CMap::GetNextAssoc

Ruft das Kartenelement an rNextPositionund aktualisiert rNextPosition dann, um auf das nächste Element in der Karte zu verweisen.

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

Parameter

rNextPosition
Gibt einen Verweis auf einen POSITION Wert an, der von einem vorherigen GetNextAssoc oder GetStartPosition Aufruf zurückgegeben wird.

KEY
Vorlagenparameter, der den Typ des Schlüssels der Karte angibt.

rKey
Gibt den zurückgegebenen Schlüssel des abgerufenen Elements an.

VALUE
Vorlagenparameter, der den Typ des Kartenwerts angibt.

rValue
Gibt den zurückgegebenen Wert des abgerufenen Elements an.

Hinweise

Diese Funktion ist am nützlichsten für das Durchlaufen aller Elemente in der Karte. Beachten Sie, dass die Positionssequenz nicht unbedingt mit der Tastenwertsequenz identisch ist.

Wenn das abgerufene Element der letzte in der Karte ist, wird der neue Wert rNextPosition auf .NULL

Beispiel

Sehen Sie sich das Beispiel für CMap::SetAt.

CMap::GetSize

Gibt die Anzahl der Kartenelemente zurück.

INT_PTR GetSize() const;

Rückgabewert

Die Anzahl der Elemente in der Karte.

Hinweise

Rufen Sie diese Methode auf, um die Anzahl der Elemente in der Karte abzurufen.

Beispiel

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

Startet eine Karteniteration, indem ein POSITION Wert zurückgegeben wird, der an einen GetNextAssoc Aufruf übergeben werden kann.

POSITION GetStartPosition() const;

Rückgabewert

Ein POSITION Wert, der eine Startposition für das Durchlaufen der Karte angibt oder NULL wenn die Karte leer ist.

Hinweise

Die Iterationssequenz ist nicht vorhersehbar; Daher hat das "erste Element in der Karte" keine besondere Bedeutung.

Beispiel

Sehen Sie sich das Beispiel für CMap::SetAt.

CMap::InitHashTable

Initialisiert die Hashtabelle.

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

Parameter

hashSize
Anzahl der Einträge in der Hashtabelle.

bAllocNow
Wenn TRUE, weist die Hashtabelle bei der Initialisierung zu. Andernfalls wird die Tabelle bei Bedarf zugewiesen.

Hinweise

Um eine optimale Leistung zu erzielen, sollte die Hashtabellengröße eine Primzahl sein. Um Kollisionen zu minimieren, sollte die Größe ungefähr 20 Prozent größer sein als der größte erwartete Datensatz.

Beispiel

Sehen Sie sich das Beispiel für CMap::Lookup.

CMap::IsEmpty

Bestimmt, ob die Karte leer ist.

BOOL IsEmpty() const;

Rückgabewert

Nonzero, wenn diese Karte keine Elemente enthält; andernfalls 0.

Beispiel

Sehen Sie sich das Beispiel für CMap::RemoveAll.

CMap::Lookup

Sucht nach dem Wert, der einem bestimmten Schlüssel zugeordnet ist.

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

Parameter

ARG_KEY
Vorlagenparameter, der den Typ des key Werts angibt.

key
Gibt den Schlüssel an, der das element identifiziert, das nachschlagen soll.

VALUE
Gibt den Typ des werts an, der nachschlagen soll.

rValue
Empfängt den Nachschlagewert.

Rückgabewert

Nonzero, wenn das Element gefunden wurde; andernfalls 0.

Hinweise

Lookup verwendet einen Hashingalgorithmus, um das Kartenelement schnell mit einem Schlüssel zu finden, der exakt mit dem angegebenen Schlüssel übereinstimmt.

Beispiel

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

Ein praktischer Ersatz für die SetAt Memberfunktion.

VALUE& operator[](arg_key key);

Parameter

VALUE
Vorlagenparameter, der den Typ des Kartenwerts angibt.

ARG_KEY
Vorlagenparameter, der den Typ des Schlüsselwerts angibt.

key
Der Zum Abrufen des Werts aus der Karte verwendete Schlüssel.

Hinweise

Daher kann sie nur auf der linken Seite einer Zuordnungsanweisung (ein l-Wert) verwendet werden. Wenn kein Zuordnungselement mit dem angegebenen Schlüssel vorhanden ist, wird ein neues Element erstellt.

Es gibt keine "rechte Seite" (r-Wert), die diesem Operator entspricht, da es eine Möglichkeit gibt, dass ein Schlüssel möglicherweise nicht in der Karte gefunden wird. Verwenden Sie die Lookup Memberfunktion zum Abrufen von Elementen.

Beispiel

Sehen Sie sich das Beispiel für CMap::Lookup.

CMap::PGetFirstAssoc

Gibt den ersten Eintrag des Kartenobjekts zurück.

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

Rückgabewert

Ein Zeiger auf den ersten Eintrag in der Karte; siehe CMap::CPair. Wenn die Karte keine Einträge enthält, lautet NULLder Wert .

Hinweise

Rufen Sie diese Funktion auf, um einen Zeiger für das erste Element im Kartenobjekt zurückzugeben.

Beispiel

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

Ruft das Kartenelement ab, auf das verwiesen wird.pAssocRec

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

CPair *PGetNextAssoc(const CPair* pAssocRet);

Parameter

pAssocRet
Verweist auf einen Karteneintrag, der von einem vorherigen PGetNextAssoc oder CMap::PGetFirstAssoc aufruf zurückgegeben wird.

Rückgabewert

Ein Zeiger auf den nächsten Eintrag in der Karte; siehe CMap::CPair. Wenn das Element der letzte in der Karte ist, lautet NULLder Wert .

Hinweise

Rufen Sie diese Methode auf, um alle Elemente in der Karte zu durchlaufen. Rufen Sie das erste Element mit einem Aufruf abPGetFirstAssoc, und durchlaufen Sie dann die Karte mit aufeinander folgenden Aufrufen.PGetNextAssoc

Beispiel

Sehen Sie sich das Beispiel für CMap::PGetFirstAssoc.

CMap::PLookup

Sucht den einem bestimmten Schlüssel zugeordneten Wert.

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

Parameter

key
Schlüssel für das Element, nach dem gesucht werden soll.

Rückgabewert

Ein Zeiger auf eine Schlüsselstruktur; siehe CMap::CPair. Wenn keine Übereinstimmung gefunden wird, CMap::PLookup wird zurückgegeben NULL.

Hinweise

Rufen Sie diese Methode auf, um nach einem Kartenelement mit einem Schlüssel zu suchen, der exakt dem angegebenen Schlüssel entspricht.

Beispiel

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

Entfernt alle Werte aus dieser Karte, indem die globale Hilfsfunktion DestructElementsaufgerufen wird.

void RemoveAll();

Hinweise

Die Funktion funktioniert ordnungsgemäß, wenn die Karte bereits leer ist.

Beispiel

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

Sucht den Karteneintrag, der dem angegebenen Schlüssel entspricht; wenn der Schlüssel gefunden wird, wird der Eintrag entfernt.

BOOL RemoveKey(ARG_KEY key);

Parameter

ARG_KEY
Vorlagenparameter, der den Typ des Schlüssels angibt.

key
Schlüssel für das zu entfernende Element.

Rückgabewert

Nonzero, wenn der Eintrag gefunden und erfolgreich entfernt wurde; andernfalls 0.

Hinweise

Die DestructElements Hilfsfunktion wird verwendet, um den Eintrag zu entfernen.

Beispiel

Sehen Sie sich das Beispiel für CMap::SetAt.

CMap::SetAt

Die primäre Möglichkeit, ein Element in eine Karte einzufügen.

void SetAt(ARG_KEY key, ARG_VALUE newValue);

Parameter

ARG_KEY
Vorlagenparameter, der den Typ des key Parameters angibt.

key
Gibt den Schlüssel des neuen Elements an.

ARG_VALUE
Vorlagenparameter, der den Typ des newValue Parameters angibt.

newValue
Gibt den Wert des neuen Elements an.

Hinweise

Zuerst wird der Schlüssel nachschlagen. Wenn der Schlüssel gefunden wird, wird der entsprechende Wert geändert; andernfalls wird ein neues Schlüssel-Wert-Paar erstellt.

Beispiel

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

Siehe auch

MFC-Beispiel COLLECT
CObject Klasse
Hierarchiediagramm