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


Класс CList

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

Синтаксис

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, а затем задает rPosition POSITION значение следующей записи в списке.

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

Параметры

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

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

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

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

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

Замечания

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

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

Если извлеченный элемент является последним в списке, новое значение имеет значение 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, а затем задает rPosition POSITION значение предыдущей записи в списке.

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

Параметры

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

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

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

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

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

Замечания

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

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

Если извлеченный элемент является первым в списке, то для нового значения 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;

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

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

Пример

// 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
Позиция элемента, который нужно удалить из списка.

Замечания

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

Пример

// 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 записывает элемент в указанную позицию в списке.

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

Пример

// 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 Класс