Partilhar via


Classe CObArray

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çalho: afxcoll.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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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