La classe CList

Prend en charge les listes ordonnées d'objets non uniques accessibles séquentiellement ou par valeur.

Syntaxe

template<class TYPE, class ARG_TYPE = const TYPE&>
class CList : public CObject

Membres

Constructeurs publics

Nom Description
CList::CList Construit une liste ordonnée vide.

Méthodes publiques

Nom Description
CList::AddHead Ajoute un élément (ou tous les éléments d’une autre liste) à la tête de la liste (fait un nouveau chef).
CList::AddTail Ajoute un élément (ou tous les éléments d’une autre liste) à la fin de la liste (fait une nouvelle queue).
CList::Find Obtient la position d’un élément spécifié par la valeur du pointeur.
CList::FindIndex Obtient la position d’un élément spécifié par un index de base zéro.
CList::GetAt Obtient l’élément à une position donnée.
CList::GetCount Retourne le nombre d’éléments de cette liste.
CList::GetHead Retourne l’élément principal de la liste (ne peut pas être vide).
CList::GetHeadPosition Retourne la position de l’élément principal de la liste.
CList::GetNext Obtient l’élément suivant pour itérer.
CList::GetPrev Obtient l’élément précédent pour l’itération.
CList::GetSize Retourne le nombre d’éléments de cette liste.
CList::GetTail Retourne l’élément tail de la liste (ne peut pas être vide).
CList::GetTailPosition Retourne la position de l’élément de fin de la liste.
CList::InsertAfter Insère un nouvel élément après une position donnée.
CList::InsertBefore Insère un nouvel élément avant une position donnée.
CList::IsEmpty Teste la condition de liste vide (aucun élément).
CList::RemoveAll Supprime tous les éléments de cette liste.
CList::RemoveAt Supprime un élément de cette liste, spécifié par position.
CList::RemoveHead Supprime l’élément de la tête de la liste.
CList::RemoveTail Supprime l’élément de la fin de la liste.
CList::SetAt Définit l’élément à une position donnée.

Paramètres

TYPE
Type d’objet stocké dans la liste.

ARG_TYPE
Type utilisé pour référencer des objets stockés dans la liste. Il peut s’agir d’une référence.

Notes

CList les listes se comportent comme des listes doublement liées.

Une variable de type POSITION est une clé pour la liste. Vous pouvez utiliser une POSITION variable comme itérateur pour parcourir une liste de manière séquentielle et en tant que signet pour contenir un emplacement. Toutefois, une position n’est pas la même qu’un index.

L’insertion d’élément est très rapide à la tête de la liste, à la queue et à un connu POSITION. Une recherche séquentielle est nécessaire pour rechercher un élément par valeur ou index. Cette recherche peut être lente si la liste est longue.

Si vous avez besoin d’un vidage d’éléments individuels dans la liste, vous devez définir la profondeur du contexte de vidage sur 1 ou supérieur.

Certaines fonctions membres de cette classe appellent des fonctions d’assistance globales qui doivent être personnalisées pour la plupart des utilisations de la CList classe. Consultez les helpers de la classe de collection dans la section « Macros et globals ».

Pour plus d’informations sur l’utilisation CList, consultez l’article Collections.

Exemple

// CList is a template class that takes two template arguments.
// The first argument is type stored internally by the list, the
// second argument is the type used in the arguments for the
// CList methods.

// This code defines a list of ints.
CList<int, int> myIntList;

// This code defines a list of CStrings
CList<CString, CString &> myStringList;

// This code defines a list of MYTYPEs,
// NOTE: MYTYPE could be any struct, class or type definition
CList<MYTYPE, MYTYPE &> myTypeList;

Hiérarchie d'héritage

CObject

CList

Spécifications

En-tête : afxtempl.h

CList::AddHead

Ajoute un nouvel élément ou une liste d’éléments à la tête de cette liste.

POSITION AddHead(ARG_TYPE newElement);
void AddHead(CList* pNewList);

Paramètres

ARG_TYPE
Paramètre de modèle qui spécifie le type de l’élément de liste (peut être une référence).

newElement
Nouvel élément.

pNewList
Pointeur vers une autre CList liste. Les éléments inclus pNewList seront ajoutés à cette liste.

Valeur de retour

La première version retourne la POSITION valeur de l’élément nouvellement inséré.

Notes

La liste peut être vide avant l’opération.

Exemple

// Declarations of the variables used in the example
CList<CString, CString &> myList;
CList<CString, CString &> myList2;

// There are two versions of CList::AddHead: one adds a single
// element to the front of the list, the second adds another list
// to the front.

// This adds the string "ABC" to the front of myList.
// myList is a list of CStrings (ie defined as CList<CString,CString&>).
myList.AddHead(CString(_T("ABC")));

// This adds the elements of myList2 to the front of myList.
myList.AddHead(&myList2);

CList::AddTail

Ajoute un nouvel élément ou une liste d’éléments à la fin de cette liste.

POSITION AddTail(ARG_TYPE newElement);
void AddTail(CList* pNewList);

Paramètres

ARG_TYPE
Paramètre de modèle qui spécifie le type de l’élément de liste (peut être une référence).

newElement
Élément à ajouter à cette liste.

pNewList
Pointeur vers une autre CList liste. Les éléments inclus pNewList seront ajoutés à cette liste.

Valeur de retour

La première version retourne la POSITION valeur de l’élément nouvellement inséré.

Notes

La liste peut être vide avant l’opération.

Exemple

// Define myList and myList2.
CList<CString, CString &> myList;
CList<CString, CString &> myList2;

// Add elements to the end of myList and myList2.
myList.AddTail(CString(_T("A")));
myList.AddTail(CString(_T("B")));
myList2.AddTail(CString(_T("C")));
myList2.AddTail(CString(_T("D")));

// There are two versions of CList::AddTail: one adds a single
// element to the end of the list, the second adds another list
// to the end.

// This adds the string "ABC" to the end of myList.
// myList is a list of CStrings (ie defined as CList<CString,CString&>).
myList.AddTail(CString(_T("ABC")));
ASSERT(CString(_T("ABC")) == myList.GetTail());

// This adds the elements of myList2 to the end of myList.
myList.AddTail(&myList2);

CList::CList

Construit une liste ordonnée vide.

CList(INT_PTR nBlockSize = 10);

Paramètres

nBlockSize
Granularité d’allocation de mémoire pour étendre la liste.

Notes

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

Exemple

// This code defines myList as a list of strings
// such that memory gets allocated in chunks of
// 16 strings.
CList<CString, CString &> myList(16);

// This code defines myList2 as a list of ints
// such that memory gets allocated in chunks of
// 128 ints.
CList<int, int> myList2(128);

CList::Find

Recherche séquentiellement la liste pour rechercher le premier élément correspondant à l’élément spécifié searchValue.

POSITION Find(
    ARG_TYPE searchValue,
    POSITION startAfter = NULL) const;

Paramètres

ARG_TYPE
Paramètre de modèle qui spécifie le type de l’élément de liste (peut être une référence).

searchValue
Valeur à trouver dans la liste.

startAfter
Position de début de la recherche. Si aucune valeur n’est spécifiée, la recherche commence par l’élément principal.

Valeur de retour

Valeur POSITION qui peut être utilisée pour l’itération ou la récupération du pointeur d’objet ; NULL si l’objet est introuvable.

Exemple

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddHead(CString(_T("XYZ")));
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Find a specific element.
POSITION pos = myList.Find(CString(_T("XYZ")));
ASSERT(CString(_T("XYZ")) == myList.GetAt(pos));

CList::FindIndex

Utilise la valeur d’un nIndex index dans la liste.

POSITION FindIndex(INT_PTR nIndex) const;

Paramètres

nIndex
Index de base zéro de l’élément de liste à trouver.

Valeur de retour

Valeur POSITION qui peut être utilisée pour l’itération ou la récupération du pointeur d’objet ; NULL si nIndex elle est négative ou trop grande.

Notes

Il démarre une analyse séquentielle à partir de la tête de la liste, en s’arrêtant sur le nièmeélément.

Exemple

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Verify the first element (index 0).
ASSERT(CString(_T("XYZ")) == myList.GetAt(myList.FindIndex(0)));

// Verify the third element (index 2).
ASSERT(CString(_T("123")) == myList.GetAt(myList.FindIndex(2)));

CList::GetAt

Obtient l’élément de liste à une position donnée.

TYPE& GetAt(POSITION position);
const TYPE& GetAt(POSITION position) const;

Paramètres

TYPE
Paramètre de modèle spécifiant le type d’objet dans la liste.

position
Position dans la liste de l’élément à obtenir.

Valeur de retour

Consultez la description de la valeur de retour pour GetHead.

Notes

GetAt retourne l’élément (ou une référence à l’élément) associé à une position donnée. Ce n’est pas le même qu’un index, et vous ne pouvez pas opérer sur une POSITION valeur vous-même. Une variable de type POSITION est une clé pour la liste.

Vous devez vous assurer que votre POSITION valeur représente une position valide dans la liste. S’il n’est pas valide, la version de débogage de la bibliothèque de classes Microsoft Foundation affirme.

Exemple

Consultez l’exemple pour CList::GetHeadPosition.

CList::GetCount

Obtient le nombre d’éléments de cette liste.

INT_PTR GetCount() const;

Valeur de retour

Valeur entière contenant le nombre d’éléments.

Notes

L’appel de cette méthode génère le même résultat que la CList::GetSize méthode.

Exemple

Consultez l’exemple pour CList::RemoveHead.

CList::GetHead

Obtient l’élément head (ou une référence à l’élément head) de cette liste.

const TYPE& GetHead() const;

TYPE& GetHead();

Paramètres

TYPE
Paramètre de modèle spécifiant le type d’objet dans la liste.

Valeur de retour

Si la liste est const, GetHead retourne une copie de l’élément à la tête de la liste. Cela permet à la fonction d’être utilisée uniquement sur le côté droit d’une instruction d’affectation et protège la liste contre la modification.

Si la liste n’est pas const, GetHead retourne une référence à l’élément en tête de la liste. Cela permet à la fonction d’être utilisée sur l’un ou l’autre côté d’une instruction d’affectation et permet ainsi aux entrées de liste d’être modifiées.

Notes

Vous devez vous assurer que la liste n’est pas vide avant d’appeler GetHead. Si la liste est vide, la version de débogage de la bibliothèque de classes Microsoft Foundation affirme. Permet IsEmpty de vérifier que la liste contient des éléments.

Exemple

// Define myList.
CList<CString, CString &> myList;

// Add an element to the front of the list.
myList.AddHead(CString(_T("ABC")));

// Verify the element was added to the front of the list.
ASSERT(CString(_T("ABC")) == myList.GetHead());

CList::GetHeadPosition

Obtient la position de l’élément principal de cette liste.

POSITION GetHeadPosition() const;

Valeur de retour

Valeur POSITION qui peut être utilisée pour l’itération ou la récupération du pointeur d’objet ; NULL si la liste est vide.

Exemple

// Define myList.
CList<CString, CString &> myList;

// Add an element to the front of the list.
myList.AddHead(CString(_T("ABC")));

// Verify the element at the head position
// is the one added.
POSITION pos = myList.GetHeadPosition();
ASSERT(CString(_T("ABC")) == myList.GetAt(pos));

CList::GetNext

Obtient l’élément de liste identifié par rPosition, puis définit rPosition la POSITION valeur de l’entrée suivante dans la liste.

TYPE& GetNext(POSITION& rPosition);
const TYPE& GetNext(POSITION& rPosition) const;

Paramètres

TYPE
Paramètre de modèle spécifiant le type des éléments de la liste.

rPosition
Référence à une POSITION valeur retournée par un appel de fonction membre précédent GetNext, GetHeadPositionou autre.

Valeur de retour

Si la liste est const, GetNext retourne une copie d’un élément de la liste. Cela permet à la fonction d’être utilisée uniquement sur le côté droit d’une instruction d’affectation et protège la liste contre la modification.

Si la liste n’est pas const, GetNext retourne une référence à un élément de la liste. Cela permet à la fonction d’être utilisée sur l’un ou l’autre côté d’une instruction d’affectation et permet ainsi aux entrées de liste d’être modifiées.

Notes

Vous pouvez utiliser GetNext dans une boucle d’itération avant si vous établissez la position initiale avec un appel à GetHeadPosition ou Find.

Vous devez vous assurer que votre POSITION valeur représente une position valide dans la liste. S’il n’est pas valide, la version de débogage de la bibliothèque de classes Microsoft Foundation affirme.

Si l’élément récupéré est le dernier de la liste, la nouvelle valeur rPosition est définie sur NULL.

Exemple

// Define myList.
// Define myList.
CList<CString, CString &> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Dump the list elements to the debug window.
POSITION pos = myList.GetHeadPosition();
for (int i = 0; i < myList.GetCount(); i++)
{
   TRACE(_T("%s\r\n"), (LPCTSTR)myList.GetNext(pos));
}

CList::GetPrev

Obtient l’élément de liste identifié par rPosition, puis définit rPosition la POSITION valeur de l’entrée précédente dans la liste.

TYPE& GetPrev(POSITION& rPosition);
const TYPE& GetPrev(POSITION& rPosition) const;

Paramètres

TYPE
Paramètre de modèle spécifiant le type des éléments de la liste.

rPosition
Référence à une POSITION valeur retournée par un appel de fonction membre précédent GetPrev ou autre.

Valeur de retour

Si la liste est const, GetPrev retourne une copie de l’élément à la tête de la liste. Cela permet à la fonction d’être utilisée uniquement sur le côté droit d’une instruction d’affectation et protège la liste contre la modification.

Si la liste n’est pas const, GetPrev retourne une référence à un élément de la liste. Cela permet à la fonction d’être utilisée sur l’un ou l’autre côté d’une instruction d’affectation et permet ainsi aux entrées de liste d’être modifiées.

Notes

Vous pouvez utiliser GetPrev dans une boucle d’itération inverse si vous établissez la position initiale avec un appel à GetTailPosition ou Find.

Vous devez vous assurer que votre POSITION valeur représente une position valide dans la liste. S’il n’est pas valide, la version de débogage de la bibliothèque de classes Microsoft Foundation affirme.

Si l’élément récupéré est le premier de la liste, la nouvelle valeur rPosition est définie NULLsur .

Exemple

// Define myList.
CList<CString,CString&> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Dump the list elements to the debug window,
// in reverse order.
POSITION pos = myList.GetTailPosition();
for (int i = 0; i < myList.GetCount(); i++)
{
   TRACE(_T("%s\r\n"), (LPCTSTR)myList.GetPrev(pos));
}

CList::GetSize

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

INT_PTR GetSize() const;

Valeur de retour

Nombre d'éléments dans la liste.

Notes

Appelez cette méthode pour récupérer le nombre d’éléments de la liste. L’appel de cette méthode génère le même résultat que la CList::GetCount méthode.

Exemple

// Define myList.
CList<CString, CString &> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Remove the head element and verify the list.
// NOTE: once the head is removed, the number of
// elements in the list will be one.
CString strHead = myList.RemoveHead();
ASSERT((CString(_T("123")) == strHead) && (myList.GetSize() == 1) &&
       (CString(_T("ABC")) == myList.GetHead()));

CList::GetTail

Obtient le CObject pointeur qui représente l’élément de fin de cette liste.

TYPE& GetTail();
const TYPE& GetTail() const;

Paramètres

TYPE
Paramètre de modèle spécifiant le type d’éléments dans la liste.

Valeur de retour

Consultez la description de la valeur de retour pour GetHead.

Notes

Vous devez vous assurer que la liste n’est pas vide avant d’appeler GetTail. Si la liste est vide, la version de débogage de la bibliothèque de classes Microsoft Foundation affirme. Permet IsEmpty de vérifier que la liste contient des éléments.

Exemple

// Define myList.
CList<CString, CString &> myList;

// Add an element to the end of the list.
myList.AddTail(CString(_T("ABC")));

// Verify the element was added to the end of the list.
ASSERT(CString(_T("ABC")) == myList.GetTail());

CList::GetTailPosition

Obtient la position de l’élément tail de cette liste ; NULL si la liste est vide.

POSITION GetTailPosition() const;

Valeur de retour

Valeur POSITION qui peut être utilisée pour l’itération ou la récupération du pointeur d’objet ; NULL si la liste est vide.

Exemple

// Define myList.
CList<CString,CString&> myList;

// Add an element to the end of the list.
myList.AddTail(CString(_T("ABC")));

// Verify the element at the end position
// is the one added.
POSITION pos = myList.GetTailPosition();
ASSERT(CString(_T("ABC")) == myList.GetAt(pos));      

CList::InsertAfter

Ajoute un élément à cette liste après l’élément à la position spécifiée.

POSITION InsertAfter(POSITION position, ARG_TYPE newElement);

Paramètres

position
Valeur POSITION retournée par un appel de fonction membre ou Find GetPrevprécédentGetNext.

ARG_TYPE
Paramètre de modèle spécifiant le type de l’élément de liste.

newElement
Élément à ajouter à cette liste.

Valeur de retour

Valeur POSITION qui peut être utilisée pour l’itération ou la récupération d’éléments de liste.

Exemple

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
POSITION pos = myList.AddHead(CString(_T("XYZ")));
pos = myList.InsertAfter(pos, CString(_T("ABC")));
pos = myList.InsertAfter(pos, CString(_T("123")));

// Verify the tail element is what's expected.
ASSERT(CString(_T("123")) == myList.GetTail());

CList::InsertBefore

Ajoute un élément à cette liste avant l’élément à la position spécifiée.

POSITION InsertBefore(POSITION position, ARG_TYPE newElement);

Paramètres

position
Valeur POSITION retournée par un appel de fonction membre ou Find GetPrevprécédentGetNext.

ARG_TYPE
Paramètre de modèle qui spécifie le type de l’élément de liste (peut être une référence).

newElement
Élément à ajouter à cette liste.

Valeur de retour

Valeur POSITION qui peut être utilisée pour l’itération ou la récupération d’éléments de liste.

Notes

Si position c’est NULLle cas, l’élément est inséré à la tête de la liste.

Exemple

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
POSITION pos = myList.AddHead(CString(_T("XYZ")));
pos = myList.InsertBefore(pos, CString(_T("ABC")));
pos = myList.InsertBefore(pos, CString(_T("123")));

// Verify the head element is what's expected.
ASSERT(CString(_T("123")) == myList.GetHead());

CList::IsEmpty

Indique si cette liste ne contient aucun élément.

BOOL IsEmpty() const;

Valeur de retour

Différent de zéro si cette liste est vide ; sinon 0.

Exemple

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove the head element until the list is empty.
CString str;
while (!myList.IsEmpty())
{
   str = myList.RemoveHead();
   TRACE(_T("%s\r\n"), (LPCTSTR)str);
}

CList::RemoveAll

Supprime tous les éléments de cette liste et libère la mémoire associée.

void RemoveAll();

Notes

Aucune erreur n’est générée si la liste est déjà vide.

Exemple

// Define myList.
CList<CString, CString&> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove all of the elements in the list.
myList.RemoveAll();

// Verify the list is empty.
ASSERT(myList.IsEmpty());

CList::RemoveAt

Supprime l’élément spécifié de cette liste.

void RemoveAt(POSITION position);

Paramètres

position
Position de l’élément à supprimer de la liste.

Notes

Vous devez vous assurer que votre POSITION valeur représente une position valide dans la liste. S’il n’est pas valide, la version de débogage de la bibliothèque de classes Microsoft Foundation affirme.

Exemple

// Define myList.
CList<CString, CString&> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove CString("ABC") from the list.
myList.RemoveAt(myList.FindIndex(1));

// Verify CString("ABC") is not in the list.
ASSERT(myList.Find(CString(_T("ABC"))) == NULL);

CList::RemoveHead

Supprime l’élément de la tête de la liste et retourne un pointeur vers celui-ci.

TYPE RemoveHead();

Paramètres

TYPE
Paramètre de modèle spécifiant le type d’éléments dans la liste.

Valeur de retour

Élément précédemment à la tête de la liste.

Notes

Vous devez vous assurer que la liste n’est pas vide avant d’appeler RemoveHead. Si la liste est vide, la version de débogage de la bibliothèque de classes Microsoft Foundation affirme. Permet IsEmpty de vérifier que la liste contient des éléments.

Exemple

// Define myList.
CList<CString, CString&> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Remove the head element and verify the list.
// NOTE: once the head is removed, the number of
// elements in the list will be one.
CString strHead = myList.RemoveHead();
ASSERT((CString(_T("123")) == strHead) && (myList.GetCount() == 1) &&
(CString(_T("ABC")) == myList.GetHead()));

CList::RemoveTail

Supprime l’élément de la fin de la liste et retourne un pointeur vers celui-ci.

TYPE RemoveTail();

Paramètres

TYPE
Paramètre de modèle spécifiant le type d’éléments dans la liste.

Valeur de retour

Élément situé à la fin de la liste.

Notes

Vous devez vous assurer que la liste n’est pas vide avant d’appeler RemoveTail. Si la liste est vide, la version de débogage de la bibliothèque de classes Microsoft Foundation affirme. Permet IsEmpty de vérifier que la liste contient des éléments.

Exemple

// Define myList.
CList<CString, CString &> myList;

// Add two elements to the list.
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove the tail element and verify the list.
// NOTE: once the tail is removed, the number of
// elements in the list will be one.
CString strTail = myList.RemoveTail();
ASSERT((CString(_T("123")) == strTail) && (myList.GetCount() == 1) &&
       (CString(_T("ABC")) == myList.GetTail()));

CList::SetAt

Une variable de type POSITION est une clé pour la liste.

void SetAt(POSITION pos, ARG_TYPE newElement);

Paramètres

pos
Élément POSITION à définir.

ARG_TYPE
Paramètre de modèle qui spécifie le type de l’élément de liste (peut être une référence).

newElement
Élément à ajouter à la liste.

Notes

Ce n’est pas le même qu’un index, et vous ne pouvez pas opérer sur une POSITION valeur vous-même. SetAt écrit l’élément à la position spécifiée dans la liste.

Vous devez vous assurer que votre POSITION valeur représente une position valide dans la liste. S’il n’est pas valide, la version de débogage de la bibliothèque de classes Microsoft Foundation affirme.

Exemple

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Replace CString("ABC") with CString("CBA")
POSITION pos = myList.Find(CString(_T("ABC")));
myList.SetAt(pos, CString(_T("CBA")));

// Verify CString("ABC") is not in the list.
ASSERT(myList.Find(CString(_T("ABC"))) == NULL);

Voir aussi

Exemple MFC COLLECT
CObject Classe
Graphique hiérarchique
CMap Classe
CArray Classe