CList Klasa

Obsługuje uporządkowane listy obiektów nieudostępnianych sekwencyjnie lub według wartości.

Składnia

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

Elementy członkowskie

Konstruktory publiczne

Metody publiczne

Parametry

TYPE
Typ obiektu przechowywanego na liście.

ARG_TYPE
Typ używany do odwołowania się do obiektów przechowywanych na liście. Może to być odwołanie.

Uwagi

CList listy zachowują się jak listy połączone podwójnie.

Zmienna typu POSITION jest kluczem listy. Możesz użyć zmiennej POSITION jako iteratora do przechodzenia listy sekwencyjnie i jako zakładki do przechowywania miejsca. Pozycja nie jest jednak taka sama jak indeks.

Wstawianie elementów jest bardzo szybkie na czele listy, na ogonie i przy znanym POSITION. Wyszukiwanie sekwencyjne jest niezbędne do wyszukania elementu według wartości lub indeksu. To wyszukiwanie może być powolne, jeśli lista jest długa.

Jeśli potrzebujesz zrzutu poszczególnych elementów na liście, musisz ustawić głębokość kontekstu zrzutu na 1 lub większą.

Niektóre funkcje składowe tej klasy wywołają globalne funkcje pomocnika, które muszą być dostosowane do większości zastosowań CList klasy. Zobacz Pomocnicy klas kolekcji w sekcji "Makra i globalne".

Aby uzyskać więcej informacji na temat korzystania z programu CList, zobacz artykuł Kolekcje.

Przykład

// 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;

Hierarchia dziedziczenia

CObject

CList

Wymagania

Nagłówek: afxtempl.h

CList::AddHead

Dodaje nowy element lub listę elementów do nagłówka tej listy.

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

Parametry

ARG_TYPE
Parametr szablonu określający typ elementu listy (może być odwołaniem).

newElement
Nowy element.

pNewList
Wskaźnik do innej CList listy. Elementy w pliku pNewList zostaną dodane do tej listy.

Wartość zwracana

Pierwsza wersja zwraca POSITION wartość nowo wstawionego elementu.

Uwagi

Lista może być pusta przed operacją.

Przykład

// 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

Dodaje nowy element lub listę elementów do końca tej listy.

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

Parametry

ARG_TYPE
Parametr szablonu określający typ elementu listy (może być odwołaniem).

newElement
Element, który ma zostać dodany do tej listy.

pNewList
Wskaźnik do innej CList listy. Elementy w pliku pNewList zostaną dodane do tej listy.

Wartość zwracana

Pierwsza wersja zwraca POSITION wartość nowo wstawionego elementu.

Uwagi

Lista może być pusta przed operacją.

Przykład

// 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

Tworzy pustą uporządkowaną listę.

CList(INT_PTR nBlockSize = 10);

Parametry

nBlockSize
Stopień szczegółowości alokacji pamięci na potrzeby rozszerzania listy.

Uwagi

Wraz ze wzrostem listy pamięć jest przydzielana w jednostkach nBlockSize wpisów.

Przykład

// 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

Wyszukuje listę sekwencyjnie, aby znaleźć pierwszy element pasujący do określonego searchValueelementu .

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

Parametry

ARG_TYPE
Parametr szablonu określający typ elementu listy (może być odwołaniem).

searchValue
Wartość, która ma zostać znaleziona na liście.

startAfter
Pozycja początkowa wyszukiwania. Jeśli żadna wartość nie jest określona, wyszukiwanie rozpoczyna się od elementu head.

Wartość zwracana

POSITION Wartość, która może służyć do iteracji lub pobierania wskaźnika obiektu; NULL jeśli obiekt nie zostanie znaleziony.

Przykład

// 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

Używa wartości nIndex jako indeksu do listy.

POSITION FindIndex(INT_PTR nIndex) const;

Parametry

nIndex
Indeks na podstawie zera elementu listy, który ma zostać znaleziony.

Wartość zwracana

POSITION Wartość, która może służyć do iteracji lub pobierania wskaźnika obiektu; NULL jeśli nIndex jest ujemna lub zbyt duża.

Uwagi

Spowoduje to uruchomienie sekwencyjnego skanowania z nagłówka listy, zatrzymując się na nelement.

Przykład

// 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

Pobiera element listy na danej pozycji.

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

Parametry

TYPE
Parametr szablonu określający typ obiektu na liście.

position
Pozycja na liście elementu do pobrania.

Wartość zwracana

Zobacz opis wartości zwracanej dla elementu GetHead.

Uwagi

GetAt Zwraca element (lub odwołanie do elementu) skojarzonego z daną pozycją. Nie jest on taki sam jak indeks i nie można samodzielnie działać na POSITION wartości. Zmienna typu POSITION jest kluczem listy.

Musisz upewnić się, że wartość POSITION reprezentuje prawidłową pozycję na liście. Jeśli jest on nieprawidłowy, oznacza to, że wersja debugowania biblioteki klas programu Microsoft Foundation jest asercyjna.

Przykład

Zobacz przykład dla elementu CList::GetHeadPosition.

CList::GetCount

Pobiera liczbę elementów na tej liście.

INT_PTR GetCount() const;

Wartość zwracana

Wartość całkowita zawierająca liczbę elementów.

Uwagi

Wywołanie tej metody spowoduje wygenerowanie tego samego wyniku co CList::GetSize metoda.

Przykład

Zobacz przykład dla elementu CList::RemoveHead.

CList::GetHead

Pobiera element head (lub odwołanie do elementu head) tej listy.

const TYPE& GetHead() const;

TYPE& GetHead();

Parametry

TYPE
Parametr szablonu określający typ obiektu na liście.

Wartość zwracana

Jeśli lista to const, GetHead zwraca kopię elementu na czele listy. Dzięki temu funkcja może być używana tylko po prawej stronie instrukcji przypisania i chroni listę przed modyfikacją.

Jeśli lista nie constma wartości , GetHead zwraca odwołanie do elementu na czele listy. Dzięki temu funkcja może być używana po obu stronach instrukcji przypisania, a tym samym umożliwia modyfikowanie wpisów listy.

Uwagi

Przed wywołaniem metody GetHeadupewnij się, że lista nie jest pusta. Jeśli lista jest pusta, zostanie asercyjna wersja debugowania biblioteki klas programu Microsoft Foundation. Użyj polecenia IsEmpty , aby sprawdzić, czy lista zawiera elementy.

Przykład

// 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

Pobiera pozycję elementu głównego tej listy.

POSITION GetHeadPosition() const;

Wartość zwracana

POSITION Wartość, która może służyć do iteracji lub pobierania wskaźnika obiektu; NULL jeśli lista jest pusta.

Przykład

// 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

Pobiera element listy zidentyfikowany przez rPositionelement , a następnie ustawia rPosition wartość POSITION następnego wpisu na liście.

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

Parametry

TYPE
Parametr szablonu określający typ elementów na liście.

rPosition
Odwołanie do POSITION wartości zwróconej przez poprzednie GetNextwywołanie funkcji , GetHeadPositionlub innego elementu członkowskiego.

Wartość zwracana

Jeśli lista to const, GetNext zwraca kopię elementu listy. Dzięki temu funkcja może być używana tylko po prawej stronie instrukcji przypisania i chroni listę przed modyfikacją.

Jeśli lista nie constma wartości , GetNext zwraca odwołanie do elementu listy. Dzięki temu funkcja może być używana po obu stronach instrukcji przypisania, a tym samym umożliwia modyfikowanie wpisów listy.

Uwagi

Można użyć GetNext w pętli iteracji przesyłania dalej, jeśli ustanowisz pozycję początkową z wywołaniem lub GetHeadPosition Find.

Musisz upewnić się, że wartość POSITION reprezentuje prawidłową pozycję na liście. Jeśli jest on nieprawidłowy, oznacza to, że wersja debugowania biblioteki klas programu Microsoft Foundation jest asercyjna.

Jeśli pobrany element jest ostatnim elementem na liście, nowa wartość parametru jest ustawiona rPosition na wartość NULL.

Przykład

// 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

Pobiera element listy zidentyfikowany przez rPositionelement , a następnie ustawia rPosition wartość POSITION poprzedniego wpisu na liście.

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

Parametry

TYPE
Parametr szablonu określający typ elementów na liście.

rPosition
Odwołanie do POSITION wartości zwracanej przez poprzednie GetPrev lub inne wywołanie funkcji składowej.

Wartość zwracana

Jeśli lista to const, GetPrev zwraca kopię elementu na czele listy. Dzięki temu funkcja może być używana tylko po prawej stronie instrukcji przypisania i chroni listę przed modyfikacją.

Jeśli lista nie constma wartości , GetPrev zwraca odwołanie do elementu listy. Dzięki temu funkcja może być używana po obu stronach instrukcji przypisania, a tym samym umożliwia modyfikowanie wpisów listy.

Uwagi

Można użyć GetPrev w pętli iteracji odwrotnej, jeśli ustanowisz pozycję początkową za pomocą wywołania metody GetTailPosition lub Find.

Musisz upewnić się, że wartość POSITION reprezentuje prawidłową pozycję na liście. Jeśli jest on nieprawidłowy, oznacza to, że wersja debugowania biblioteki klas programu Microsoft Foundation jest asercyjna.

Jeśli pobrany element jest pierwszym elementem na liście, nowa wartość parametru jest ustawiona rPosition na NULLwartość .

Przykład

// 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

Zwraca liczbę elementów listy.

INT_PTR GetSize() const;

Wartość zwracana

Liczba elementów na liście.

Uwagi

Wywołaj tę metodę, aby pobrać liczbę elementów na liście. Wywołanie tej metody spowoduje wygenerowanie tego samego wyniku co CList::GetCount metoda.

Przykład

// 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

CObject Pobiera wskaźnik reprezentujący element końcowy tej listy.

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

Parametry

TYPE
Parametr szablonu określający typ elementów na liście.

Wartość zwracana

Zobacz opis wartości zwracanej dla elementu GetHead.

Uwagi

Przed wywołaniem metody GetTailupewnij się, że lista nie jest pusta. Jeśli lista jest pusta, zostanie asercyjna wersja debugowania biblioteki klas programu Microsoft Foundation. Użyj polecenia IsEmpty , aby sprawdzić, czy lista zawiera elementy.

Przykład

// 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

Pobiera położenie elementu końcowego tej listy; NULL jeśli lista jest pusta.

POSITION GetTailPosition() const;

Wartość zwracana

POSITION Wartość, która może służyć do iteracji lub pobierania wskaźnika obiektu; NULL jeśli lista jest pusta.

Przykład

// 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

Dodaje element do tej listy po elemecie w określonej pozycji.

POSITION InsertAfter(POSITION position, ARG_TYPE newElement);

Parametry

position
Wartość POSITION zwrócona przez poprzednie GetNextwywołanie funkcji , GetPrevlub Find składowej.

ARG_TYPE
Parametr szablonu określający typ elementu listy.

newElement
Element, który ma zostać dodany do tej listy.

Wartość zwracana

POSITION Wartość, która może służyć do iteracji lub pobierania elementu listy.

Przykład

// 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

Dodaje element do tej listy przed elementem na określonej pozycji.

POSITION InsertBefore(POSITION position, ARG_TYPE newElement);

Parametry

position
POSITION Wartość zwrócona przez poprzednie GetNextwywołanie funkcji , GetPrevlub Find składowej.

ARG_TYPE
Parametr szablonu określający typ elementu listy (może być odwołaniem).

newElement
Element, który ma zostać dodany do tej listy.

Wartość zwracana

POSITION Wartość, która może służyć do iteracji lub pobierania elementu listy.

Uwagi

Jeśli position parametr to NULL, element zostanie wstawiony na początku listy.

Przykład

// 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

Wskazuje, czy ta lista nie zawiera żadnych elementów.

BOOL IsEmpty() const;

Wartość zwracana

Niezerowe, jeśli ta lista jest pusta; w przeciwnym razie 0.

Przykład

// 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

Usuwa wszystkie elementy z tej listy i zwalnia skojarzona pamięć.

void RemoveAll();

Uwagi

Jeśli lista jest już pusta, nie jest generowany żaden błąd.

Przykład

// 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

Usuwa określony element z tej listy.

void RemoveAt(POSITION position);

Parametry

position
Pozycja elementu, który ma zostać usunięty z listy.

Uwagi

Musisz upewnić się, że wartość POSITION reprezentuje prawidłową pozycję na liście. Jeśli jest on nieprawidłowy, oznacza to, że wersja debugowania biblioteki klas programu Microsoft Foundation jest asercyjna.

Przykład

// 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

Usuwa element z nagłówka listy i zwraca do niego wskaźnik.

TYPE RemoveHead();

Parametry

TYPE
Parametr szablonu określający typ elementów na liście.

Wartość zwracana

Element wcześniej znajdujący się na czele listy.

Uwagi

Przed wywołaniem metody RemoveHeadupewnij się, że lista nie jest pusta. Jeśli lista jest pusta, zostanie asercyjna wersja debugowania biblioteki klas programu Microsoft Foundation. Użyj polecenia IsEmpty , aby sprawdzić, czy lista zawiera elementy.

Przykład

// 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

Usuwa element z końca listy i zwraca do niego wskaźnik.

TYPE RemoveTail();

Parametry

TYPE
Parametr szablonu określający typ elementów na liście.

Wartość zwracana

Element, który znajdował się na ogonie listy.

Uwagi

Przed wywołaniem metody RemoveTailupewnij się, że lista nie jest pusta. Jeśli lista jest pusta, zostanie asercyjna wersja debugowania biblioteki klas programu Microsoft Foundation. Użyj polecenia IsEmpty , aby sprawdzić, czy lista zawiera elementy.

Przykład

// 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

Zmienna typu POSITION jest kluczem listy.

void SetAt(POSITION pos, ARG_TYPE newElement);

Parametry

pos
Element POSITION do ustawienia.

ARG_TYPE
Parametr szablonu określający typ elementu listy (może być odwołaniem).

newElement
Element, który ma zostać dodany do listy.

Uwagi

Nie jest on taki sam jak indeks i nie można samodzielnie działać na POSITION wartości. SetAt zapisuje element na określonej pozycji na liście.

Musisz upewnić się, że wartość POSITION reprezentuje prawidłową pozycję na liście. Jeśli jest on nieprawidłowy, oznacza to, że wersja debugowania biblioteki klas programu Microsoft Foundation jest asercyjna.

Przykład

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

Zobacz też

Przykład MFC COLLECT
CObject Klasa
Wykres hierarchii
CMap Klasa
CArray Klasa