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
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 nBlockSize
entradas.
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