La classe CMap

Classe de collection de dictionnaires qui mappe des clés uniques à des valeurs.

Syntaxe

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

Paramètres

KEY
Classe de l’objet utilisé comme clé de la carte.

ARG_KEY
Type de données utilisé pour KEY les arguments ; généralement une référence à KEY.

VALUE
Classe de l’objet stocké dans la carte.

ARG_VALUE
Type de données utilisé pour VALUE les arguments ; généralement une référence à VALUE.

Membres

Structures publiques

Nom	Description
CMap::CPair	Structure imbriquée contenant une valeur de clé et la valeur de l’objet associé.

Constructeurs publics

Nom	Description
CMap::CMap	Construit une collection qui mappe les clés aux valeurs.

Méthodes publiques

Nom	Description
CMap::GetCount	Retourne le nombre d’éléments de cette carte.
CMap::GetHashTableSize	Retourne le nombre d’éléments dans la table de hachage.
CMap::GetNextAssoc	Obtient l’élément suivant pour itérer.
CMap::GetSize	Retourne le nombre d’éléments de cette carte.
CMap::GetStartPosition	Retourne la position du premier élément.
CMap::InitHashTable	Initialise la table de hachage et spécifie sa taille.
CMap::IsEmpty	Teste la condition de mappage vide (aucun élément).
CMap::Lookup	Recherche la valeur mappée à une clé donnée.
CMap::PGetFirstAssoc	Retourne un pointeur vers le premier élément.
CMap::PGetNextAssoc	Obtient un pointeur vers l’élément suivant pour itérer.
CMap::PLookup	Retourne un pointeur vers une clé dont la valeur correspond à la valeur spécifiée.
CMap::RemoveAll	Supprime tous les éléments de cette carte.
CMap::RemoveKey	Supprime un élément spécifié par une clé.
CMap::SetAt	Insère un élément dans la carte ; remplace un élément existant si une clé correspondante est trouvée.

Opérateurs publics

Nom	Description
CMap::operator [ ]	Insère un élément dans la carte — substitution d’opérateur pour SetAt.

Notes

Une fois que vous avez inséré une paire clé-valeur (élément) dans la carte, vous pouvez récupérer ou supprimer efficacement la paire à l’aide de la clé pour y accéder. Vous pouvez également itérer sur tous les éléments de la carte.

Une variable de type POSITION est utilisée pour un autre accès aux entrées. Vous pouvez utiliser une POSITION entrée pour « mémoriser » une entrée et effectuer une itération dans la carte. Vous pouvez penser que cette itération est séquentielle par valeur de clé ; ce n’est pas le cas. La séquence d’éléments récupérés est indéterminée.

Certaines fonctions membres de cette classe appellent des fonctions d’assistance globales qui doivent être personnalisées pour la plupart des utilisations de la CMap classe. Consultez les helpers de la classe de collection dans la section Macros et Globals de la référence MFC.

CMap remplace la CObject::Serialize prise en charge de la sérialisation et du dumping de ses éléments. Si une carte est stockée dans une archive à l’aide Serialized’une archive, chaque élément de carte est sérialisé à son tour. L’implémentation par défaut de la SerializeElements fonction d’assistance effectue une écriture au niveau du bit. Pour plus d’informations sur la sérialisation des éléments de collection de pointeurs dérivés ou d’autres CObject types définis par l’utilisateur, consultez Comment : créer une collection de types Coffre.

Si vous avez besoin d’un vidage de diagnostic des éléments individuels dans la carte (clés et valeurs), vous devez définir la profondeur du contexte de vidage sur 1 ou supérieur.

Lorsqu’un CMap objet est supprimé ou lorsque ses éléments sont supprimés, les clés et les valeurs sont supprimées.

La dérivation de classe map est similaire à la dérivation de liste. Consultez l’article Collections pour obtenir une illustration de la dérivation d’une classe de liste à usage spécial.

Hiérarchie d'héritage

CObject

CMap

Spécifications

En-têteafxtempl.h:

CMap::CMap

Construit une carte vide.

CMap(INT_PTR nBlockSize = 10);

Paramètres

nBlockSize
Spécifie la granularité d’allocation de mémoire pour étendre la carte.

Notes

À mesure que la carte augmente, la mémoire est allouée en unités d’entrées nBlockSize .

Exemple

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

CMap::CPair

Contient une valeur de clé et la valeur de l’objet associé.

Notes

Il s’agit d’une structure imbriquée dans la classe CMap.

La structure se compose de deux champs :

• key Valeur réelle du type de clé.

• value Valeur de l’objet associé.

Il est utilisé pour stocker les valeurs de retour à partir de CMap::PLookup, CMap::PGetFirstAssocet CMap::PGetNextAssoc.

Exemple

Pour obtenir un exemple d’utilisation, consultez l’exemple pour CMap::PLookup.

CMap::GetCount

Récupère le nombre d’éléments dans la carte.

INT_PTR GetCount() const;

Valeur de retour

Nombre d'éléments.

Exemple

Consultez l’exemple pour CMap::Lookup.

CMap::GetHashTableSize

Détermine le nombre d’éléments dans la table de hachage de la carte.

UINT GetHashTableSize() const;

Valeur de retour

Nombre d’éléments dans la table de hachage.

Exemple

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

UINT uTableSize = myMap.GetHashTableSize();

CMap::GetNextAssoc

Récupère l’élément de carte à l’adresse rNextPosition, puis met à jour rNextPosition pour faire référence à l’élément suivant dans la carte.

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

Paramètres

rNextPosition
Spécifie une référence à une POSITION valeur retournée par un appel ou GetStartPosition un précédentGetNextAssoc.

KEY
Paramètre de modèle spécifiant le type de la clé de la carte.

rKey
Spécifie la clé retournée de l’élément récupéré.

VALUE
Paramètre de modèle spécifiant le type de la valeur de la carte.

rValue
Spécifie la valeur retournée de l’élément récupéré.

Notes

Cette fonction est particulièrement utile pour effectuer une itération sur tous les éléments de la carte. Notez que la séquence de position n’est pas nécessairement la même que la séquence de valeurs de clé.

Si l’élément récupéré est le dernier de la carte, la nouvelle valeur rNextPosition est définie NULLsur .

Exemple

Consultez l’exemple pour CMap::SetAt.

CMap::GetSize

Retourne le nombre d’éléments de carte.

INT_PTR GetSize() const;

Valeur de retour

Nombre d’éléments dans la carte.

Notes

Appelez cette méthode pour récupérer le nombre d’éléments dans la carte.

Exemple

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

Démarre une itération de carte en retournant une POSITION valeur qui peut être passée à un GetNextAssoc appel.

POSITION GetStartPosition() const;

Valeur de retour

Valeur POSITION qui indique une position de départ pour itérer la carte ; ou NULL si la carte est vide.

Notes

La séquence d’itération n’est pas prévisible ; par conséquent, le « premier élément de la carte » n’a aucune signification particulière.

Exemple

Consultez l’exemple pour CMap::SetAt.

CMap::InitHashTable

Initialise la table de hachage.

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

Paramètres

hashSize
Nombre d’entrées dans la table de hachage.

bAllocNow
Si TRUE, alloue la table de hachage lors de l’initialisation ; sinon, la table est allouée si nécessaire.

Notes

Pour des performances optimales, la taille de la table de hachage doit être un nombre premier. Pour réduire les collisions, la taille doit être d’environ 20 % supérieure au plus grand jeu de données prévu.

Exemple

Consultez l’exemple pour CMap::Lookup.

CMap::IsEmpty

Détermine si la carte est vide.

BOOL IsEmpty() const;

Valeur de retour

Différent de zéro si cette carte ne contient aucun élément ; sinon 0.

Exemple

Consultez l’exemple pour CMap::RemoveAll.

CMap::Lookup

Recherche la valeur mappée à une clé donnée.

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

Paramètres

ARG_KEY
Paramètre de modèle spécifiant le type de la key valeur.

key
Spécifie la clé qui identifie l’élément à rechercher.

VALUE
Spécifie le type de la valeur à rechercher.

rValue
Reçoit la valeur recherchée.

Valeur de retour

Différent de zéro si l’élément a été trouvé ; sinon 0.

Notes

Lookup utilise un algorithme de hachage pour rechercher rapidement l’élément de carte avec une clé qui correspond exactement à la clé donnée.

Exemple

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

Substitut pratique de la SetAt fonction membre.

VALUE& operator[](arg_key key);

Paramètres

VALUE
Paramètre de modèle spécifiant le type de la valeur de carte.

ARG_KEY
Paramètre de modèle spécifiant le type de la valeur de clé.

key
Clé utilisée pour récupérer la valeur de la carte.

Notes

Il peut donc être utilisé uniquement sur le côté gauche d’une instruction d’affectation (une valeur l). S’il n’existe aucun élément de mappage avec la clé spécifiée, un nouvel élément est créé.

Il n’existe pas de « côté droit » (r-value) équivalent à cet opérateur, car il est possible qu’une clé ne soit pas trouvée dans la carte. Utilisez la fonction membre pour la récupération d’élément Lookup .

Exemple

Consultez l’exemple pour CMap::Lookup.

CMap::PGetFirstAssoc

Retourne la première entrée de l’objet map.

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

Valeur de retour

Pointeur vers la première entrée dans la carte ; voir CMap::CPair. Si la carte ne contient aucune entrée, la valeur est NULL.

Notes

Appelez cette fonction pour renvoyer un pointeur le premier élément de l’objet map.

Exemple

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

Récupère l’élément de carte pointé par pAssocRec.

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

CPair *PGetNextAssoc(const CPair* pAssocRet);

Paramètres

pAssocRet
Pointe vers une entrée de carte retournée par un précédent PGetNextAssoc ou CMap::PGetFirstAssoc un appel.

Valeur de retour

Pointeur vers l’entrée suivante dans la carte ; voir CMap::CPair. Si l’élément est le dernier dans la carte, la valeur est NULL.

Notes

Appelez cette méthode pour itérer à travers tous les éléments de la carte. Récupérez le premier élément avec un appel à PGetFirstAssoc , puis effectuez une itération dans la carte avec des appels successifs à PGetNextAssoc.

Exemple

Consultez l’exemple pour CMap::PGetFirstAssoc.

CMap::PLookup

Recherche la valeur mappée à une clé donnée.

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

Paramètres

key
Clé pour que l’élément soit recherché.

Valeur de retour

Pointeur vers une structure de clé ; voir CMap::CPair. Si aucune correspondance n’est trouvée, CMap::PLookup retourne NULL.

Notes

Appelez cette méthode pour rechercher un élément de carte avec une clé qui correspond exactement à la clé donnée.

Exemple

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

Supprime toutes les valeurs de cette carte en appelant la fonction DestructElementsd’assistance globale .

void RemoveAll();

Notes

La fonction fonctionne correctement si la carte est déjà vide.

Exemple

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

Recherche l’entrée de carte correspondant à la clé fournie ; ensuite, si la clé est trouvée, supprime l’entrée.

BOOL RemoveKey(ARG_KEY key);

Paramètres

ARG_KEY
Paramètre de modèle spécifiant le type de la clé.

key
Clé pour que l’élément soit supprimé.

Valeur de retour

Différent de zéro si l’entrée a été trouvée et supprimée avec succès ; sinon 0.

Notes

La DestructElements fonction d’assistance est utilisée pour supprimer l’entrée.

Exemple

Consultez l’exemple pour CMap::SetAt.

CMap::SetAt

Le principal signifie d’insérer un élément dans une carte.

void SetAt(ARG_KEY key, ARG_VALUE newValue);

Paramètres

ARG_KEY
Paramètre de modèle spécifiant le type du key paramètre.

key
Spécifie la clé du nouvel élément.

ARG_VALUE
Paramètre de modèle spécifiant le type du newValue paramètre.

newValue
Spécifie la valeur du nouvel élément.

Notes

Tout d’abord, la clé est recherchée. Si la clé est trouvée, la valeur correspondante est modifiée ; sinon, une nouvelle paire clé-valeur est créée.

Exemple

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

Voir aussi

Exemple MFC COLLECT
CObject Classe
Graphique hiérarchique