Classe `CObArray`

Artigo
06/16/2023

Dá suporte a matrizes de ponteiros CObject.

Sintaxe

class CObArray : public CObject

Membros

Construtores públicos

Nome	Descrição
`CObArray::CObArray`	Constrói uma matriz vazia para ponteiros `CObject`.

Métodos públicos

Nome	Descrição
`CObArray::Add`	Inclui um elemento ao final da matriz; aumenta a matriz quando necessário.
`CObArray::Append`	Acrescenta outra matriz à matriz; aumenta a matriz quando necessário.
`CObArray::Copy`	Copia outra matriz à matriz; aumenta a matriz quando necessário.
`CObArray::ElementAt`	Retorna uma referência temporária ao ponteiro do elemento dentro da matriz.
`CObArray::FreeExtra`	Libera toda memória não usada acima do limite superior atual.
`CObArray::GetAt`	Retorna o valor a um determinado índice.
`CObArray::GetCount`	Obtém o número de elementos nesta matriz.
`CObArray::GetData`	Permite acesso aos elementos na matriz. Pode ser `NULL`.
`CObArray::GetSize`	Obtém o número de elementos nesta matriz.
`CObArray::GetUpperBound`	Retorna o maior índice válido.
`CObArray::InsertAt`	Insere um elemento (ou todos os elementos em outra matriz) em um índice especificado.
`CObArray::IsEmpty`	Determina se a matriz está vazia.
`CObArray::RemoveAll`	Remove todos os elementos dessa matriz.
`CObArray::RemoveAt`	Remove um elemento a um índice específico.
`CObArray::SetAt`	Define o valor de um determinado índice; não é permitido à matriz aumentar.
`CObArray::SetAtGrow`	Define o valor de um determinado índice; aumenta a matriz quando necessário.
`CObArray::SetSize`	Define o número de elementos a ser contido nesta matriz.

Operadores públicos

Nome	Descrição
`CObArray::operator []`	Define ou obtém o elemento no índice especificado.

Comentários

Essas matrizes de objetos são semelhantes às matrizes C, mas podem reduzir e crescer dinamicamente conforme necessário.

Os índices de matriz sempre começam na posição 0. Você pode decidir se deseja corrigir o limite superior ou permitir que a matriz se expanda quando você adiciona elementos além do limite atual. A memória é alocada contiguamente ao limite superior, mesmo que alguns elementos sejam NULL.

No Win32, o tamanho de um objeto CObArray é limitado apenas à memória disponível.

Assim como acontece com uma matriz C, o tempo de acesso de um elemento indexado CObArray é constante e é independente do tamanho da matriz.

A CObArray incorpora a macro IMPLEMENT_SERIAL para suportar serialização e despejo de seus elementos. Se uma matriz de ponteiros CObject for armazenada em um arquivo, com um operador de inserção sobrecarregado ou com a função de membro Serialize, cada elemento CObject, será, por sua vez, serializado em conjunto com seu índice de matriz.

Se você precisar de um despejo de elementos CObject individuais em uma matriz, deverá definir a profundidade do objeto CDumpContext como 1 ou maior.

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

Observação

Antes de usar uma matriz, utilize SetSize para estabelecer seu tamanho e alocar memória para ela. Se SetSize não for utilizado, incluir elementos à matriz fará com que ela seja frequentemente realocada e copiada. Realocações e cópias frequentes são ineficientes e podem fragmentar a memória.

A derivação de classe de matriz é semelhante à derivação de lista. Para obter detalhes sobre a derivação de uma classe de lista de finalidade especial, consulte o artigo Coleções.

Observação

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

Hierarquia de herança

CObject

CObArray

Requisitos

Cabeçalhoafxcoll.h:

`CObArray::Add`

Adiciona um novo elemento ao final de uma matriz, aumentando a matriz em 1.

INT_PTR Add(CObject* newElement);

Parâmetros

newElement
O ponteiro CObject a ser adicionado a essa matriz.

Valor de Devolução

O índice do elemento adicionado.

Comentários

Se SetSize tiver sido usado com um valor nGrowBy maior que 1, memória extra poderá ser alocada. No entanto, o limite superior aumentará em apenas 1.

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

Classe	Função membro
`CByteArray`	`INT_PTR Add(BYTE newElement);` `throw(CMemoryException*);`
`CDWordArray`	`INT_PTR Add(DWORD newElement);` `throw(CMemoryException*);`
`CPtrArray`	`INT_PTR Add(void* newElement);` `throw(CMemoryException*);`
`CStringArray`	`INT_PTR Add(LPCTSTR newElement); throw(CMemoryException*);` `INT_PTR Add(const CString& newElement);`
`CUIntArray`	`INT_PTR Add(UINT newElement);` `throw(CMemoryException*);`
`CWordArray`	`INT_PTR Add(WORD newElement);` `throw(CMemoryException*);`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray arr;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
#ifdef _DEBUG
   afxDump.SetDepth(1);
   afxDump << _T("Add example: ") << &arr << _T("\n");
#endif

Os resultados deste programa são os seguintes:

Add example: A CObArray with 2 elements
[0] = a CAge at $442A 21
[1] = a CAge at $4468 40

`CObArray::Append`

Chame essa função de membro para adicionar o conteúdo de outra matriz ao final da matriz fornecida.

INT_PTR Append(const CObArray& src);

Parâmetros

src
Origem dos elementos a serem acrescentados à matriz.

Valor de Devolução

O índice do primeiro elemento acrescentado.

Comentários

As matrizes devem ser do mesmo tipo.

Se necessário, Append poderá alocar memória extra para acomodar os elementos acrescentados à matriz.

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

Classe	Função membro
`CByteArray`	`INT_PTR Append(const CByteArray& src);`
`CDWordArray`	`INT_PTR Append(const CDWordArray& src);`
`CPtrArray`	`INT_PTR Append(const CPtrArray& src);`
`CStringArray`	`INT_PTR Append(const CStringArray& src);`
`CUIntArray`	`INT_PTR Append(const CUIntArray& src);`
`CWordArray`	`INT_PTR Append(const CWordArray& src);`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray myArray1, myArray2;

// Add elements to the second array.
myArray2.Add(new CAge(21));
myArray2.Add(new CAge(42));

// Add elements to the first array and also append the second array.
myArray1.Add(new CAge(3));
myArray1.Append(myArray2);

#ifdef _DEBUG
   afxDump.SetDepth(1);
   afxDump << _T("myArray1: ") << &myArray1 << _T("\n");
   afxDump << _T("myArray2: ") << &myArray2 << _T("\n");
#endif

`CObArray::Copy`

Chame essa função de membro para substituir os elementos da matriz fornecida pelos elementos de outra matriz do mesmo tipo.

void Copy(const CObArray& src);

Parâmetros

src
Origem dos elementos a serem copiados para a matriz.

Comentários

Copy não libera memória. Se necessário, Copy pode alocar memória extra para acomodar os elementos copiados para a matriz.

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

Classe	Função membro
`CByteArray`	`void Copy(const CByteArray& src);`
`CDWordArray`	`void Copy(const CDWordArray& src);`
`CPtrArray`	`void Copy(const CPtrArray& src);`
`CStringArray`	`void Copy(const CStringArray& src);`
`CUIntArray`	`void Copy(const CUIntArray& src);`
`CWordArray`	`void Copy(const CWordArray& src);`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray myArray1, myArray2;

// Add elements to the second array.
myArray2.Add(new CAge(21));
myArray2.Add(new CAge(42));

// Copy the elements from the second array to the first.
myArray1.Copy(myArray2);

#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << "myArray1: " << &myArray1 << "\n";
afxDump << "myArray2: " << &myArray2 << "\n";
#endif

`CObArray::CObArray`

Constrói uma matriz de ponteiro CObject vazia.

CObArray();

Comentários

A matriz expande um elemento de cada vez.

A tabela a seguir mostra outros construtores semelhantes a CObArray::CObArray.

Classe	Construtor
`CByteArray`	`CByteArray();`
`CDWordArray`	`CDWordArray();`
`CPtrArray`	`CPtrArray();`
`CStringArray`	`CStringArray();`
`CUIntArray`	`CUIntArray();`
`CWordArray`	`CWordArray();`

Exemplo

CObArray arr; //Array with default blocksize
CObArray* pArray = new CObArray; //Array on the heap with default blocksize

`CObArray::ElementAt`

Retorna uma referência temporária ao ponteiro do elemento dentro da matriz.

CObject*& ElementAt(INT_PTR nIndex);

Parâmetros

nIndex
Um índice inteiro maior que ou igual a 0 e menor que ou igual ao valor retornado por GetUpperBound.

Valor de Devolução

Uma referência a um ponteiro CObject.

Comentários

Ele é usado para implementar o operador de atribuição do lado esquerdo para matrizes. Essa é uma função avançada que deve ser usada apenas para implementar operadores de matriz especiais.

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

Classe	Função membro
`CByteArray`	`BYTE& ElementAt(INT_PTR nIndex);`
`CDWordArray`	`DWORD& ElementAt(INT_PTR nIndex);`
`CPtrArray`	`void*& ElementAt(INT_PTR nIndex);`
`CStringArray`	`CString& ElementAt(INT_PTR nIndex);`
`CUIntArray`	`UINT& ElementAt(INT_PTR nIndex);`
`CWordArray`	`WORD& ElementAt(INT_PTR nIndex);`

Exemplo

Confira o exemplo de CObArray::GetSize.

`CObArray::FreeExtra`

Libera qualquer memória extra alocada enquanto a matriz foi expandida.

void FreeExtra();

Comentários

Essa função não tem efeito sobre o tamanho ou o limite superior da matriz.

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

Classe	Função membro
`CByteArray`	`void FreeExtra();`
`CDWordArray`	`void FreeExtra();`
`CPtrArray`	`void FreeExtra();`
`CStringArray`	`void FreeExtra();`
`CUIntArray`	`void FreeExtra();`
`CWordArray`	`void FreeExtra();`

Exemplo

Confira o exemplo de CObArray::GetData.

`CObArray::GetAt`

Retorna o elemento de matriz no índice especificado.

CObject* GetAt(INT_PTR nIndex) const;

Parâmetros

nIndex
Um índice inteiro maior que ou igual a 0 e menor que ou igual ao valor retornado por GetUpperBound.

Valor de Devolução

O elemento de ponteiro CObject atualmente neste índice.

Comentários

Observação

Passar um valor negativo ou um valor maior do que o valor retornado por GetUpperBound resultará em uma declaração com falha.

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

Classe	Função membro
`CByteArray`	`BYTE GetAt(INT_PTR nIndex) const;`
`CDWordArray`	`DWORD GetAt(INT_PTR nIndex) const;`
`CPtrArray`	`void* GetAt(INT_PTR nIndex) const;`
`CStringArray`	`const CString& GetAt(INT_PTR nIndex) const;`
`CUIntArray`	`UINT GetAt(INT_PTR nIndex) const;`
`CWordArray`	`WORD GetAt(INT_PTR nIndex) const;`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray arr;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
ASSERT(*(CAge*) arr.GetAt(0) == CAge(21));

`CObArray::GetCount`

Retorna o número de elementos da matriz.

INT_PTR GetCount() const;

Valor de Devolução

O número de itens na matriz.

Comentários

Chame esse método para recuperar o número de elementos na matriz. Como os índices são baseados em zero, o tamanho é 1 maior que o maior índice.

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

Classe	Função membro
`CByteArray`	`INT_PTR GetCount() const;`
`CDWordArray`	`INT_PTR GetCount() const;`
`CPtrArray`	`INT_PTR GetCount() const;`
`CStringArray`	`INT_PTR GetCount() const;`
`CUIntArray`	`INT_PTR GetCount() const;`
`CWordArray`	`INT_PTR GetCount() const;`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
   myArray.Add(new CAge(i));

// Add 100 to all the elements of the array.
for (int i = 0; i < myArray.GetCount(); i++)
{
   CAge*& pAge = (CAge*&) myArray.ElementAt(i);
   delete pAge;
   pAge = new CAge(100 + i);
}

`CObArray::GetData`

Use essa função de membro para obter acesso direto aos elementos na matriz.

const CObject** GetData() const;

CObject** GetData();

Valor de Devolução

Um ponteiro para a matriz de CObject ponteiros.

Comentários

Se nenhum elemento estiver disponível, GetData retornará um valor NULL.

Embora o acesso direto aos elementos de uma matriz possa ajudar você a trabalhar mais rapidamente, tenha cuidado ao chamar GetData. Qualquer erro afetará diretamente os elementos da matriz.

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

Classe	Função membro
CByteArray	`const BYTE* GetData() const; BYTE* GetData();`
CDWordArray	`const DWORD* GetData() const; DWORD* GetData();`
CPtrArray	`const void GetData() const; void GetData();`
CStringArray	`const CString* GetData() const; CString* GetData();`
CUIntArray	`const UINT* GetData() const; UINT* GetData();`
CWordArray	`const WORD* GetData() const; WORD* GetData();`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray myArray;

// Allocate memory for at least 32 elements.
myArray.SetSize(32, 128);

// Add elements to the array.
CAge** ppAge = (CAge * *)myArray.GetData();
for (int i = 0; i < 32; i++, ppAge++)
   * ppAge = new CAge(i);

// Only keep first 5 elements and free extra (unused) bytes.
for (int i = 5; i < myArray.GetCount(); i++)
{
   delete myArray[i]; // free objects before resetting array size.         
}
myArray.SetSize(5, 128);
myArray.FreeExtra(); // only frees pointers.

#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("myArray: ") << &myArray << _T("\n");
#endif

`CObArray::GetSize`

Retorna o tamanho da matriz.

INT_PTR GetSize() const;

Comentários

Como os índices são baseados em zero, o tamanho é 1 maior que o maior índice.

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

Classe	Função membro
`CByteArray`	`INT_PTR GetSize() const;`
`CDWordArray`	`INT_PTR GetSize() const;`
`CPtrArray`	`INT_PTR GetSize() const;`
`CStringArray`	`INT_PTR GetSize() const;`
`CUIntArray`	`INT_PTR GetSize() const;`
`CWordArray`	`INT_PTR GetSize() const;`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
   myArray.Add(new CAge(i));

// Add 100 to all the elements of the array.
for (int i = 0; i < myArray.GetSize(); i++)
{
   CAge*& pAge = (CAge * &)myArray.ElementAt(i);
   delete pAge;
   pAge = new CAge(100 + i);
}

#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("myArray: ") << &myArray << _T("\n");
#endif

`CObArray::GetUpperBound`

Retorna o limite superior atual dessa matriz.

INT_PTR GetUpperBound() const;

Valor de Devolução

O índice do limite superior (baseado em zero).

Comentários

Como os índices de matriz são baseados em zero, essa função retorna um valor 1 menor que GetSize.

A condição GetUpperBound() = -1 indica que a matriz não contém elementos.

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

Classe	Função membro
`CByteArray`	`INT_PTR GetUpperBound() const;`
`CDWordArray`	`INT_PTR GetUpperBound() const;`
`CPtrArray`	`INT_PTR GetUpperBound() const;`
`CStringArray`	`INT_PTR GetUpperBound() const;`
`CUIntArray`	`INT_PTR GetUpperBound() const;`
`CWordArray`	`INT_PTR GetUpperBound() const;`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray arr;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
ASSERT(arr.GetUpperBound() == 1); // Largest index

`CObArray::InsertAt`

Insere um elemento (ou todos os elementos em outra matriz) em um índice especificado.

void InsertAt(
    INT_PTR nIndex,
    CObject* newElement,
    INT_PTR nCount = 1);

void InsertAt(
    INT_PTR nStartIndex,
    CObArray* pNewArray);

Parâmetros

nIndex
Um índice inteiro que poderá ser maior que o valor retornado por GetUpperBound.

newElement
O ponteiro CObject a ser colocado nesta matriz. Um newElement de valor NULL é permitido.

nCount
O número de vezes que esse elemento deverá ser inserido (o padrão é 1).

nStartIndex
Um índice inteiro que poderá ser maior que o valor retornado por GetUpperBound.

pNewArray
Outra matriz que contém elementos a serem adicionados a essa matriz.

Comentários

A primeira versão de InsertAt insere um elemento (ou várias cópias de um elemento) em um índice especificado em uma matriz. No processo, ela desloca para cima (incrementando o índice) o elemento existente nesse índice e desloca todos os elementos acima dele.

A segunda versão insere todos os elementos de outra coleção CObArray, começando na posição nStartIndex.

A função SetAt, por outro lado, substitui um elemento de matriz especificado e não desloca nenhum elemento.

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

Classe	Função membro
`CByteArray`	`void InsertAt(INT_PTR nIndex, BYTE newElement, int nCount = 1);` `throw(CMemoryException);` `void InsertAt(INT_PTR nStartIndex, CByteArray pNewArray);` `throw(CMemoryException*);`
`CDWordArray`	`void InsertAt(INT_PTR nIndex, DWORD newElement, int nCount = 1);` `throw(CMemoryException);` `void InsertAt(INT_PTR nStartIndex, CDWordArray pNewArray);` `throw(CMemoryException*);`
`CPtrArray`	`void InsertAt(INT_PTR nIndex, void* newElement, int nCount = 1);` `throw(CMemoryException);` `void InsertAt(INT_PTR nStartIndex, CPtrArray pNewArray);` `throw(CMemoryException*);`
`CStringArray`	`void InsertAt(INT_PTR nIndex, LPCTSTR newElement, int nCount = 1);` `throw(CMemoryException);` `void InsertAt(INT_PTR nStartIndex, CStringArray pNewArray);` `throw(CMemoryException*);`
`CUIntArray`	`void InsertAt(INT_PTR nIndex, UINT newElement, int nCount = 1);` `throw(CMemoryException);` `void InsertAt(INT_PTR nStartIndex, CUIntArray pNewArray);` `throw(CMemoryException*);`
`CWordArray`	`void InsertAt(INT_PTR nIndex, WORD newElement, int nCount = 1);` `throw(CMemoryException);` `void InsertAt(INT_PTR nStartIndex, CWordArray pNewArray);` `throw(CMemoryException*);`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray arr;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1 (will become 2).
arr.InsertAt(1, new CAge(30));  // New element 1
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("InsertAt example: ") << &arr << _T("\n");
#endif

Os resultados deste programa são os seguintes:

InsertAt example: A CObArray with 3 elements
[0] = a CAge at $45C8 21
[1] = a CAge at $4646 30
[2] = a CAge at $4606 40

`CObArray::IsEmpty`

Determina se a matriz está vazia.

BOOL IsEmpty() const;

Valor de Devolução

Diferente de zero se a matriz estiver vazia; caso contrário, 0.

`CObArray::operator [ ]`

Esses operadores subscritos são substitutos convenientes para as funções SetAt e GetAt.

CObject*& operator[](int_ptr nindex);
CObject* operator[](int_ptr nindex) const;

Comentários

O primeiro operador, chamado para matrizes que não são const, pode ser usado à direita (r-value) ou à esquerda (l-value) de uma instrução de atribuição. O segundo, chamado para matrizes const, pode ser usado somente à direita.

A versão de Depuração da biblioteca declarará se o subscrito (no lado esquerdo ou direito de uma instrução de atribuição) estiver fora dos limites.

A tabela a seguir mostra outros operadores semelhantes a CObArray::operator [].

Classe	Operador
`CByteArray`	`BYTE& operator [](INT_PTR nindex);` `BYTE operator [](INT_PTR nindex) const;`
`CDWordArray`	`DWORD& operator [](INT_PTR nindex);` `DWORD operator [](INT_PTR nindex) const;`
`CPtrArray`	`void& operator [](INT_PTR nindex);` `void operator [](INT_PTR nindex) const;`
`CStringArray`	`CString& operator [](INT_PTR nindex);` `CString operator [](INT_PTR nindex) const;`
`CUIntArray`	`UINT& operator [](INT_PTR nindex);` `UINT operator [](INT_PTR nindex) const;`
`CWordArray`	`WORD& operator [](INT_PTR nindex);` `WORD operator [](INT_PTR nindex) const;`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray arr;
CAge* pa;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
pa = (CAge*)arr[0]; // Get element 0
ASSERT(*pa == CAge(21)); // Get element 0
arr[0] = new CAge(30); // Replace element 0
delete pa;
ASSERT(*(CAge*)arr[0] == CAge(30)); // Get new element 0

`CObArray::RemoveAll`

Remove todos os ponteiros dessa matriz, mas não exclui os objetos CObject.

void RemoveAll();

Comentários

Se a matriz já estiver vazia, a função ainda funcionará.

A função RemoveAll libera toda a memória usada para o armazenamento de ponteiro.

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

Classe	Função membro
`CByteArray`	`void RemoveAll();`
`CDWordArray`	`void RemoveAll();`
`CPtrArray`	`void RemoveAll();`
`CStringArray`	`void RemoveAll();`
`CUIntArray`	`void RemoveAll();`
`CWordArray`	`void RemoveAll();`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray arr;
CAge* pa1;
CAge* pa2;

arr.Add(pa1 = new CAge(21)); // Element 0
arr.Add(pa2 = new CAge(40)); // Element 1
ASSERT(arr.GetSize() == 2);
arr.RemoveAll(); // Pointers removed but objects not deleted.
ASSERT(arr.GetSize() == 0);
delete pa1;
delete pa2;  // Cleans up memory.

`CObArray::RemoveAt`

Remove um ou mais elementos começando em um índice especificado em uma matriz.

void RemoveAt(
    INT_PTR nIndex,
    INT_PTR nCount = 1);

Parâmetros

nIndex
Um índice inteiro maior que ou igual a 0 e menor que ou igual ao valor retornado por GetUpperBound.

nCount
O número de elementos a serem removidos.

Comentários

No processo, ele desloca todos os elementos acima dos elementos removidos. Ele diminui o limite superior da matriz, mas não libera memória.

Se você tentar remover mais elementos do que os contidos na matriz acima do ponto de remoção, a versão de depuração da biblioteca será declarada.

A função RemoveAt remove o ponteiro CObject da matriz, mas não exclui o objeto em si.

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

Classe	Função membro
`CByteArray`	`void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);`
`CDWordArray`	`void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);`
CPtrArray	`void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);`
`CStringArray`	`void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);`
`CUIntArray`	`void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);`
`CWordArray`	`void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray arr;
CObject* pa;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
if ((pa = arr.GetAt(0)) != NULL)
{
   arr.RemoveAt(0);  // Element 1 moves to 0.
   delete pa; // Delete the original element at 0.
}
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("RemoveAt example: ") << &arr << _T("\n");
#endif

Os resultados deste programa são os seguintes:

RemoveAt example: A CObArray with 1 elements
[0] = a CAge at $4606 40

`CObArray::SetAt`

Define o elemento de matriz no índice especificado.

void SetAt(
    INT_PTR nIndex,
    CObject* newElement);

Parâmetros

nIndex
Um índice inteiro maior que ou igual a 0 e menor que ou igual ao valor retornado por GetUpperBound.

newElement
O ponteiro do objeto a ser inserido nesta matriz. Um valor NULL é permitido.

Comentários

SetAt não fará com que a matriz cresça. Use SetAtGrow se quiser que a matriz cresça automaticamente.

Verifique se o valor do índice representa uma posição válida na matriz. Se estiver fora dos limites, a versão de depuração da biblioteca será declarada.

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

Classe	Função membro
`CByteArray`	`void SetAt(INT_PTR nIndex, BYTE newElement);`
`CDWordArray`	`void SetAt(INT_PTR nIndex, DWORD newElement);`
`CPtrArray`	`void SetAt(INT_PTR nIndex, void* newElement);`
`CStringArray`	`void SetAt(INT_PTR nIndex, LPCTSTR newElement);`
`CUIntArray`	`void SetAt(INT_PTR nIndex, UINT newElement);`
`CWordArray`	`void SetAt(INT_PTR nIndex, WORD newElement);`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray arr;
CObject* pa;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
if ((pa = arr.GetAt(0)) != NULL)
{
   arr.SetAt(0, new CAge(30));  // Replace element 0.
   delete pa; // Delete the original element at 0.
}
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("SetAt example: ") << &arr << _T("\n");
#endif

Os resultados deste programa são os seguintes:

SetAt example: A CObArray with 2 elements
[0] = a CAge at $47E0 30
[1] = a CAge at $47A0 40

`CObArray::SetAtGrow`

Define o elemento de matriz no índice especificado.

void SetAtGrow(
    INT_PTR nIndex,
    CObject* newElement);

Parâmetros

nIndex
Um índice inteiro que é maior ou igual a 0.

newElement
O ponteiro do objeto a ser adicionado a essa matriz. Um valor NULL é permitido.

Comentários

A matriz crescerá automaticamente, se necessário (ou seja, o limite superior é ajustado para acomodar o novo elemento).

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

Classe	Função membro
`CByteArray`	`void SetAtGrow(INT_PTR nIndex, BYTE newElement);` `throw(CMemoryException*);`
`CDWordArray`	`void SetAtGrow(INT_PTR nIndex, DWORD newElement);` `throw(CMemoryException*);`
`CPtrArray`	`void SetAtGrow(INT_PTR nIndex, void* newElement);` `throw( CMemoryException*);`
`CStringArray`	`void SetAtGrow(INT_PTR nIndex, LPCTSTR newElement);` `throw(CMemoryException*);`
`CUIntArray`	`void SetAtGrow(INT_PTR nIndex, UINT newElement);` `throw(CMemoryException*);`
`CWordArray`	`void SetAtGrow(INT_PTR nIndex, WORD newElement);` `throw(CMemoryException*);`

Exemplo

Consulte CObList::CObList para obter uma listagem da classe CAge usada em todos os exemplos de coleção.

CObArray arr;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
arr.SetAtGrow(3, new CAge(65)); // Element 2 deliberately
                                      // skipped.
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("SetAtGrow example: ") << &arr << _T("\n");
#endif

Os resultados deste programa são os seguintes:

SetAtGrow example: A CObArray with 4 elements
[0] = a CAge at $47C0 21
[1] = a CAge at $4800 40
[2] = NULL
[3] = a CAge at $4840 65

`CObArray::SetSize`

Estabelece o tamanho de uma matriz vazia ou existente; alocará memória, se necessário.

void SetSize(
    INT_PTR nNewSize,
    INT_PTR nGrowBy = -1);

Parâmetros

nNewSize
O novo tamanho da matriz (número de elementos). Deve ser maior que ou igual a 0.

nGrowBy
O número mínimo de slots de elemento a serem alocados se um aumento de tamanho for necessário.

Comentários

Se o novo tamanho for menor que o tamanho antigo, a matriz será truncada, e toda a memória não utilizada será liberada. Para obter eficiência, chame SetSize para definir o tamanho da matriz antes de usá-la. Isso impede a necessidade de realocar e copiar a matriz sempre que um item é adicionado.

O parâmetro nGrowBy afeta a alocação de memória interna enquanto a matriz está crescendo. Seu uso nunca afeta o tamanho da matriz conforme relatado por GetSize e GetUpperBound.

Se o tamanho da matriz tiver crescido, todos os ponteiros recém-alocados CObject * serão definidos como NULL.

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

Classe	Função membro
`CByteArray`	`void SetSize(INT_PTR nNewSize, int nGrowBy = -1);` `throw(CMemoryException*);`
`CDWordArray`	`void SetSize(INT_PTR nNewSize, int nGrowBy = -1);` `throw(CMemoryException*);`
`CPtrArray`	`void SetSize(INT_PTR nNewSize, int nGrowBy = -1);` `throw(CMemoryException*);`
`CStringArray`	`void SetSize(INT_PTR nNewSize, int nGrowBy = -1);` `throw(CMemoryException*);`
`CUIntArray`	`void SetSize(INT_PTR nNewSize, int nGrowBy = -1);` `throw(CMemoryException*);`
`CWordArray`	`void SetSize(INT_PTR nNewSize, int nGrowBy = -1);` `throw(CMemoryException*);`

Exemplo

Confira o exemplo de CObArray::GetData.

Confira também

Classe CObject
Gráfico da hierarquia
Classe CStringArray
Classe CPtrArray
Classe CByteArray
Classe CWordArray
Classe CDWordArray

Compartilhar via

Classe CObArray

Sintaxe

Membros

Construtores públicos

Métodos públicos

Operadores públicos

Comentários

Hierarquia de herança

Requisitos

CObArray::Add

Parâmetros

Valor de Devolução

Comentários

Exemplo

CObArray::Append

Parâmetros

Valor de Devolução

Comentários

Exemplo

CObArray::Copy

Parâmetros

Comentários

Exemplo

CObArray::CObArray

Comentários

Exemplo

CObArray::ElementAt

Parâmetros

Valor de Devolução

Comentários

Exemplo

CObArray::FreeExtra

Comentários

Exemplo

CObArray::GetAt

Parâmetros

Valor de Devolução

Comentários

Exemplo

CObArray::GetCount

Valor de Devolução

Comentários

Exemplo

CObArray::GetData

Valor de Devolução

Comentários

Exemplo

CObArray::GetSize

Comentários

Exemplo

CObArray::GetUpperBound

Valor de Devolução

Comentários

Exemplo

CObArray::InsertAt

Parâmetros

Comentários

Exemplo

CObArray::IsEmpty

Valor de Devolução

CObArray::operator [ ]

Comentários

Exemplo

CObArray::RemoveAll

Comentários

Exemplo

CObArray::RemoveAt

Parâmetros

Comentários

Exemplo

CObArray::SetAt

Parâmetros

Comentários

Exemplo

CObArray::SetAtGrow

Parâmetros

Comentários

Exemplo

CObArray::SetSize

Classe `CObArray`

`CObArray::Add`

`CObArray::Append`

`CObArray::Copy`

`CObArray::CObArray`

`CObArray::ElementAt`

`CObArray::FreeExtra`

`CObArray::GetAt`

`CObArray::GetCount`

`CObArray::GetData`

`CObArray::GetSize`

`CObArray::GetUpperBound`

`CObArray::InsertAt`

`CObArray::IsEmpty`

`CObArray::operator [ ]`

`CObArray::RemoveAll`

`CObArray::RemoveAt`

`CObArray::SetAt`

`CObArray::SetAtGrow`

`CObArray::SetSize`