Класс `CList`

Статья
06/16/2023

Поддерживает упорядоченные списки неуникальных объектов, доступные последовательно или по значению.

Синтаксис

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

Участники

Открытые конструкторы

Имя	Описание
`CList::CList`	Создает пустой упорядоченный список.

Открытые методы

Имя	Описание
`CList::AddHead`	Добавляет элемент (или все элементы в другом списке) в голову списка (делает новую голову).
`CList::AddTail`	Добавляет элемент (или все элементы в другом списке) в хвост списка (делает новый хвост).
`CList::Find`	Возвращает позицию элемента, указанного значением указателя.
`CList::FindIndex`	Возвращает позицию элемента, заданного отсчитываемым от нуля индексом.
`CList::GetAt`	Возвращает элемент в заданной позиции.
`CList::GetCount`	Возвращает количество элементов в этом списке.
`CList::GetHead`	Возвращает головной элемент списка (не может быть пустым).
`CList::GetHeadPosition`	Возвращает позицию головного элемента списка.
`CList::GetNext`	Возвращает следующий элемент для итерации.
`CList::GetPrev`	Возвращает предыдущий элемент для итерации.
`CList::GetSize`	Возвращает количество элементов в этом списке.
`CList::GetTail`	Возвращает хвостовой элемент списка (не может быть пустым).
`CList::GetTailPosition`	Возвращает положение хвостового элемента списка.
`CList::InsertAfter`	Вставляет новый элемент после заданной позиции.
`CList::InsertBefore`	Вставляет новый элемент перед заданной позицией.
`CList::IsEmpty`	Проверяет условие пустого списка (без элементов).
`CList::RemoveAll`	Удаляет все элементы из этого списка.
`CList::RemoveAt`	Удаляет элемент из этого списка, указанный позицией.
`CList::RemoveHead`	Удаляет элемент из головы списка.
`CList::RemoveTail`	Удаляет элемент из хвоста списка.
`CList::SetAt`	Задает элемент в заданной позиции.

Параметры

TYPE
Тип объекта, хранящегося в списке.

ARG_TYPE
Тип, используемый для ссылки на объекты, хранящиеся в списке. Может быть ссылкой.

Замечания

CList списки ведут себя как вдвойне связанные списки.

Переменная типа POSITION является ключом для списка. Вы можете использовать POSITION переменную в качестве итератора для последовательного обхода списка и в качестве закладки для хранения места. Однако позиция не совпадает с индексом.

Вставка элементов очень быстра в голове списка, в хвосте и на известном POSITION. Последовательный поиск необходим для поиска элемента по значению или индексу. Этот поиск может быть медленным, если список длинный.

Если вам нужен дамп отдельных элементов в списке, необходимо задать глубину контекста дампа 1 или больше.

Некоторые функции-члены этого класса вызывают глобальные вспомогательные функции, которые необходимо настроить для большинства использования CList класса. См . вспомогательные элементы класса коллекции в разделе "Макросы и глобальные".

Дополнительные сведения об использовании CListсм. в статье "Коллекции".

Пример

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

Иерархия наследования

CObject

CList

Требования

Заголовок.afxtempl.h

`CList::AddHead`

Добавляет новый элемент или список элементов в голову этого списка.

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

Параметры

ARG_TYPE
Параметр шаблона, указывающий тип элемента списка (может быть ссылкой).

newElement
Новый элемент.

pNewList
Указатель на другой CList список. Элементы в pNewList этом списке будут добавлены.

Возвращаемое значение

Первая версия возвращает POSITION значение только что вставленного элемента.

Замечания

Список может быть пустым перед операцией.

Пример

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

Добавляет новый элемент или список элементов в хвост этого списка.

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

Параметры

ARG_TYPE
Параметр шаблона, указывающий тип элемента списка (может быть ссылкой).

newElement
Элемент, добавляемый в список.

pNewList
Указатель на другой CList список. Элементы в pNewList этом списке будут добавлены.

Возвращаемое значение

Первая версия возвращает POSITION значение только что вставленного элемента.

Замечания

Список может быть пустым перед операцией.

Пример

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

Создает пустой упорядоченный список.

CList(INT_PTR nBlockSize = 10);

Параметры

nBlockSize
Степень детализации выделения памяти для расширения списка.

Замечания

По мере роста списка память выделяется в единицах записей nBlockSize .

Пример

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

Выполняет поиск списка последовательно, чтобы найти первый элемент, соответствующий указанному.searchValue

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

Параметры

ARG_TYPE
Параметр шаблона, указывающий тип элемента списка (может быть ссылкой).

searchValue
Значение, которое нужно найти в списке.

startAfter
Начальная позиция для поиска. Если значение не указано, поиск начинается с головного элемента.

Возвращаемое значение

POSITION Значение, которое можно использовать для итерации или извлечения указателя объекта; NULL если объект не найден.

Пример

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

Использует значение nIndex в качестве индекса в списке.

POSITION FindIndex(INT_PTR nIndex) const;

Параметры

nIndex
Отсчитываемый от нуля индекс элемента списка.

Возвращаемое значение

POSITION Значение, которое можно использовать для итерации или извлечения указателя объекта; NULL если nIndex отрицательный или слишком большой.

Замечания

Он запускает последовательное сканирование из головы списка, остановившись на n-мэлементе.

Пример

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

Возвращает элемент списка в заданной позиции.

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

Параметры

TYPE
Параметр шаблона, указывающий тип объекта в списке.

position
Позиция в списке элемента, который требуется получить.

Возвращаемое значение

См. описание возвращаемого значения для GetHead.

Замечания

GetAt возвращает элемент (или ссылку на элемент), связанный с заданной позицией. Это не то же самое, что и индекс, и вы не можете работать с POSITION значением самостоятельно. Переменная типа POSITION является ключом для списка.

Необходимо убедиться, что значение POSITION представляет допустимую позицию в списке. Если это недопустимо, то утверждается отладочная версия библиотеки классов Microsoft Foundation.

Пример

Пример см. в примере CList::GetHeadPosition.

`CList::GetCount`

Возвращает количество элементов в этом списке.

INT_PTR GetCount() const;

Возвращаемое значение

Целочисленное значение, содержащее число элементов.

Замечания

Вызов этого метода создаст тот же результат, что CList::GetSize и метод.

Пример

Пример см. в примере CList::RemoveHead.

`CList::GetHead`

Возвращает головной элемент (или ссылку на головной элемент) этого списка.

const TYPE& GetHead() const;

TYPE& GetHead();

Параметры

TYPE
Параметр шаблона, указывающий тип объекта в списке.

Возвращаемое значение

Если список указан const, GetHead возвращает копию элемента в начале списка. Это позволяет использовать функцию только в правой части инструкции назначения и защищает список от изменения.

Если список не constуказан, GetHead возвращает ссылку на элемент в начале списка. Это позволяет использовать функцию с любой стороны инструкции назначения и таким образом позволяет изменять записи списка.

Замечания

Перед вызовом GetHeadнеобходимо убедиться, что список не пуст. Если список пуст, то утверждается отладочная версия библиотеки классов Microsoft Foundation. Используется IsEmpty для проверки того, содержит ли список элементы.

Пример

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

Возвращает позицию головного элемента этого списка.

POSITION GetHeadPosition() const;

Возвращаемое значение

Значение POSITION , которое можно использовать для итерации или извлечения указателя объекта; NULL если список пуст.

Пример

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

Возвращает элемент списка, определенный rPosition, а затем задает rPositionPOSITION значение следующей записи в списке.

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

Параметры

TYPE
Параметр шаблона, указывающий тип элементов в списке.

rPosition
Ссылка на POSITION значение, GetHeadPositionвозвращаемое предыдущим GetNextили другим вызовом функции-члена.

Возвращаемое значение

Если список указан const, GetNext возвращает копию элемента списка. Это позволяет использовать функцию только в правой части инструкции назначения и защищает список от изменения.

Если список не constуказан, GetNext возвращает ссылку на элемент списка. Это позволяет использовать функцию с любой стороны инструкции назначения и таким образом позволяет изменять записи списка.

Замечания

Вы можете использовать GetNext в цикле итерации пересылки, если установить начальную позицию с вызовом GetHeadPosition или Find.

Если извлеченный элемент является последним в списке, новое значение имеет значение rPosition NULL.

Пример

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

Возвращает элемент списка, определенный rPosition, а затем задает rPositionPOSITION значение предыдущей записи в списке.

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

Параметры

TYPE
Параметр шаблона, указывающий тип элементов в списке.

rPosition
Ссылка на POSITION значение, возвращаемое предыдущим GetPrev или другим вызовом функции-члена.

Возвращаемое значение

Если список указан const, GetPrev возвращает копию элемента в начале списка. Это позволяет использовать функцию только в правой части инструкции назначения и защищает список от изменения.

Если список не constуказан, GetPrev возвращает ссылку на элемент списка. Это позволяет использовать функцию с любой стороны инструкции назначения и таким образом позволяет изменять записи списка.

Замечания

Можно использовать GetPrev в цикле обратной итерации, если установить начальную позицию с вызовом GetTailPosition или Find.

Если извлеченный элемент является первым в списке, то для нового значения rPosition задано значение NULL.

Пример

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

Возвращает количество элементов списка.

INT_PTR GetSize() const;

Возвращаемое значение

Количество элементов в списке.

Замечания

Вызовите этот метод, чтобы получить количество элементов в списке. Вызов этого метода создаст тот же результат, что CList::GetCount и метод.

Пример

// 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 Возвращает указатель, представляющий хвостовой элемент этого списка.

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

Параметры

TYPE
Параметр шаблона, указывающий тип элементов в списке.

Возвращаемое значение

См. описание возвращаемого значения для GetHead.

Замечания

Перед вызовом GetTailнеобходимо убедиться, что список не пуст. Если список пуст, то утверждается отладочная версия библиотеки классов Microsoft Foundation. Используется IsEmpty для проверки того, содержит ли список элементы.

Пример

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

Получает позицию хвостового элемента этого списка; NULL Значение , если список пуст.

POSITION GetTailPosition() const;

Возвращаемое значение

Пример

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

Добавляет элемент в этот список после элемента в указанной позиции.

POSITION InsertAfter(POSITION position, ARG_TYPE newElement);

Параметры

position
Значение POSITION, возвращаемое предыдущим GetNextGetPrevвызовом функции или Find функцией-членом.

ARG_TYPE
Параметр шаблона, указывающий тип элемента списка.

newElement
Элемент, добавляемый в список.

Возвращаемое значение

POSITION Значение, которое можно использовать для итерации или извлечения элемента списка.

Пример

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

Добавляет элемент в список перед элементом в указанной позиции.

POSITION InsertBefore(POSITION position, ARG_TYPE newElement);

Параметры

position
ЗначениеPOSITION, GetPrevвозвращаемое предыдущим GetNextвызовом функции или Find функцией-членом.

ARG_TYPE
Параметр шаблона, указывающий тип элемента списка (может быть ссылкой).

newElement
Элемент, добавляемый в список.

Возвращаемое значение

POSITION Значение, которое можно использовать для итерации или извлечения элемента списка.

Замечания

Если position это NULLтак, элемент вставляется в начало списка.

Пример

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

Указывает, содержит ли этот список никакие элементы.

BOOL IsEmpty() const;

Возвращаемое значение

Ненулевое значение, если этот список пуст; в противном случае — 0.

Пример

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

Удаляет все элементы из этого списка и освобождает связанную память.

void RemoveAll();

Замечания

Ошибка не возникает, если список уже пуст.

Пример

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

Удаляет указанный элемент из этого списка.

void RemoveAt(POSITION position);

Параметры

position
Позиция элемента, который нужно удалить из списка.

Замечания

Пример

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

Удаляет элемент из головы списка и возвращает указатель на него.

TYPE RemoveHead();

Параметры

TYPE
Параметр шаблона, указывающий тип элементов в списке.

Возвращаемое значение

Элемент ранее в начале списка.

Замечания

Перед вызовом RemoveHeadнеобходимо убедиться, что список не пуст. Если список пуст, то утверждается отладочная версия библиотеки классов Microsoft Foundation. Используется IsEmpty для проверки того, содержит ли список элементы.

Пример

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

Удаляет элемент из хвоста списка и возвращает указатель на него.

TYPE RemoveTail();

Параметры

TYPE
Параметр шаблона, указывающий тип элементов в списке.

Возвращаемое значение

Элемент, который был в хвосте списка.

Замечания

Перед вызовом RemoveTailнеобходимо убедиться, что список не пуст. Если список пуст, то утверждается отладочная версия библиотеки классов Microsoft Foundation. Используется IsEmpty для проверки того, содержит ли список элементы.

Пример

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

Переменная типа POSITION является ключом для списка.

void SetAt(POSITION pos, ARG_TYPE newElement);

Параметры

pos
Элемент POSITION , который нужно задать.

ARG_TYPE
Параметр шаблона, указывающий тип элемента списка (может быть ссылкой).

newElement
Элемент, добавляемый в список.

Замечания

Это не то же самое, что и индекс, и вы не можете работать с POSITION значением самостоятельно. SetAt записывает элемент в указанную позицию в списке.

Пример

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

См. также

Пример MFC COLLECT
CObject Класса
Диаграмма иерархии
CMap Класса
CArray Класса

Поделиться через

Класс CList

Синтаксис

Участники

Открытые конструкторы

Открытые методы

Параметры

Замечания

Пример

Иерархия наследования

Требования

CList::AddHead

Параметры

Возвращаемое значение

Замечания

Пример

CList::AddTail

Параметры

Возвращаемое значение

Замечания

Пример

CList::CList

Параметры

Замечания

Пример

CList::Find

Параметры

Возвращаемое значение

Пример

CList::FindIndex

Параметры

Возвращаемое значение

Замечания

Пример

CList::GetAt

Параметры

Возвращаемое значение

Замечания

Пример

CList::GetCount

Возвращаемое значение

Замечания

Пример

CList::GetHead

Параметры

Возвращаемое значение

Замечания

Пример

CList::GetHeadPosition

Возвращаемое значение

Пример

CList::GetNext

Параметры

Возвращаемое значение

Замечания

Пример

CList::GetPrev

Параметры

Возвращаемое значение

Замечания

Пример

CList::GetSize

Возвращаемое значение

Замечания

Пример

CList::GetTail

Параметры

Возвращаемое значение

Замечания

Пример

CList::GetTailPosition

Возвращаемое значение

Пример

CList::InsertAfter

Параметры

Возвращаемое значение

Пример

CList::InsertBefore

Параметры

Возвращаемое значение

Класс `CList`

`CList::AddHead`

`CList::AddTail`

`CList::CList`

`CList::Find`

`CList::FindIndex`

`CList::GetAt`

`CList::GetCount`

`CList::GetHead`

`CList::GetHeadPosition`

`CList::GetNext`

`CList::GetPrev`

`CList::GetSize`

`CList::GetTail`

`CList::GetTailPosition`

`CList::InsertAfter`

`CList::InsertBefore`

`CList::IsEmpty`

`CList::RemoveAll`

`CList::RemoveAt`

`CList::RemoveHead`

`CList::RemoveTail`

`CList::SetAt`