Partager via


CAtlMap, classe

Cette classe fournit des méthodes pour créer et gérer un objet map.

Syntaxe

template <typename K,
          typename V,
          class KTraits = CElementTraits<K>,
          class VTraits = CElementTraits<V>>
class CAtlMap

Paramètres

K
Type d’élément clé.

V
Type d’élément value.

KTraits
Code utilisé pour copier ou déplacer des éléments clés. Pour plus d’informations, consultez la classe CElementTraits.

VTraits
Code utilisé pour copier ou déplacer des éléments de valeur.

Membres

Typedefs publics

Nom Description
CAtlMap ::KINARGTYPE Type utilisé lorsqu’une clé est passée en tant qu’argument d’entrée
CAtlMap ::KOUTARGTYPE Type utilisé lorsqu’une clé est retournée en tant qu’argument de sortie.
CAtlMap ::VINARGTYPE Type utilisé lorsqu’une valeur est passée en tant qu’argument d’entrée.
CAtlMap ::VOUTARGTYPE Type utilisé lorsqu’une valeur est passée en tant qu’argument de sortie.

Classes publiques

Nom Description
CAtlMap ::CPair, classe Classe contenant les éléments clé et valeur.

CPair Data Members

Nom Description
CPair ::m_key Membre de données stockant l’élément clé.
CPair ::m_value Membre de données stockant l’élément valeur.

Constructeurs publics

Nom Description
CAtlMap ::CAtlMap Constructeur .
CAtlMap ::~CAtlMap Destructeur.

Méthodes publiques

Nom Description
CAtlMap ::AssertValid Appelez cette méthode pour provoquer une assertion si la CAtlMap valeur n’est pas valide.
CAtlMap ::D isableAutoRehash Appelez cette méthode pour désactiver le réachage automatique de l’objet CAtlMap .
CAtlMap ::EnableAutoRehash Appelez cette méthode pour activer le réachage automatique de l’objet CAtlMap .
CAtlMap ::GetAt Appelez cette méthode pour renvoyer l’élément à une position spécifiée dans la carte.
CAtlMap ::GetCount Appelez cette méthode pour récupérer le nombre d’éléments dans la carte.
CAtlMap ::GetHashTableSize Appelez cette méthode pour déterminer le nombre de compartiments dans la table de hachage de la carte.
CAtlMap ::GetKeyAt Appelez cette méthode pour récupérer la clé stockée à la position donnée dans l’objet CAtlMap .
CAtlMap ::GetNext Appelez cette méthode pour obtenir un pointeur vers la paire d’éléments suivante stockée dans l’objet CAtlMap .
CAtlMap ::GetNextAssoc Obtient l’élément suivant pour itérer.
CAtlMap ::GetNextKey Appelez cette méthode pour récupérer la clé suivante de l’objet CAtlMap .
CAtlMap ::GetNextValue Appelez cette méthode pour obtenir la valeur suivante de l’objet CAtlMap .
CAtlMap ::GetStartPosition Appelez cette méthode pour démarrer une itération de carte.
CAtlMap ::GetValueAt Appelez cette méthode pour récupérer la valeur stockée à une position donnée dans l’objet CAtlMap .
CAtlMap ::InitHashTable Appelez cette méthode pour initialiser la table de hachage.
CAtlMap ::IsEmpty Appelez cette méthode pour tester un objet map vide.
CAtlMap ::Lookup Appelez cette méthode pour rechercher des clés ou des valeurs dans l’objet CAtlMap .
CAtlMap ::Rehash Appelez cette méthode pour réinscrire l’objet CAtlMap .
CAtlMap ::RemoveAll Appelez cette méthode pour supprimer tous les éléments de l’objet CAtlMap .
CAtlMap ::RemoveAtPos Appelez cette méthode pour supprimer l’élément à la position donnée dans l’objet CAtlMap .
CAtlMap ::RemoveKey Appelez cette méthode pour supprimer un élément de l’objet CAtlMap , en fonction de la clé.
CAtlMap ::SetAt Appelez cette méthode pour insérer une paire d’éléments dans la carte.
CAtlMap ::SetOptimalLoad Appelez cette méthode pour définir la charge optimale de l’objet CAtlMap .
CAtlMap ::SetValueAt Appelez cette méthode pour modifier la valeur stockée à une position donnée dans l’objet CAtlMap .

Opérateurs publics

Nom Description
CAtlMap ::operator[] Remplace ou ajoute un nouvel élément au CAtlMap.

Notes

CAtlMap fournit la prise en charge d’un tableau de mappage d’un type donné, la gestion d’un tableau non ordonné d’éléments clés et leurs valeurs associées. Les éléments (constitués d’une clé et d’une valeur) sont stockés à l’aide d’un algorithme de hachage, ce qui permet de stocker et de récupérer efficacement une grande quantité de données.

Les paramètres KTraits et VTraits sont des classes de caractéristiques qui contiennent tout code supplémentaire nécessaire pour copier ou déplacer des éléments.

Une alternative est CAtlMap proposée par la classe CRBMap . CRBMap stocke également les paires clé/valeur, mais présente différentes caractéristiques de performances. Le temps nécessaire pour insérer un élément, rechercher une clé ou supprimer une clé d’un CRBMap objet est de ordre log(n), où n est le nombre d’éléments. Pour CAtlMap, toutes ces opérations prennent généralement un temps constant, bien que les pires scénarios peuvent être de l’ordre n. Par conséquent, dans un cas classique, CAtlMap est plus rapide.

L’autre différence entre CRBMap et CAtlMap devient apparente lors de l’itération dans les éléments stockés. Dans un CRBMap, les éléments sont visités dans un ordre trié. Dans un CAtlMap, les éléments ne sont pas classés et aucun ordre ne peut être déduit.

Quand un petit nombre d’éléments doivent être stockés, envisagez plutôt d’utiliser la classe CSimpleMap .

Pour plus d’informations, consultez les classes de collection ATL.

Spécifications

En-tête : atlcoll.h

CAtlMap ::AssertValid

Appelez cette méthode pour provoquer une assertion si l’objet CAtlMap n’est pas valide.

void AssertValid() const;

Notes

Dans les builds de débogage, cette méthode entraîne une ASSERTION si l’objet CAtlMap n’est pas valide.

Exemple

Consultez l’exemple de CAtlMap ::CAtlMap.

CAtlMap ::CAtlMap

Constructeur .

CAtlMap(
    UINT nBins = 17,
    float fOptimalLoad = 0.75f,
    float fLoThreshold = 0.25f,
    float fHiThreshold = 2.25f,
    UINT nBlockSize = 10) throw ();

Paramètres

nBins
Nombre de compartiments fournissant des pointeurs vers les éléments stockés. Consultez les remarques plus loin dans cette rubrique pour obtenir une explication des compartiments.

fOptimalLoad
Rapport de charge optimal.

fLoThreshold
Seuil inférieur pour le ratio de charge.

fHiThreshold
Seuil supérieur pour le ratio de charge.

nBlockSize
Taille du bloc.

Notes

CAtlMap fait référence à tous ses éléments stockés en créant d’abord un index à l’aide d’un algorithme de hachage sur la clé. Cet index fait référence à un « bin » qui contient un pointeur vers les éléments stockés. Si la corbeille est déjà en cours d’utilisation, une liste liée est créée pour accéder aux éléments suivants. La traversée d’une liste est plus lente que l’accès direct à l’élément correct, et la structure de la carte doit donc équilibrer les exigences de stockage par rapport aux performances. Les paramètres par défaut ont été choisis pour donner de bons résultats dans la plupart des cas.

Le rapport de charge est le rapport entre le nombre de compartiments et le nombre d’éléments stockés dans l’objet map. Lorsque la structure de la carte est recalculée, la valeur du paramètre fOptimalLoad est utilisée pour calculer le nombre de compartiments requis. Cette valeur peut être modifiée à l’aide de la méthode CAtlMap ::SetOptimalLoad .

Le paramètre fLoThreshold est la valeur inférieure que le ratio de charge peut atteindre avant CAtlMap de recalculer la taille optimale de la carte.

Le paramètre fHiThreshold est la valeur supérieure que le ratio de charge peut atteindre avant que l’objet CAtlMap recalcule la taille optimale de la carte.

Ce processus de recalcul (appelé rehashing) est activé par défaut. Si vous souhaitez désactiver ce processus, peut-être lorsque vous entrez un grand nombre de données à la fois, appelez la méthode CAtlMap ::D isableAutoRehash . Réactivez-la avec la méthode CAtlMap ::EnableAutoRehash .

Le paramètre nBlockSize est une mesure de la quantité de mémoire allouée lorsqu’un nouvel élément est requis. Les tailles de bloc supérieures réduisent les appels aux routines d’allocation de mémoire, mais utilisent davantage de ressources.

Avant de stocker des données, il est nécessaire d’initialiser la table de hachage avec un appel à CAtlMap ::InitHashTable.

Exemple

// Create a map which stores a double
// value using an integer key

CAtlMap<int, double> mySinTable;
int i;

// Initialize the Hash Table
mySinTable.InitHashTable(257);

// Add items to the map
for (i = 0; i < 90; i++)
   mySinTable[i] = sin((double)i);

// Confirm the map is valid
mySinTable.AssertValid();

// Confirm the number of elements in the map
ATLASSERT(mySinTable.GetCount() == 90);

// Remove elements with even key values
for (i = 0; i < 90; i += 2)
   mySinTable.RemoveKey(i);

// Confirm the number of elements in the map
ATLASSERT(mySinTable.GetCount() == 45);

// Walk through all the elements in the map.
// First, get start position.
POSITION pos;
int key;
double value;
pos = mySinTable.GetStartPosition();

// Now iterate the map, element by element
while (pos != NULL) 
{
   key = mySinTable.GetKeyAt(pos);
   value = mySinTable.GetNextValue(pos);
}

CAtlMap ::~CAtlMap

Destructeur.

~CAtlMap() throw();

Notes

Libère toutes les ressources allouées.

CAtlMap ::CPair, classe

Classe contenant les éléments clé et valeur.

class CPair : public __POSITION

Notes

Cette classe est utilisée par les méthodes CAtlMap ::GetNext et CAtlMap ::Lookup pour accéder aux éléments de clé et de valeur stockés dans la structure de mappage.

CAtlMap ::D isableAutoRehash

Appelez cette méthode pour désactiver le réachage automatique de l’objet CAtlMap .

void DisableAutoRehash() throw();

Notes

Lorsque le réachage automatique est activé (qu’il s’agit par défaut), le nombre de compartiments dans la table de hachage est automatiquement recalculé si la valeur de chargement (le ratio du nombre de compartiments au nombre d’éléments stockés dans le tableau) dépasse les valeurs maximales ou minimales spécifiées au moment de la création de la carte.

DisableAutoRehash est plus utile lorsqu’un grand nombre d’éléments sera ajouté à la carte à la fois. Au lieu de déclencher le processus de rehashing chaque fois que les limites sont dépassées, il est plus efficace d’appeler DisableAutoRehash, d’ajouter les éléments et enfin d’appeler CAtlMap ::EnableAutoRehash.

CAtlMap ::EnableAutoRehash

Appelez cette méthode pour activer le réachage automatique de l’objet CAtlMap .

void EnableAutoRehash() throw();

Notes

Lorsque le réachage automatique est activé (qu’il s’agit par défaut), le nombre de compartiments dans la table de hachage est automatiquement recalculé si la valeur de charge (le rapport du nombre de compartiments au nombre d’éléments stockés dans le tableau) dépasse les valeurs maximales ou minimales spécifiées au moment de la création de la carte.

EnableAutoRefresh est le plus souvent utilisé après un appel à CAtlMap ::D isableAutoRehash.

CAtlMap ::GetAt

Appelez cette méthode pour renvoyer l’élément à une position spécifiée dans la carte.

void GetAt(
    POSITION pos,
    KOUTARGTYPE key,
    VOUTARGTYPE value) const;

CPair* GetAt(POSITION& pos) throw();

Paramètres

pos
Compteur de position, retourné par un appel précédent à CAtlMap ::GetNextAssoc ou CAtlMap ::GetStartPosition.

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

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

Valeur de retour

Retourne un pointeur vers la paire actuelle d’éléments clé/valeur stockés dans la carte.

Notes

Dans les builds de débogage, une erreur d’assertion se produit si pos est égal à NULL.

CAtlMap ::GetCount

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

size_t GetCount() const throw();

Valeur de retour

Retourne le nombre d’éléments dans l’objet map. Un seul élément est une paire clé/valeur.

Exemple

Consultez l’exemple de CAtlMap ::CAtlMap.

CAtlMap ::GetHashTableSize

Appelez cette méthode pour déterminer le nombre de compartiments dans la table de hachage de la carte.

UINT GetHashTableSize() const throw();

Valeur de retour

Retourne le nombre de compartiments dans la table de hachage. Consultez CAtlMap ::CAtlMap pour obtenir une explication.

CAtlMap ::GetKeyAt

Appelez cette méthode pour récupérer la clé stockée à la position donnée dans l’objet CAtlMap .

const K& GetKeyAt(POSITION pos) const throw();

Paramètres

pos
Compteur de position, retourné par un appel précédent à CAtlMap ::GetNextAssoc ou CAtlMap ::GetStartPosition.

Valeur de retour

Retourne une référence à la clé stockée à la position donnée dans l’objet CAtlMap .

Exemple

Consultez l’exemple de CAtlMap ::CAtlMap.

CAtlMap ::GetNext

Appelez cette méthode pour obtenir un pointeur vers la paire d’éléments suivante stockée dans l’objet CAtlMap .

CPair* GetNext(POSITION& pos) throw();
const CPair* GetNext(POSITION& pos) const throw();

Paramètres

pos
Compteur de position, retourné par un appel précédent à CAtlMap ::GetNextAssoc ou CAtlMap ::GetStartPosition.

Valeur de retour

Retourne un pointeur vers la paire suivante d’éléments clé/valeur stockés dans la carte. Le compteur de position de pos est mis à jour après chaque appel. Si l’élément récupéré est le dernier de la carte, pos a la valeur NULL.

CAtlMap ::GetNextAssoc

Obtient l’élément suivant pour itérer.

void GetNextAssoc(
    POSITION& pos,
    KOUTARGTYPE key,
    VOUTARGTYPE value) const;

Paramètres

pos
Compteur de position, retourné par un appel précédent à CAtlMap ::GetNextAssoc ou CAtlMap ::GetStartPosition.

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

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

Notes

Le compteur de position de pos est mis à jour après chaque appel. Si l’élément récupéré est le dernier de la carte, pos a la valeur NULL.

CAtlMap ::GetNextKey

Appelez cette méthode pour récupérer la clé suivante de l’objet CAtlMap .

const K& GetNextKey(POSITION& pos) const throw();

Paramètres

pos
Compteur de position, retourné par un appel précédent à CAtlMap ::GetNextAssoc ou CAtlMap ::GetStartPosition.

Valeur de retour

Retourne une référence à la clé suivante dans la carte.

Notes

Met à jour le compteur de position actuel, pos. S’il n’y a plus d’entrées dans la carte, le compteur de position est défini sur NULL.

CAtlMap ::GetNextValue

Appelez cette méthode pour obtenir la valeur suivante de l’objet CAtlMap .

V& GetNextValue(POSITION& pos) throw();
const V& GetNextValue(POSITION& pos) const throw();

Paramètres

pos
Compteur de position, retourné par un appel précédent à CAtlMap ::GetNextAssoc ou CAtlMap ::GetStartPosition.

Valeur de retour

Retourne une référence à la valeur suivante dans la carte.

Notes

Met à jour le compteur de position actuel, pos. S’il n’y a plus d’entrées dans la carte, le compteur de position est défini sur NULL.

Exemple

Consultez l’exemple de CAtlMap ::CAtlMap.

CAtlMap ::GetStartPosition

Appelez cette méthode pour démarrer une itération de carte.

POSITION GetStartPosition() const throw();

Valeur de retour

Retourne la position de début ou NULL est retournée si la carte est vide.

Notes

Appelez cette méthode pour démarrer une itération de carte en retournant une valeur POSITION qui peut être passée à la GetNextAssoc méthode.

Remarque

La séquence d’itération n’est pas prévisible

Exemple

Consultez l’exemple de CAtlMap ::CAtlMap.

CAtlMap ::GetValueAt

Appelez cette méthode pour récupérer la valeur stockée à une position donnée dans l’objet CAtlMap .

V& GetValueAt(POSITION pos) throw();
const V& GetValueAt(POSITION pos) const throw();

Paramètres

pos
Compteur de position, retourné par un appel précédent à CAtlMap ::GetNextAssoc ou CAtlMap ::GetStartPosition.

Valeur de retour

Retourne une référence à la valeur stockée à la position donnée dans l’objet CAtlMap .

CAtlMap ::InitHashTable

Appelez cette méthode pour initialiser la table de hachage.

bool InitHashTable(
    UINT nBins,
    bool bAllocNow = true);

Paramètres

nBins
Nombre de compartiments utilisés par la table de hachage. Consultez CAtlMap ::CAtlMap pour obtenir une explication.

bAllocNow
Indication d’indicateur quand la mémoire doit être allouée.

Valeur de retour

Retourne TRUE lors de l’initialisation réussie, FALSE en cas d’échec.

Notes

InitHashTable doit être appelé avant que tous les éléments soient stockés dans la table de hachage. Si cette méthode n’est pas appelée explicitement, elle est appelée automatiquement la première fois qu’un élément est ajouté à l’aide du nombre de compartiments spécifié par le CAtlMap constructeur. Sinon, la carte est initialisée à l’aide du nouveau nombre de compartiments spécifié par le paramètre nBins .

Si le paramètre bAllocNow a la valeur false, la mémoire requise par la table de hachage n’est pas allouée tant qu’elle n’est pas requise pour la première fois. Cela peut être utile s’il est incertain si la carte sera utilisée.

Exemple

Consultez l’exemple de CAtlMap ::CAtlMap.

CAtlMap ::IsEmpty

Appelez cette méthode pour tester un objet map vide.

bool IsEmpty() const throw();

Valeur de retour

Retourne TRUE si la carte est vide, FALSE sinon.

CAtlMap ::KINARGTYPE

Type utilisé lorsqu’une clé est passée en tant qu’argument d’entrée.

typedef KTraits::INARGTYPE KINARGTYPE;

CAtlMap ::KOUTARGTYPE

Type utilisé lorsqu’une clé est retournée en tant qu’argument de sortie.

typedef KTraits::OUTARGTYPE KOUTARGTYPE;

CAtlMap ::Lookup

Appelez cette méthode pour rechercher des clés ou des valeurs dans l’objet CAtlMap .

bool Lookup(KINARGTYPE key, VOUTARGTYPE value) const;
const CPair* Lookup(KINARGTYPE key) const throw();
CPair* Lookup(KINARGTYPE key) throw();

Paramètres

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

value
Variable qui reçoit la valeur recherchée.

Valeur de retour

La première forme de la méthode retourne true si la clé est trouvée, sinon false. Les deuxième et troisième formulaires retournent un pointeur vers un CPair qui peut être utilisé comme position pour les appels à CAtlMap ::GetNext, et ainsi de suite .

Notes

Lookup utilise un algorithme de hachage pour rechercher rapidement l’élément de carte contenant une clé qui correspond exactement au paramètre de clé donné.

CAtlMap ::operator []

Remplace ou ajoute un nouvel élément au CAtlMap.

V& operator[](kinargtype key) throw();

Paramètres

key
Clé de l’élément à ajouter ou remplacer.

Valeur de retour

Retourne une référence à la valeur associée à la clé donnée.

Exemple

Si la clé existe déjà, l’élément est remplacé. Si la clé n’existe pas, un nouvel élément est ajouté. Consultez l’exemple de CAtlMap ::CAtlMap.

CAtlMap ::Rehash

Appelez cette méthode pour réinscrire l’objet CAtlMap .

void Rehash(UINT nBins = 0);

Paramètres

nBins
Nouveau nombre de compartiments à utiliser dans la table de hachage. Consultez CAtlMap ::CAtlMap pour obtenir une explication.

Notes

Si nBins est 0, CAtlMap calcule un nombre raisonnable en fonction du nombre d’éléments de la carte et du paramètre de charge optimal. Normalement, le processus de rehashing est automatique, mais si CAtlMap ::D isableAutoRehash a été appelé, cette méthode effectue le redimensionnement nécessaire.

CAtlMap ::RemoveAll

Appelez cette méthode pour supprimer tous les éléments de l’objet CAtlMap .

void RemoveAll() throw();

Notes

Efface l’objet CAtlMap , libérant la mémoire utilisée pour stocker les éléments.

CAtlMap ::RemoveAtPos

Appelez cette méthode pour supprimer l’élément à la position donnée dans l’objet CAtlMap .

void RemoveAtPos(POSITION pos) throw();

Paramètres

pos
Compteur de position, retourné par un appel précédent à CAtlMap ::GetNextAssoc ou CAtlMap ::GetStartPosition.

Notes

Supprime la paire clé/valeur stockée à la position spécifiée. La mémoire utilisée pour stocker l’élément est libérée. La position référencée par pos devient non valide et, bien que la position d’autres éléments de la carte reste valide, elles ne conservent pas nécessairement le même ordre.

CAtlMap ::RemoveKey

Appelez cette méthode pour supprimer un élément de l’objet CAtlMap , en fonction de la clé.

bool RemoveKey(KINARGTYPE key) throw();

Paramètres

key
Clé correspondant à la paire d’éléments que vous souhaitez supprimer.

Valeur de retour

Retourne TRUE si la clé est trouvée et supprimée, FALSE en cas d’échec.

Exemple

Consultez l’exemple de CAtlMap ::CAtlMap.

CAtlMap ::SetAt

Appelez cette méthode pour insérer une paire d’éléments dans la carte.

POSITION SetAt(
    KINARGTYPE key,
    VINARGTYPE value);

Paramètres

key
Valeur de clé à ajouter à l’objet CAtlMap .

value
Valeur à ajouter à l’objet CAtlMap .

Valeur de retour

Retourne la position de la paire d’éléments clé/valeur dans l’objet CAtlMap .

Notes

SetAt remplace un élément existant si une clé correspondante est trouvée. Si la clé est introuvable, une nouvelle paire clé/valeur est créée.

CAtlMap ::SetOptimalLoad

Appelez cette méthode pour définir la charge optimale de l’objet CAtlMap .

void SetOptimalLoad(
    float fOptimalLoad,
    float fLoThreshold,
    float fHiThreshold,
    bool bRehashNow = false);

Paramètres

fOptimalLoad
Rapport de charge optimal.

fLoThreshold
Seuil inférieur pour le ratio de charge.

fHiThreshold
Seuil supérieur pour le ratio de charge.

bRehashNow
Indicateur indiquant si la table de hachage doit être recalculée.

Notes

Cette méthode redéfinit la valeur de charge optimale pour l’objet CAtlMap . Consultez CAtlMap ::CAtlMap pour une discussion sur les différents paramètres. Si bRehashNow a la valeur true et que le nombre d’éléments se trouve en dehors des valeurs minimales et maximales, la table de hachage est recalculée.

CAtlMap ::SetValueAt

Appelez cette méthode pour modifier la valeur stockée à une position donnée dans l’objet CAtlMap .

void SetValueAt(
    POSITION pos,
    VINARGTYPE value);

Paramètres

pos
Compteur de position, retourné par un appel précédent à CAtlMap ::GetNextAssoc ou CAtlMap ::GetStartPosition.

value
Valeur à ajouter à l’objet CAtlMap .

Notes

Modifie l’élément valeur stocké à la position donnée dans l’objet CAtlMap .

CAtlMap ::VINARGTYPE

Type utilisé lorsqu’une valeur est passée en tant qu’argument d’entrée.

typedef VTraits::INARGTYPE VINARGTYPE;

CAtlMap ::VOUTARGTYPE

Type utilisé lorsqu’une valeur est passée en tant qu’argument de sortie.

typedef VTraits::OUTARGTYPE VOUTARGTYPE;

CAtlMap ::CPair ::m_key

Membre de données stockant l’élément clé.

const K m_key;

Paramètres

K
Type d’élément clé.

CAtlMap ::CPair ::m_value

Membre de données stockant l’élément valeur.

V  m_value;

Paramètres

V
Type d’élément value.

Voir aussi

Exemple de marque
Exemple UpdatePV
Vue d’ensemble de la classe