Classe `CObList`

Artigo
04/03/2023

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 tail 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çalhoafxcoll.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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 sozinho. 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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 sozinho. 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

Compartilhar via

Classe CObList

Sintaxe

Membros

Construtores públicos

Métodos públicos

Comentários

Hierarquia de herança

Requisitos

CObList::AddHead

Parâmetros

Valor de Devolução

Comentários

Exemplo

CObList::AddTail

Parâmetros

Valor de Devolução

Comentários

Exemplo

CObList::CObList

Parâmetros

Comentários

Exemplo

CObList::Find

Parâmetros

Valor de Devolução

Comentários

Exemplo

CObList::FindIndex

Parâmetros

Valor de Devolução

Comentários

Exemplo

CObList::GetAt

Parâmetros

Valor de Devolução

Comentários

Exemplo

CObList::GetCount

Valor de Devolução

Exemplo

CObList::GetHead

Valor de Devolução

Comentários

Exemplo

CObList::GetHeadPosition

Valor de Devolução

Exemplo

CObList::GetNext

Parâmetros

Valor de Devolução

Comentários

Exemplo

CObList::GetPrev

Parâmetros

Valor de Devolução

Comentários

Exemplo

CObList::GetSize

Valor de Devolução

Comentários

Exemplo

CObList::GetTail

Valor de Devolução

Comentários

Exemplo

CObList::GetTailPosition

Valor de Devolução

Exemplo

CObList::InsertAfter

Parâmetros

Valor de Devolução

Exemplo

CObList::InsertBefore

Parâmetros

Valor de Devolução

Exemplo

CObList::IsEmpty

Valor de Devolução

Exemplo

Classe `CObList`

`CObList::AddHead`

`CObList::AddTail`

`CObList::CObList`

`CObList::Find`

`CObList::FindIndex`

`CObList::GetAt`

`CObList::GetCount`

`CObList::GetHead`

`CObList::GetHeadPosition`

`CObList::GetNext`

`CObList::GetPrev`

`CObList::GetSize`

`CObList::GetTail`

`CObList::GetTailPosition`

`CObList::InsertAfter`

`CObList::InsertBefore`

`CObList::IsEmpty`

`CObList::RemoveAll`

`CObList::RemoveAt`

`CObList::RemoveHead`

`CObList::RemoveTail`

`CObList::SetAt`