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, Serialize
wird 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-Safe 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
CMap
Anforderungen
Header: afxtempl.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::PGetFirstAssoc
und 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
Ein Beispiel hierfür finden Sie unter 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 rNextPosition
und 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
Ein Beispiel hierfür finden Sie unter 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
Ein Beispiel hierfür finden Sie unter 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
Ein Beispiel hierfür finden Sie unter 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
Ein Beispiel hierfür finden Sie unter 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
Ein Beispiel hierfür finden Sie unter 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 NULL
der 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 NULL
der 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
Ein Beispiel hierfür finden Sie unter 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 DestructElements
aufgerufen 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
Ein Beispiel hierfür finden Sie unter 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);
}