Partilhar via


Classe CList

Dá suporte a listas ordenadas de objetos não exclusivos acessíveis sequencialmente ou por valor.

Sintaxe

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

Membros

Construtores públicos

Nome Descrição
CList::CList Constrói uma lista ordenada vazia.

Métodos públicos

Nome Descrição
CList::AddHead Adiciona um elemento (ou todos os elementos em outra lista) ao cabeçalho da lista (faz um novo cabeçalho).
CList::AddTail Adiciona um elemento (ou todos os elementos em outra lista) à parte final da lista (faz uma nova parte final).
CList::Find Obtém a posição de um elemento especificado pelo valor do ponteiro.
CList::FindIndex Obtém a posição de um elemento especificado por um índice baseado em zero.
CList::GetAt Obtém o elemento em uma determinada posição.
CList::GetCount Retorna o número de elementos nessa lista.
CList::GetHead Retorna o elemento inicial da lista (não pode estar vazio).
CList::GetHeadPosition Retorna a posição do elemento principal da lista.
CList::GetNext Obtém o próximo elemento para iteração.
CList::GetPrev Obtém o elemento anterior para iteração.
CList::GetSize Retorna o número de elementos nessa lista.
CList::GetTail Retorna o elemento final da lista (não pode estar vazio).
CList::GetTailPosition Retorna a posição do elemento final da lista.
CList::InsertAfter Insere um novo elemento após uma determinada posição.
CList::InsertBefore Insere um novo elemento antes de uma determinada posição.
CList::IsEmpty Testa a condição de lista vazia (sem elementos).
CList::RemoveAll Remove todos os elementos dessa lista.
CList::RemoveAt Remove um elemento dessa lista, especificado pela posição.
CList::RemoveHead Remove o elemento do cabeçalho da lista.
CList::RemoveTail Remove o elemento da parte final da lista.
CList::SetAt Define o elemento em uma determinada posição.

Parâmetros

TYPE
Tipo de objeto armazenado na lista.

ARG_TYPE
Tipo usado para referenciar objetos armazenados na lista. Pode ser uma referência.

Comentários

As listas CList se comportam como listas duplamente vinculadas.

Uma variável do tipo POSITION é uma chave para a lista. Você pode usar uma variável POSITION como um iterador para percorrer uma lista sequencialmente e como um indicador para manter um lugar. No entanto, uma posição não é o mesmo que um índice.

A inserção de elementos é muito rápida no topo da lista, na parte final e em uma POSITION conhecida. Uma pesquisa sequencial é necessária para pesquisar um elemento por valor ou índice. Essa pesquisa pode ser lenta se a lista for longa.

Se você precisar de um despejo de elementos individuais na lista, precisará definir a profundidade do contexto do despejo como 1 ou maior.

Determinadas funções membro dessa classe chamam funções auxiliares globais que precisam ser personalizadas para a maioria dos usos da classe CList. Consulte Auxiliares de classe de coleção na seção "Macros e globais".

Para mais informações sobre como usar CList, confira o artigo Coleções.

Exemplo

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

Hierarquia de herança

CObject

CList

Requisitos

Cabeçalho: afxtempl.h

CList::AddHead

Adiciona um novo elemento ou lista de elementos ao cabeçalho desta lista.

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

Parâmetros

ARG_TYPE
Parâmetro de modelo que especifica o tipo do elemento de lista (pode ser uma referência).

newElement
O novo elemento.

pNewList
Um ponteiro para outra lista CList. Os elementos em pNewList serão adicionados a essa lista.

Valor de retorno

A primeira versão retorna o valor POSITION do elemento que acaba de ser inserido.

Comentários

A lista pode estar vazia antes da operação.

Exemplo

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

Adiciona um novo elemento ou lista de elementos à parte final dessa lista.

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

Parâmetros

ARG_TYPE
Parâmetro de modelo que especifica o tipo do elemento de lista (pode ser uma referência).

newElement
O elemento a ser adicionado a essa lista.

pNewList
Um ponteiro para outra lista CList. Os elementos em pNewList serão adicionados a essa lista.

Valor de retorno

A primeira versão retorna o valor POSITION do elemento que acaba de ser inserido.

Comentários

A lista pode estar vazia antes da operação.

Exemplo

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

Constrói uma lista ordenada vazia.

CList(INT_PTR nBlockSize = 10);

Parâmetros

nBlockSize
A granularidade da alocação de memória para estender a lista.

Comentários

À medida que a lista cresce, a memória é alocada em unidades de nBlockSizeentradas.

Exemplo

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

Pesquisa a lista sequencialmente para encontrar o primeiro elemento que corresponde ao searchValue especificado.

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

Parâmetros

ARG_TYPE
Parâmetro de modelo que especifica o tipo do elemento de lista (pode ser uma referência).

searchValue
O valor a ser encontrado na lista.

startAfter
A posição inicial da pesquisa. Se nenhum valor for especificado, a pesquisa começará com o elemento inicial.

Valor de retorno

Um valor POSITION que pode ser usado para iteração ou recuperação do ponteiro do objeto; NULL se o objeto não for encontrado.

Exemplo

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

Usa o valor de nIndex como um índice na lista.

POSITION FindIndex(INT_PTR nIndex) const;

Parâmetros

nIndex
O índice baseado em zero do elemento de lista a ser encontrado.

Valor de retorno

Um valor de POSITION que pode ser usado para iteração ou recuperação do ponteiro do objeto; NULL se nIndex for negativo ou muito grande.

Comentários

Ele inicia uma verificação sequencial do cabeçalho da lista, parando no nº elemento.

Exemplo

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

Obtém o elemento de lista em uma determinada posição.

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

Parâmetros

TYPE
Parâmetro de modelo que especifica o tipo de objeto na lista.

position
A posição na lista do elemento a ser obtido.

Valor de retorno

Confira a descrição do valor retornado para GetHead.

Comentários

GetAt retorna o elemento (ou uma referência ao elemento) associado a uma determinada posição. Ele não é o mesmo que um índice e você não pode operar em um valor POSITION por conta própria. Uma variável do tipo POSITION é uma chave para a lista.

Você deve garantir que o valor de POSITION represente uma posição válida na lista. Se ele for inválido, a versão de Depuração da biblioteca Microsoft Foundation Class será declarada.

Exemplo

Confira o exemplo de CList::GetHeadPosition.

CList::GetCount

Obtém o número de elementos na lista.

INT_PTR GetCount() const;

Valor de retorno

Um valor inteiro que contém a contagem de elementos.

Comentários

Chamar esse método gera o mesmo resultado que o do método CList::GetSize.

Exemplo

Confira o exemplo de CList::RemoveHead.

CList::GetHead

Obtém o elemento inicial (ou uma referência ao elemento inicial) dessa lista.

const TYPE& GetHead() const;

TYPE& GetHead();

Parâmetros

TYPE
Parâmetro de modelo que especifica o tipo de objeto na lista.

Valor de retorno

Se a lista é const, GetHead retorna uma cópia do elemento no início da lista. Isso permite que a função seja usada apenas no lado direito de uma instrução de atribuição e protege a lista contra modificações.

Se a lista não é const, GetHead retorna uma referência ao elemento no início da lista. Isso permite que a função seja usada em ambos os lados de uma instrução de atribuição e, portanto, permite que as entradas da lista sejam modificadas.

Comentários

Você precisa garantir que a lista não esteja vazia antes de chamar GetHead. Se a lista estiver vazia, a versão de Depuração da biblioteca Microsoft Foundation Class será declarada. Use IsEmpty para verificar se a lista contém elementos.

Exemplo

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

Obtém a posição do elemento principal desta lista.

POSITION GetHeadPosition() const;

Valor de retorno

Um valor POSITION que pode ser usado para iteração ou recuperação do ponteiro do objeto; NULL se a lista estiver vazia.

Exemplo

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

Obtém o elemento de lista identificado por rPosition, então define rPosition como o valor POSITION da próxima entrada na lista.

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

Parâmetros

TYPE
Parâmetro de modelo que especifica o tipo dos elementos na lista.

rPosition
Uma referência a um valor POSITION retornado por uma chamada de função membro GetNext, GetHeadPosition ou outra chamada de função membro anterior.

Valor de retorno

Se a lista é const, GetNext retorna uma cópia de um elemento da lista. Isso permite que a função seja usada apenas no lado direito de uma instrução de atribuição e protege a lista contra modificações.

Se a lista não é const, GetNext retorna uma referência a um elemento da lista. Isso permite que a função seja usada em ambos os lados de uma instrução de atribuição e, portanto, permite que as entradas da lista sejam modificadas.

Comentários

Você poderá usar GetNext em um loop de iteração direta se estabelecer a posição inicial com uma chamada para GetHeadPosition ou Find.

Você deve garantir que o valor de POSITION represente uma posição válida na lista. Se ele for inválido, a versão de Depuração da biblioteca Microsoft Foundation Class será declarada.

Se o elemento recuperado for o último na lista, o novo valor de rPosition será definido como NULL.

Exemplo

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

Obtém o elemento de lista identificado por rPosition, então define rPosition como o valor POSITION da entrada anterior na lista.

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

Parâmetros

TYPE
Parâmetro de modelo que especifica o tipo dos elementos na lista.

rPosition
Uma referência a um valor POSITION retornado por uma chamada de função membro GetPrev ou outra chamada de função membro anterior.

Valor de retorno

Se a lista é const, GetPrev retorna uma cópia do elemento no início da lista. Isso permite que a função seja usada apenas no lado direito de uma instrução de atribuição e protege a lista contra modificações.

Se a lista não é const, GetPrev retorna uma referência a um elemento da lista. Isso permite que a função seja usada em ambos os lados de uma instrução de atribuição e, portanto, permite que as entradas da lista sejam modificadas.

Comentários

Você poderá usar GetPrev em um loop de iteração reversa se estabelecer a posição inicial com uma chamada para GetTailPosition ou Find.

Você deve garantir que o valor de POSITION represente uma posição válida na lista. Se ele for inválido, a versão de Depuração da biblioteca Microsoft Foundation Class será declarada.

Se o elemento recuperado for o primeiro da lista, o novo valor de rPosition será definido como NULL.

Exemplo

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

Retorna o número de elementos da lista.

INT_PTR GetSize() const;

Valor de retorno

O número de itens da lista.

Comentários

Chame esse método para recuperar o número de elementos na lista. Chamar esse método gera o mesmo resultado que o do método CList::GetCount.

Exemplo

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

Obtém o ponteiro CObject que representa o elemento final desta lista.

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

Parâmetros

TYPE
Parâmetro de modelo que especifica o tipo dos elementos na lista.

Valor de retorno

Confira a descrição do valor retornado para GetHead.

Comentários

Você precisa garantir que a lista não esteja vazia antes de chamar GetTail. Se a lista estiver vazia, a versão de Depuração da biblioteca Microsoft Foundation Class será declarada. Use IsEmpty para verificar se a lista contém elementos.

Exemplo

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

Obtém a posição do elemento final desta lista; NULL se a lista estiver vazia.

POSITION GetTailPosition() const;

Valor de retorno

Um valor POSITION que pode ser usado para iteração ou recuperação do ponteiro do objeto; NULL se a lista estiver vazia.

Exemplo

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

Adiciona um elemento a essa lista após o elemento na posição especificada.

POSITION InsertAfter(POSITION position, ARG_TYPE newElement);

Parâmetros

position
Um valor POSITION retornado por uma chamada de função membro GetNext, GetPrev ou Find anterior.

ARG_TYPE
Parâmetro de modelo que especifica o tipo do elemento de lista.

newElement
O elemento a ser adicionado a essa lista.

Valor de retorno

Um valor POSITION que pode ser usado para iteração ou recuperação do elemento de lista.

Exemplo

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

Adiciona um elemento a essa lista antes do elemento na posição especificada.

POSITION InsertBefore(POSITION position, ARG_TYPE newElement);

Parâmetros

position
Um valor POSITION retornado por uma chamada de função membro GetNext, GetPrev ou Find anterior.

ARG_TYPE
Parâmetro de modelo que especifica o tipo do elemento de lista (pode ser uma referência).

newElement
O elemento a ser adicionado a essa lista.

Valor de retorno

Um valor POSITION que pode ser usado para iteração ou recuperação do elemento de lista.

Comentários

Se position for NULL, o elemento será inserido no início da lista.

Exemplo

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

Indica se essa lista não contém elementos.

BOOL IsEmpty() const;

Valor de retorno

Não zero se essa lista estiver vazia; caso contrário, 0.

Exemplo

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

Remove todos os elementos dessa lista e libera a memória associada.

void RemoveAll();

Comentários

Nenhum erro será gerado se a lista já estiver vazia.

Exemplo

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

Remove o elemento especificado da lista.

void RemoveAt(POSITION position);

Parâmetros

position
A posição do elemento a ser removido da lista.

Comentários

Você deve garantir que o valor de POSITION represente uma posição válida na lista. Se ele for inválido, a versão de Depuração da biblioteca Microsoft Foundation Class será declarada.

Exemplo

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

Remove o elemento da cabeça da lista e retorna um ponteiro para ele.

TYPE RemoveHead();

Parâmetros

TYPE
Parâmetro de modelo que especifica o tipo dos elementos na lista.

Valor de retorno

O elemento anteriormente no início da lista.

Comentários

Você precisa garantir que a lista não esteja vazia antes de chamar RemoveHead. Se a lista estiver vazia, a versão de Depuração da biblioteca Microsoft Foundation Class será declarada. Use IsEmpty para verificar se a lista contém elementos.

Exemplo

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

Remove o elemento da parte final da lista e retorna um ponteiro para ele.

TYPE RemoveTail();

Parâmetros

TYPE
Parâmetro de modelo que especifica o tipo dos elementos na lista.

Valor de retorno

O elemento que estava na parte final da lista.

Comentários

Você precisa garantir que a lista não esteja vazia antes de chamar RemoveTail. Se a lista estiver vazia, a versão de Depuração da biblioteca Microsoft Foundation Class será declarada. Use IsEmpty para verificar se a lista contém elementos.

Exemplo

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

Uma variável do tipo POSITION é uma chave para a lista.

void SetAt(POSITION pos, ARG_TYPE newElement);

Parâmetros

pos
O POSITION do elemento a ser definido.

ARG_TYPE
Parâmetro de modelo que especifica o tipo do elemento de lista (pode ser uma referência).

newElement
O elemento a ser adicionado à lista.

Comentários

Ele não é o mesmo que um índice e você não pode operar em um valor POSITION por conta própria. SetAt grava o elemento na posição especificada na lista.

Você deve garantir que o valor de POSITION represente uma posição válida na lista. Se ele for inválido, a versão de Depuração da biblioteca Microsoft Foundation Class será declarada.

Exemplo

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

Confira também

Exemplo de MFC COLLECT
Classe CObject
Gráfico da hierarquia
Classe CMap
Classe CArray