Classe CObList

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

Sintaxe

class CObList : public CObject

Membros

Construtores públicos

Nome	Descrição
CObList::CObList	Constrói uma lista vazia para ponteiros CObject.

Métodos públicos

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

Comentários

As listas CObList 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 é a mesma 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.

A CObList incorpora a macro IMPLEMENT_SERIAL para suportar serialização e despejo de seus elementos. Se uma lista de ponteiros CObject for armazenada em um arquivo morto, com um operador de inserção sobrecarregado ou com a função de membro Serialize, cada elemento CObject será serializado individualmente.

Se for necessário um despejo de elementos CObject individuais na lista, será necessário definir a profundidade do contexto do despejo para 1 ou maior.

Quando um objeto CObList é excluído ou quando seus elementos são removidos, apenas os ponteiros CObject são removidos, não os objetos que eles referenciam.

Você pode derivar suas classes de CObList. Sua nova classe de lista, projetada para conter ponteiros para objetos derivados de CObject, adiciona membros de dados e funções de membro. Observe que a lista resultante não é fortemente tipada de modo estrito, pois permite a inserção de qualquer ponteiro CObject.

Observação

Você deve usar a macro IMPLEMENT_SERIAL na implementação de sua classe derivada se pretende serializar a lista.

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

Hierarquia de herança

CObject

CObList

Requisitos

Cabeçalho: afxcoll.h

CObList::AddHead

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

POSITION AddHead(CObject* newElement);
void AddHead(CObList* pNewList);

Parâmetros

newElement
O ponteiro CObject a ser adicionado a essa lista.

pNewList
Um ponteiro para outra lista CObList. 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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::AddHead.

Classe	Função membro
CPtrList	POSITION AddHead( void * newElement ); void AddHead( CPtrList * pNewList );
CStringList	POSITION AddHead(const CString& newElement ); POSITION AddHead(LPCTSTR newElement ); void AddHead(CStringList * pNewList );

Comentários

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

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
list.AddHead(new CAge(21)); // 21 is now at head.
list.AddHead(new CAge(40)); // 40 replaces 21 at head.
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("AddHead example: ") << &list << _T("\n");
#endif      

Os resultados deste programa são os seguintes:

AddHead example: A CObList with 2 elements
a CAge at $44A8 40
a CAge at $442A 21

CObList::AddTail

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

POSITION AddTail(CObject* newElement);
void AddTail(CObList* pNewList);

Parâmetros

newElement
O ponteiro CObject a ser adicionado a essa lista.

pNewList
Um ponteiro para outra lista CObList. 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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::AddTail.

Classe	Função membro
CPtrList	POSITION AddTail( void * newElement ); void AddTail( CPtrList * pNewList );
CStringList	POSITION AddTail( const CString& newElement ); POSITION AddTail( LPCTSTR newElement ); void AddTail( CStringList * pNewList );

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
list.AddTail(new CAge(21));
list.AddTail(new CAge(40)); // List now contains (21, 40).
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("AddTail example: ") << &list << _T("\n");
#endif      

Os resultados deste programa são os seguintes:

AddTail example: A CObList with 2 elements
a CAge at $444A 21
a CAge at $4526 40

CObList::CObList

Constrói uma lista de ponteiros CObject vazia.

CObList(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. Se uma alocação de memória falhar, um CMemoryException será gerado.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::CObList.

Classe	Função membro
CPtrList	CPtrList( INT_PTR nBlockSize = 10 );
CStringList	CStringList( INT_PTR nBlockSize = 10 );

Exemplo

Veja abaixo uma listagem da classe CAge derivada de CObjectusada em todos os exemplos de coleção:

// Simple CObject-derived class for CObList and other examples
class CAge : public CObject
{
   DECLARE_SERIAL(CAge)
private:
   int   m_years;
public:
   CAge() { m_years = 0; }
   CAge(int age) { m_years = age; }
   CAge(const CAge& a) { m_years = a.m_years; } // Copy constructor
   void Serialize(CArchive& ar);
   void AssertValid() const;
   const CAge& operator=(const CAge& a)
   {
      m_years = a.m_years; return *this;
   }
   BOOL operator==(CAge a)
   {
      return m_years == a.m_years;
   }
#ifdef _DEBUG
   void Dump(CDumpContext& dc) const
   {
      CObject::Dump(dc);
      dc << m_years;
   }
#endif
};

Veja abaixo um exemplo de uso do construtor CObList:

CObList list(20);  // List on the stack with blocksize = 20.

CObList* plist = new CObList; // List on the heap with default 
                              // blocksize.         

CObList::Find

Pesquisa a lista sequencialmente para localizar o primeiro ponteiro CObject que corresponde ao ponteiro CObject especificado.

POSITION Find(
    CObject* searchValue,
    POSITION startAfter = NULL) const;

Parâmetros

searchValue
O ponteiro do objeto a ser encontrado nesta lista.

startAfter
A posição inicial da pesquisa.

Valor de retorno

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

Comentários

Observe que os valores de ponteiro são comparados, não o conteúdo dos objetos.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::Find.

Classe	Função membro
CPtrList	POSITION Find( void *searchValue , POSITION startAfter = NULL ) const;
CStringList	POSITION Find( LPCTSTR searchValue , POSITION startAfter = NULL ) const;

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
CAge* pa1;
CAge* pa2;
POSITION pos;
list.AddHead(pa1 = new CAge(21));
list.AddHead(pa2 = new CAge(40));    // List now contains (40, 21).
if ((pos = list.Find(pa1)) != NULL) // Hunt for pa1
{                                  // starting at head by default.
   ASSERT(*(CAge*)list.GetAt(pos) == CAge(21));
}

CObList::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 de ponteiro de objeto; NULL se nIndex for muito grande. (A estrutura gerará uma declaração se nIndex for negativo.)

Comentários

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

A tabela a seguir mostra outras funções de membro semelhantes a CObList::FindIndex.

Classe	Função membro
CPtrList	POSITION FindIndex( INT_PTR nIndex ) const;
CStringList	POSITION FindIndex( INT_PTR nIndex ) const;

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
POSITION pos;

list.AddHead(new CAge(21));
list.AddHead(new CAge(40)); // List now contains (40, 21).
if ((pos = list.FindIndex(0)) != NULL)
{
   ASSERT(*(CAge*)list.GetAt(pos) == CAge(40));
}

CObList::GetAt

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

CObject*& GetAt(POSITION position);
const CObject*& GetAt(POSITION position) const;

Parâmetros

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

Valor de retorno

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

Comentários

Não é o mesmo que um índice, e você não pode operar em um POSITION valor por conta própria. GetAt recupera o ponteiro CObject associado a uma determinada posição.

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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::GetAt.

Classe	Função membro
CPtrList	const void*& GetAt( POSITION position ) const; void*& GetAt( POSITION position );
CStringList	const CString& GetAt( POSITION position ) const; CString& GetAt( POSITION position );

Exemplo

Confira o exemplo de FindIndex.

CObList::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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::GetCount.

Classe	Função membro
CPtrList	INT_PTR GetCount( ) const;
CStringList	INT_PTR GetCount( ) const;

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;

list.AddHead(new CAge(21));
list.AddHead(new CAge(40)); // List now contains (40, 21).
ASSERT(list.GetCount() == 2);

CObList::GetHead

Obtém o ponteiro CObject que representa o elemento de cabeçalho desta lista.

CObject*& GetHead();
const CObject*& GetHead() const;

Valor de retorno

Se a lista for acessada por meio de um ponteiro para um const CObList, GetHead retornará um ponteiro CObject. Isso permite que a função seja usada apenas no lado direito de uma instrução de atribuição e, portanto, protege a lista contra modificações.

Se a lista for acessada diretamente ou por meio de um ponteiro para um CObList, GetHead retornará uma referência a um ponteiro CObject. 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ê deve 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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::GetHead.

Classe	Função membro
CPtrList	const void*& GetHead( ) const; void*& GetHead( );
CStringList	const CString& GetHead( ) const; CString& GetHead( );

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

O exemplo a seguir ilustra o uso de GetHead no lado esquerdo de uma instrução de atribuição.

const CObList* cplist;

CObList* plist = new CObList;
CAge* page1 = new CAge(21);
CAge* page2 = new CAge(30);
CAge* page3 = new CAge(40);
plist->AddHead(page1);
plist->AddHead(page2);  // List now contains (30, 21).
// The following statement REPLACES the head element.
plist->GetHead() = page3; // List now contains (40, 21).
ASSERT(*(CAge*)plist->GetHead() == CAge(40));
cplist = plist;  // cplist is a pointer to a const list.
// cplist->GetHead() = page3; // Error: can't assign a pointer to a const list
ASSERT(*(CAge*)plist->GetHead() == CAge(40)); // OK

delete page1;
delete page2;
delete page3;
delete plist; // Cleans up memory.      

CObList::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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::GetHeadPosition.

Classe	Função membro
CPtrList	POSITION GetHeadPosition( ) const;
CStringList	POSITION GetHeadPosition( ) const;

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
POSITION pos;

list.AddHead(new CAge(21));
list.AddHead(new CAge(40)); // List now contains (40, 21).
if ((pos = list.GetHeadPosition()) != NULL)
{
   ASSERT(*(CAge*)list.GetAt(pos) == CAge(40));
}

CObList::GetNext

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

CObject*& GetNext(POSITION& rPosition);
const CObject* GetNext(POSITION& rPosition) const;

Parâmetros

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

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

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.

É possível remover um elemento durante uma iteração. Confira o exemplo de RemoveAt.

Observação

Do MFC 8.0, a versão const deste método foi alterada para retornar const CObject* em vez de const CObject*&. Essa alteração foi feita para colocar o compilador em conformidade com o padrão C++.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::GetNext.

Classe	Função membro
CPtrList	void*& GetNext( POSITION& rPosition ); const void* GetNext( POSITION& rPosition ) const;
CStringList	CString& GetNext( POSITION& rPosition ); const CString& GetNext( POSITION& rPosition ) const;

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
POSITION pos;
list.AddHead(new CAge(21));
list.AddHead(new CAge(40)); // List now contains (40, 21).
// Iterate through the list in head-to-tail order.
#ifdef _DEBUG
for (pos = list.GetHeadPosition(); pos != NULL;)
{
   afxDump << list.GetNext(pos) << _T("\n");
}
#endif      

Os resultados deste programa são os seguintes:

a CAge at $479C 40
a CAge at $46C0 21

CObList::GetPrev

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

CObject*& GetPrev(POSITION& rPosition);
const CObject* GetPrev(POSITION& rPosition) const;

Parâmetros

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

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

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.

Observação

Do MFC 8.0, a versão const deste método foi alterada para retornar const CObject* em vez de const CObject*&. Essa alteração foi feita para colocar o compilador em conformidade com o padrão C++.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::GetPrev.

Classe	Função membro
CPtrList	void*& GetPrev( POSITION& rPosition ); const void* GetPrev( POSITION& rPosition ) const;
CStringList	CString& GetPrev( POSITION& rPosition ); const CString& GetPrev( POSITION& rPosition ) const;

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
POSITION pos;

list.AddHead(new CAge(21));
list.AddHead(new CAge(40)); // List now contains (40, 21).
// Iterate through the list in tail-to-head order.
for (pos = list.GetTailPosition(); pos != NULL;)
{
#ifdef _DEBUG
   afxDump << list.GetPrev(pos) << _T("\n");
#endif
}

Os resultados deste programa são os seguintes:

a CAge at $421C 21
a CAge at $421C 40

CObList::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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::GetSize.

Classe	Função membro
CPtrList	INT_PTR GetSize( ) const;
CStringList	INT_PTR GetSize( ) const;

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;

list.AddHead(new CAge(21));
list.AddHead(new CAge(40)); // List now contains (40, 21).
ASSERT(list.GetSize() == 2);

CObList::GetTail

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

CObject*& GetTail();
const CObject*& GetTail() const;

Valor de retorno

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

Comentários

Você deve 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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::GetTail.

Classe	Função membro
CPtrList	const void*& GetTail( ) const; void*& GetTail( );
CStringList	const CString& GetTail( ) const; CString& GetTail( );

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;

list.AddHead(new CAge(21));
list.AddHead(new CAge(40)); // List now contains (40, 21).
ASSERT(*(CAge*)list.GetTail() == CAge(21));

CObList::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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::GetTailPosition.

Classe	Função membro
CPtrList	POSITION GetTailPosition( ) const;
CStringList	POSITION GetTailPosition( ) const;

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
POSITION pos;

list.AddHead(new CAge(21));
list.AddHead(new CAge(40)); // List now contains (40, 21).
if ((pos = list.GetTailPosition()) != NULL)
{
    ASSERT(*(CAge*) list.GetAt(pos) == CAge(21));
}     

CObList::InsertAfter

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

POSITION InsertAfter(
    POSITION position,
    CObject* newElement);

Parâmetros

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

newElement
O ponteiro do objeto a ser adicionado a essa lista.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::InsertAfter.

Classe	Função membro
CPtrList	POSITION InsertAfter( POSITION position , void * newElement );
CStringList	POSITION InsertAfter( POSITION position , const CString& newElement ); POSITION InsertAfter( POSITION position , LPCTSTR newElement );

Valor de retorno

Um valor POSITION que é o mesmo que o parâmetro position.

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
POSITION pos1, pos2;
list.AddHead(new CAge(21));
list.AddHead(new CAge(40)); // List now contains (40, 21).
if ((pos1 = list.GetHeadPosition()) != NULL)
{
    pos2 = list.InsertAfter(pos1, new CAge(65));
}
#ifdef _DEBUG
   afxDump.SetDepth(1);
   afxDump << _T("InsertAfter example: ") << &list << _T("\n");
#endif

Os resultados deste programa são os seguintes:

InsertAfter example: A CObList with 3 elements
a CAge at $4A44 40
a CAge at $4A64 65
a CAge at $4968 21

CObList::InsertBefore

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

POSITION InsertBefore(
    POSITION position,
    CObject* newElement);

Parâmetros

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

newElement
O ponteiro do objeto a ser adicionado a essa lista.

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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::InsertBefore.

Classe	Função membro
CPtrList	POSITION InsertBefore( POSITION position , void * newElement );
CStringList	POSITION InsertBefore( POSITION position , const CString& newElement ); POSITION InsertBefore( POSITION position , LPCTSTR newElement );

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
POSITION pos1, pos2;
list.AddHead(new CAge(21));
list.AddHead(new CAge(40)); // List now contains (40, 21).
if ((pos1 = list.GetTailPosition()) != NULL)
{
    pos2 = list.InsertBefore(pos1, new CAge(65));
}
#ifdef _DEBUG
   afxDump.SetDepth(1);
   afxDump << _T("InsertBefore example: ") << &list << _T("\n");
#endif      

Os resultados deste programa são os seguintes:

InsertBefore example: A CObList with 3 elements
a CAge at $4AE2 40
a CAge at $4B02 65
a CAge at $49E6 21

CObList::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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::IsEmpty.

Classe	Função membro
CPtrList	BOOL IsEmpty( ) const;
CStringList	BOOL IsEmpty( ) const;

Exemplo

Confira o exemplo de RemoveAll.

CObList::RemoveAll

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

void RemoveAll();

Comentários

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

Quando você remove elementos de um CObList, remove os ponteiros do objeto da lista. É sua responsabilidade excluir os objetos em si.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::RemoveAll.

Classe	Função membro
CPtrList	void RemoveAll( );
CStringList	void RemoveAll( );

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
CAge* pa1;
CAge* pa2;
ASSERT(list.IsEmpty()); // Yes it is.
list.AddHead(pa1 = new CAge(21));
list.AddHead(pa2 = new CAge(40)); // List now contains (40, 21).
ASSERT(!list.IsEmpty()); // No it isn't.
list.RemoveAll(); // CAges aren't destroyed.
ASSERT(list.IsEmpty()); // Yes it is.
delete pa1;     // Now delete the CAge objects.
delete pa2;

CObList::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

Quando você remove um elemento de um CObList, remove o ponteiro do objeto da lista. É sua responsabilidade excluir os objetos em si.

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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::RemoveAt.

Classe	Função membro
CPtrList	void RemoveAt( POSITION position );
CStringList	void RemoveAt( POSITION position );

Exemplo

Tenha cuidado ao remover um elemento durante uma iteração de lista. O exemplo a seguir mostra uma técnica de remoção que garante um valor de POSITION válido para GetNext.

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
POSITION pos1, pos2;
CObject* pa;

list.AddHead(new CAge(21));
list.AddHead(new CAge(40));
list.AddHead(new CAge(65)); // List now contains (65 40, 21).
for (pos1 = list.GetHeadPosition(); (pos2 = pos1) != NULL;)
{
   if (*(CAge*)list.GetNext(pos1) == CAge(40))
   {
      pa = list.GetAt(pos2); // Save the old pointer for
                             //deletion.
      list.RemoveAt(pos2);
      delete pa; // Deletion avoids memory leak.
   }
}
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("RemoveAt example: ") << &list << _T("\n");
#endif      

Os resultados deste programa são os seguintes:

RemoveAt example: A CObList with 2 elements

a CAge at $4C1E 65

a CAge at $4B22 21

CObList::RemoveHead

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

CObject* RemoveHead();

Valor de retorno

O ponteiro CObject anteriormente no cabeçalho da lista.

Comentários

Você deve 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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::RemoveHead.

Classe	Função membro
CPtrList	void* RemoveHead( );
CStringList	CString RemoveHead( );

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
CAge* pa1;
CAge* pa2;

list.AddHead(pa1 = new CAge(21));
list.AddHead(pa2 = new CAge(40)); // List now contains (40, 21).
ASSERT(*(CAge*)list.RemoveHead() == CAge(40));  // Old head
ASSERT(*(CAge*)list.GetHead() == CAge(21));  // New head
delete pa1;
delete pa2;

CObList::RemoveTail

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

CObject* RemoveTail();

Valor de retorno

Um ponteiro para o objeto que estava na parte final da lista.

Comentários

Você deve 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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::RemoveTail.

Classe	Função membro
CPtrList	void* RemoveTail( );
CStringList	CString RemoveTail( );

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
CAge* pa1;
CAge* pa2;

list.AddHead(pa1 = new CAge(21));
list.AddHead(pa2 = new CAge(40)); // List now contains (40, 21).
ASSERT(*(CAge*)list.RemoveTail() == CAge(21));  // Old tail
ASSERT(*(CAge*)list.GetTail() == CAge(40));  // New tail
delete pa1;
delete pa2; // Clean up memory.      

CObList::SetAt

Define o elemento em uma determinada posição.

void SetAt(
    POSITION pos,
    CObject* newElement);

Parâmetros

pos
O POSITION do elemento a ser definido.

newElement
O ponteiro CObject a ser gravado na lista.

Comentários

Uma variável do tipo POSITION é uma chave para a lista. Não é o mesmo que um índice, e você não pode operar em um POSITION valor por conta própria. SetAt grava o ponteiro CObject 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.

A tabela a seguir mostra outras funções de membro semelhantes a CObList::SetAt.

Classe	Função membro
CPtrList	void SetAt( POSITION pos , const CString& newElement );
CStringList	void SetAt( POSITION pos , LPCTSTR newElement );

Exemplo

Confira CObList::CObList para uma listagem da classe CAge.

CObList list;
CObject* pa;
POSITION pos;

list.AddHead(new CAge(21));
list.AddHead(new CAge(40)); // List now contains (40, 21).
if ((pos = list.GetTailPosition()) != NULL)
{
   pa = list.GetAt(pos); // Save the old pointer for 
                         //deletion.
   list.SetAt(pos, new CAge(65));  // Replace the tail 
                                     //element.
   delete pa;  // Deletion avoids memory leak.
}
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("SetAt example: ") << &list << _T("\n");
#endif      

Os resultados deste programa são os seguintes:

SetAt example: A CObList with 2 elements
a CAge at $4D98 40
a CAge at $4DB8 65

Confira também

Classe CObject
Gráfico da hierarquia
Classe CStringList
Classe CPtrList