Classe CAtlList

Esta classe fornece métodos para criar e gerir um objeto de lista.

Sintaxe

template<typename E, class ETraits = CElementTraits<E>>
class CAtlList

Parâmetros

E
O tipo de elemento.

ETraits
O código usado para copiar ou mover elementos. Consulte a Classe CElementTraits para mais detalhes.

Membros

Definições de Tipos Públicas

Construtores Públicos

Métodos Públicos

Observações

A CAtlList classe suporta listas ordenadas de objetos não únicos acessíveis sequencialmente ou por valor. CAtlList As listas comportam-se como listas duplamente ligadas. Cada lista tem uma cara e uma coroa, e novos elementos (ou listas em alguns casos) podem ser adicionados a qualquer um dos extremos da lista, ou inseridos antes ou depois de elementos específicos.

A maioria dos CAtlList métodos utiliza um valor de posição. Este valor é usado pelos métodos para referenciar a localização real da memória onde os elementos estão armazenados, e não deve ser calculado ou previsto diretamente. Se for necessário aceder ao n-ésimoelemento da lista, o método CAtlList::FindIndex devolverá o valor de posição correspondente para um dado índice. Os métodos CAtlList::GetNext e CAtlList::GetPrev podem ser usados para iterar pelos objetos da lista.

Para mais informações sobre as classes de coleção disponíveis com a ATL, consulte Classes de Coleção da ATL.

Requerimentos

Cabeçalho: atlcoll.h

CAtlList::AddHead

Chame este método para adicionar um elemento à cabeça da lista.

POSITION AddHead();
POSITION AddHead(INARGTYPE element);

Parâmetros

elemento
O novo elemento.

Valor de retorno

Devolve a posição do elemento recém-adicionado.

Observações

Se for usada a primeira versão, um elemento vazio é criado usando o seu construtor padrão, em vez do seu construtor de cópia.

Example

// Declare a list of integers
CAtlList<int> myList;

// Add some elements, each to the head of the list.
// As each new element is added, the previous head is
// pushed down the list.
myList.AddHead(42);
myList.AddHead(49);

// Confirm the value currently at the head of the list
ATLASSERT(myList.GetHead() == 49);

// Confirm the value currently at the tail of the list
ATLASSERT(myList.GetTail() == 42);   

CAtlList::AddHeadList

Chame este método para adicionar uma lista existente ao topo da lista.

void AddHeadList(const CAtlList<E, ETraits>* plNew);

Parâmetros

plNew
A lista a acrescentar.

Observações

A lista apontada pelo plNew é inserida no início da lista existente. Em builds de depuração, ocorrerá uma falha de asserção se plNew for igual a NULL.

Example

// Define two lists of integers
CAtlList<int> myList1;
CAtlList<int> myList2;

// Fill up the first list
myList1.AddTail(1);
myList1.AddTail(2);
myList1.AddTail(3);

// Add an element to the second list
myList2.AddTail(4);

// Insert the first list into the second
myList2.AddHeadList(&myList1);

// The second list now contains:
// 1, 2, 3, 4   

CAtlList::AddTail

Chame este método para adicionar um elemento à cauda desta lista.

POSITION AddTail();
POSITION AddTail(INARGTYPE element);

Parâmetros

elemento
O elemento a acrescentar.

Valor de retorno

Devolve a POSIÇÃO do elemento recém-adicionado.

Observações

Se for usada a primeira versão, um elemento vazio é criado usando o seu construtor padrão, em vez do seu construtor de cópia. O elemento é adicionado ao final da lista, tornando-se assim a cauda. Este método pode ser usado com uma lista vazia.

Example

// Define the list
CAtlList<int> myList;

// Add elements to the tail
myList.AddTail(1);
myList.AddTail(2);
myList.AddTail(3);

// Confirm the current head of the list
ATLASSERT(myList.GetHead() == 1);

// Confirm the current tail of the list
ATLASSERT(myList.GetTail() == 3);   

CAtlList::AddTailList

Chame este método para adicionar uma lista existente à cauda desta lista.

void AddTailList(const CAtlList<E, ETraits>* plNew);

Parâmetros

plNew
A lista a acrescentar.

Observações

A lista apontada por plNew é inserida após o último elemento (se existir) no objeto lista. O último elemento na lista plNew torna-se, portanto, a cauda. Em builds de depuração, ocorrerá uma falha de asserção se plNew for igual a NULL.

Example

// Define two integer lists
CAtlList<int> myList1;
CAtlList<int> myList2;

// Fill up the first list
myList1.AddTail(1);
myList1.AddTail(2);
myList1.AddTail(3);

// Add an element to the second list
myList2.AddTail(4);

// Insert the first list into the second
myList2.AddTailList(&myList1);

// The second list now contains:
// 4, 1, 2, 3   

CAtlList::AssertValid

Chame este método para confirmar que a lista é válida.

void AssertValid() const;

Observações

Em builds de depuração, ocorrerá uma falha de asserção se o objeto da lista não for válido. Para ser válida, uma lista vazia deve ter tanto a cabeça como a cauda apontando para NULL, e uma lista que não está vazia deve ter tanto a cabeça como a cauda a apontar para endereços válidos.

Example

// Define the list
CAtlList<int> myList;

// AssertValid only exists in debug builds
#ifdef _DEBUG
myList.AssertValid();
#endif   

CAtlList::CAtlList

O construtor.

CAtlList(UINT nBlockSize = 10) throw();

Parâmetros

nBlockSize
O tamanho do bloco.

Observações

O construtor do CAtlList objeto. O tamanho do bloco é uma medida da quantidade de memória alocada quando um novo elemento é necessário. Blocos maiores reduzem chamadas para rotinas de alocação de memória, mas consomem mais recursos.

Example

// Define two lists
CAtlList<int> myList1;
CAtlList<double> myList2;   

CAtlList::~CAtlList

O destruidor.

~CAtlList() throw();

Observações

Liberta todos os recursos alocados, incluindo uma chamada ao CAtlList::RemoveAll para remover todos os elementos da lista.

Em compilações de depuração, ocorrerá uma falha de asserção se a lista ainda contiver alguns elementos após a chamada a RemoveAll.

CAtlList::Find

Chame este método para pesquisar na lista o elemento especificado.

POSITION Find(INARGTYPE element, POSITION posStartAfter = NULL) const throw();

Parâmetros

elemento
O elemento a encontrar na lista.

posStartAfter
A posição inicial para a busca. Se não for especificado o valor, a pesquisa começa com o elemento cabeça.

Valor de retorno

Devolve o valor POSITION do elemento se encontrado, caso contrário devolve NULL.

Observações

Em builds de depuração, ocorrerá uma falha de asserção se o objeto da lista não for válido, ou se o valor posStartAfter estiver fora do alcance.

Example

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(100);
myList.AddTail(200);
myList.AddTail(300);
myList.AddTail(400);

// Find the '300' element in the list,
// starting from the list head.
POSITION myPos = myList.Find(300);

// Confirm that the element was found
ATLASSERT(myList.GetAt(myPos) == 300);   

CAtlList::FindIndex

Chame este método para obter a posição de um elemento, dado um valor de índice.

POSITION FindIndex(size_t iElement) const throw();

Parâmetros

iElement
O índice baseado em zero do elemento de lista necessário.

Valor de retorno

Devolve o valor POSITION correspondente, ou NULL se o iElement estiver fora do alcance.

Observações

Este método devolve a POSIÇÃO correspondente a um dado valor de índice, permitindo o acesso ao n-ésimo elemento da lista.

Em builds de depuração, ocorrerá uma falha de asserção se o objeto da lista não for válido.

Example

// Define the integer list
CAtlList<int> myList;

// Populate the list
for (int i = 0; i < 100; i++)
{
   myList.AddTail(i);
}

// Iterate through the entire list
for (size_t j = 0; j < myList.GetCount(); j++)
{
   size_t i = myList.GetAt(myList.FindIndex(j));
   ATLASSERT(i == j);
}   

CAtlList::GetAt

Chame este método para devolver o elemento numa posição especificada na lista.

E& GetAt(POSITION pos) throw();
const E& GetAt(POSITION pos) const throw();

Parâmetros

Ponto de venda
O valor POSITION que especifica um elemento particular.

Valor de retorno

Uma referência ou cópia do elemento.

Observações

Se a lista for const, GetAt devolve uma cópia do elemento. Isto permite que o método seja usado apenas no lado direito de uma instrução de atribuição e protege a lista contra modificações.

Se a lista não constfor , GetAt devolve uma referência ao elemento. Isto permite que o método seja usado em ambos os lados de uma instrução de atribuição e, assim, possibilita a modificação das entradas da lista.

Em builds de depuração, ocorrerá uma falha de asserção se pos for igual a NULL.

Example

Veja o exemplo para CAtlList::FindIndex.

CAtlList::GetCount

Chame este método para devolver o número de objetos na lista.

size_t GetCount() const throw();

Valor de retorno

Devolve o número de elementos na lista.

Example

Veja o exemplo para CAtlList::Find.

CAtlList::GetHead

Chame este método para devolver o elemento no topo da lista.

E& GetHead() throw();
const E& GetHead() const throw();

Valor de retorno

Devolve uma referência a, ou uma cópia, do elemento no topo da lista.

Observações

Se a lista for const, GetHead devolve uma cópia do elemento no topo da lista. Isto permite que o método seja usado apenas no lado direito de uma instrução de atribuição e protege a lista contra modificações.

Se a lista não constfor , GetHead devolve uma referência ao elemento no início da lista. Isto permite que o método seja usado em ambos os lados de uma instrução de atribuição e, assim, possibilita a modificação das entradas da lista.

Em builds de depuração, ocorrerá uma falha de asserção se o cabeçalho da lista apontar para NULL.

Example

Veja o exemplo para CAtlList::AddHead.

CAtlList::GetHeadPosition

Chame este método para obter a posição do cabeça da lista.

POSITION GetHeadPosition() const throw();

Valor de retorno

Devolve o valor POSITION correspondente ao elemento no topo da lista.

Observações

Se a lista estiver vazia, o valor devolvido é NULL.

Example

// Define the integer list
CAtlList<int> myList;
int i;

// Populate the list
for (i = 0; i < 100; i++)
{
   myList.AddTail(i);
}

// Get the starting position value
POSITION myPos = myList.GetHeadPosition();

// Iterate through the entire list
i = 0;
int j;

do {
   j = myList.GetNext(myPos);
   ATLASSERT(i == j);
   i++;
} while (myPos != NULL);   

CAtlList::GetNext

Chame este método para devolver o próximo elemento da lista.

E& GetNext(POSITION& pos) throw();
const E& GetNext(POSITION& pos) const throw();

Parâmetros

Ponto de venda
Um valor POSITION, devolvido por uma chamada anterior para GetNext, CAtlList::GetHeadPosition, ou outro CAtlList método.

Valor de retorno

Se a lista for const, GetNext devolve uma cópia do elemento seguinte da lista. Isto permite que o método seja usado apenas no lado direito de uma instrução de atribuição e protege a lista contra modificações.

Se a lista não constfor , GetNext devolve uma referência ao próximo elemento da lista. Isto permite que o método seja usado em ambos os lados de uma instrução de atribuição e, assim, possibilita a modificação das entradas da lista.

Observações

O contador POSITION, pos, é atualizado para apontar para o próximo elemento na lista, ou NULL se não houver mais elementos. Em builds de depuração, ocorrerá uma falha de asserção se pos for igual a NULL.

Example

Veja o exemplo de CAtlList::GetHeadPosition.

CAtlList::GetPrev

Chame este método para devolver o elemento anterior da lista.

E& GetPrev(POSITION& pos) throw();
const E& GetPrev(POSITION& pos) const throw();

Parâmetros

Ponto de venda
Um valor POSITION, devolvido por uma chamada anterior para GetPrev, CAtlList::GetTailPosition, ou outro CAtlList método.

Valor de retorno

Se a lista for const, GetPrev devolve uma cópia de um elemento da lista. Isto permite que o método seja usado apenas no lado direito de uma instrução de atribuição e protege a lista contra modificações.

Se a lista não constfor , GetPrev devolve uma referência a um elemento da lista. Isto permite que o método seja usado em ambos os lados de uma instrução de atribuição e, assim, possibilita a modificação das entradas da lista.

Observações

O contador POSITION, pos, é atualizado para apontar para o elemento anterior na lista, ou NULL se não houver mais elementos. Em builds de depuração, ocorrerá uma falha de asserção se pos for igual a NULL.

Example

Veja o exemplo de CAtlList::GetTailPosition.

CAtlList::GetTail

Chame este método para devolver o elemento na cauda da lista.

E& GetTail() throw();
const E& GetTail() const throw();

Valor de retorno

Devolve uma referência a, ou uma cópia, do elemento no final da lista.

Observações

Se a lista for const, GetTail devolve uma cópia do elemento no topo da lista. Isto permite que o método seja usado apenas no lado direito de uma instrução de atribuição e protege a lista contra modificações.

Se a lista não constfor , GetTail devolve uma referência ao elemento no início da lista. Isto permite que o método seja usado em ambos os lados de uma instrução de atribuição e, assim, possibilita a modificação das entradas da lista.

Em builds de depuração, ocorre uma falha de asserção se a cauda da lista apontar para NULL.

Example

Veja o exemplo para CAtlList::AddTail.

CAtlList::GetTailPosition

Chame este método para obter a posição da cauda da lista.

POSITION GetTailPosition() const throw();

Valor de retorno

Devolve o valor POSITION correspondente ao elemento na cauda da lista.

Observações

Se a lista estiver vazia, o valor devolvido é NULL.

Example

// Define the integer list
CAtlList<int> myList;
int i;

// Populate the list
for (i = 0; i < 100; i++)
{
   myList.AddHead(i);
}

// Get the starting position value
POSITION myP = myList.GetTailPosition();

// Iterate through the entire list
i = 0;
int j;

do {
   j = myList.GetPrev(myP);
   ATLASSERT(i == j);
   i++;
} while (myP != NULL);   

CAtlList::INARGTYPE

Tipo usado quando um elemento é passado como argumento de entrada.

typedef ETraits::INARGTYPE INARGTYPE;

CAtlList::InsertAfter

Chame este método para inserir um novo elemento na lista após a posição especificada.

POSITION InsertAfter(POSITION pos, INARGTYPE element);

Parâmetros

Ponto de venda
O valor POSITION após o qual o novo elemento será inserido.

elemento
O elemento a inserir.

Valor de retorno

Devolve o valor POSITION do novo elemento.

Observações

Em builds de depuração, ocorrerá uma falha de asserção se a lista não for válida, se a inserção falhar, ou se for feita uma tentativa de inserir o elemento após a cauda.

Example

// Define the integer list
CAtlList<int> myList;

// Populate the list
POSITION myPos = myList.AddHead(1);
myPos = myList.InsertAfter(myPos, 2);
myPos = myList.InsertAfter(myPos, 3);

// Confirm the tail value is as expected
ATLASSERT(myList.GetTail() == 3);   

CAtlList::InsertBefore

Chame este método para inserir um novo elemento na lista antes da posição especificada.

POSITION InsertBefore(POSITION pos, INARGTYPE element);

Parâmetros

Ponto de venda
O novo elemento será inserido na lista antes deste valor POSITION.

elemento
O elemento a inserir.

Valor de retorno

Devolve o valor POSITION do novo elemento.

Observações

Em builds de depuração, ocorrerá uma falha de asserção se a lista não for válida, se a inserção falhar, ou se for feita uma tentativa de inserir o elemento antes da cabeça.

Example

// Define the integer list
CAtlList<int> myList;

// Populate the list
POSITION myPos = myList.AddHead(1);
myPos = myList.InsertBefore(myPos, 2);
myPos = myList.InsertBefore(myPos, 3);

// Confirm the head value is as expected
ATLASSERT(myList.GetHead() == 3);  

CAtlList::IsEmpty

Chame este método para determinar se a lista está vazia.

bool IsEmpty() const throw();

Valor de retorno

Retorna verdadeiro se a lista não contiver objetos, caso contrário falso.

Example

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(1);
myList.AddTail(2);
myList.AddTail(3);
myList.AddTail(4);

// Confirm not empty
ATLASSERT(myList.IsEmpty() == false);

// Remove the tail element
myList.RemoveTailNoReturn();

// Confirm not empty
ATLASSERT(myList.IsEmpty() == false);

// Remove the head element
myList.RemoveHeadNoReturn();

// Confirm not empty
ATLASSERT(myList.IsEmpty() == false);

// Remove all remaining elements
myList.RemoveAll();

// Confirm empty
ATLASSERT(myList.IsEmpty() == true);   

CAtlList::MoveToHead

Chame este método para mover o elemento especificado para o topo da lista.

void MoveToHead(POSITION pos) throw();

Parâmetros

Ponto de venda
O valor POSITION do elemento a mover.

Observações

O elemento especificado é movido da sua posição atual para o topo da lista. Em builds de depuração, ocorrerá uma falha de asserção se pos for igual a NULL.

Example

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(1);
myList.AddTail(2);
myList.AddTail(3);
myList.AddTail(4);

// Move the tail element to the head
myList.MoveToHead(myList.GetTailPosition());

// Confirm the head is as expected
ATLASSERT(myList.GetHead() == 4);

// Move the head element to the tail
myList.MoveToTail(myList.GetHeadPosition());

// Confirm the tail is as expected
ATLASSERT(myList.GetTail() == 4);   

CAtlList::MoveToTail

Chame este método para mover o elemento especificado para a cauda da lista.

void MoveToTail(POSITION pos) throw();

Parâmetros

Ponto de venda
O valor POSITION do elemento a mover.

Observações

O elemento especificado é movido da sua posição atual para a cauda da lista. Em builds de depuração, ocorrerá uma falha de asserção se pos for igual a NULL.

Example

Veja o exemplo de CAtlList::MoveToHead.

CAtlList::RemoveAll

Chame este método para remover todos os elementos da lista.

void RemoveAll() throw();

Observações

Este método remove todos os elementos da lista e liberta a memória alocada. Em compilações de depuração, um ATLASSERT será criado se todos os elementos não forem eliminados ou se a estrutura da lista estiver corrompida.

Example

Veja o exemplo para CAtlList::IsEmpty.

CAtlList::RemoveAt

Chame este método para remover um único elemento da lista.

void RemoveAt(POSITION pos) throw();

Parâmetros

Ponto de venda
O valor POSITION do elemento a remover.

Observações

O elemento referenciado por pos é removido e a memória é libertada. É aceitável usá-lo RemoveAt para remover a cabeça ou a cauda da lista.

Nas compilações de depuração, ocorrerá uma falha de asserção se a lista não for válida ou se a remoção do elemento fizer com que a lista aceda a memória que não faz parte da estrutura da lista.

Example

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(100);
myList.AddTail(200);
myList.AddTail(300);

// Use RemoveAt to remove elements one by one
myList.RemoveAt(myList.Find(100));
myList.RemoveAt(myList.Find(200));
myList.RemoveAt(myList.Find(300));

// Confirm all have been deleted
ATLASSERT(myList.IsEmpty() == true);   

CAtlList::RemoveHead

Chame este método para remover o elemento no topo da lista.

E RemoveHead();

Valor de retorno

Devolve o elemento no topo da lista.

Observações

O elemento cabeça é eliminado da lista e a memória é libertada. Uma cópia do elemento é devolvida. Em compilações de depuração, ocorrerá uma falha de asserção se a lista estiver vazia.

Example

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(100);
myList.AddTail(200);
myList.AddTail(300);

// Confirm the head of the list
ATLASSERT(myList.GetHead() == 100);

// Remove the head of the list
ATLASSERT(myList.RemoveHead() == 100);

// Confirm the new head of the list
ATLASSERT(myList.GetHead() == 200);   

CAtlList::RemoveHeadNoReturn

Chame este método para remover o elemento no topo da lista sem devolver um valor.

void RemoveHeadNoReturn() throw();

Observações

O elemento cabeça é eliminado da lista e a memória é libertada. Em compilações de depuração, ocorrerá uma falha de asserção se a lista estiver vazia.

Example

Veja o exemplo para CAtlList::IsEmpty.

CAtlList::RemoveTail

Chame este método para remover o elemento na cauda da lista.

E RemoveTail();

Valor de retorno

Devolve o elemento na cauda da lista.

Observações

O elemento cauda é eliminado da lista e a memória é libertada. Uma cópia do elemento é devolvida. Em compilações de depuração, ocorrerá uma falha de asserção se a lista estiver vazia.

Example

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(100);
myList.AddTail(200);
myList.AddTail(300);

// Confirm the tail of the list
ATLASSERT(myList.GetTail() == 300);

// Remove the tail of the list
ATLASSERT(myList.RemoveTail() == 300);

// Confirm the new tail of the list
ATLASSERT(myList.GetTail() == 200);   

CAtlList::RemoverCaudaNãoRetorno

Chame este método para remover o elemento na cauda da lista sem devolver um valor.

void RemoveTailNoReturn() throw();

Observações

O elemento cauda é eliminado da lista e a memória é libertada. Em compilações de depuração, ocorrerá uma falha de asserção se a lista estiver vazia.

Example

Veja o exemplo para CAtlList::IsEmpty.

CAtlList::SetAt

Chame este método para definir o valor do elemento numa posição dada na lista.

void SetAt(POSITION pos, INARGTYPE element);

Parâmetros

Ponto de venda
O valor POSITION correspondente ao elemento a mudar.

elemento
O novo valor do elemento.

Observações

Substitui o valor existente por elemento. Em builds de depuração, ocorrerá uma falha de asserção se pos for igual a NULL.

Example

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(100);
myList.AddTail(200);

// Use SetAt to change the values stored in the head and
// tail of the list
myList.SetAt(myList.GetHeadPosition(), myList.GetHead() * 10);
myList.SetAt(myList.GetTailPosition(), myList.GetTail() * 10);

// Confirm the values
ATLASSERT(myList.GetHead() == 1000);
ATLASSERT(myList.GetTail() == 2000);   

CAtlList::SwapElements

Chame este método para trocar elementos na lista.

void SwapElements(POSITION pos1, POSITION pos2) throw();

Parâmetros

pos1
O primeiro valor da POSIÇÃO.

pos2
O segundo valor POSIÇÃO.

Observações

Troca os elementos nas duas posições especificadas. Em builds de depuração, ocorrerá uma falha de asserção se qualquer um dos valores de posição for igual a NULL.

Example

// Define the integer list
CAtlList<int> myList;

// Populate the list
for (int i = 0; i < 100; i++)
{
   myList.AddHead(i);
}

// Order is: 99, 98, 97, 96...
ATLASSERT(myList.GetHead() == 99);
ATLASSERT(myList.GetTail() == 0);

// Perform a crude bubble sort
for (int j = 0; j < 100; j++)
{
   for(int i = 0; i < 99; i++)
   {
      if (myList.GetAt(myList.FindIndex(i)) > 
         myList.GetAt(myList.FindIndex(i+1)))
      {
         myList.SwapElements(myList.FindIndex(i), myList.FindIndex(i+1));
      }
   }
}

// Order is: 0, 1, 2, 3...
ATLASSERT(myList.GetHead() == 0);
ATLASSERT(myList.GetTail() == 99);   

Consulte também

Aula de CList
Visão geral da classe