CObArray Classe

Suporta matrizes de CObject ponteiros.

Sintaxe

class CObArray : public CObject

Membros

Construtores Públicos

Métodos Públicos

Operadores Públicos

Observações

Essas matrizes de objetos são semelhantes às matrizes C, mas podem diminuir 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 adicionar elementos além do limite atual. A memória é alocada contíguamente ao limite superior, mesmo que alguns elementos sejam NULL.

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

Como em uma matriz C, o tempo de acesso para um CObArray elemento indexado é constante e é independente do tamanho da matriz.

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

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

Quando um CObArray objeto é excluído, ou quando seus elementos são removidos, apenas os CObject ponteiros são removidos, não os objetos aos quais eles fazem referência.

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.

Hierarquia de herança

CObject

CObArray

Requerimentos

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 CObject ponteiro a ser adicionado a essa matriz.

Valor de retorno

O índice do elemento adicionado.

Observações

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

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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 dada.

INT_PTR Append(const CObArray& src);

Parâmetros

src
Origem dos elementos a serem anexados à matriz.

Valor de retorno

O índice do primeiro elemento acrescentado.

Observações

As matrizes devem ser do mesmo tipo.

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

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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 dada 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.

Observações

Copy não liberta 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 ao CObArray::Copy.

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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 vazia CObject .

CObArray();

Observações

A matriz cresce um elemento de cada vez.

A tabela a seguir mostra outros construtores que são semelhantes a CObArray::CObArray.

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 ou igual a 0 e menor ou igual ao valor retornado por GetUpperBound.

Valor de retorno

Uma referência a um CObject ponteiro.

Observações

Ele é usado para implementar o operador de atribuição do lado esquerdo para matrizes. Esta é 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 ao CObArray::ElementAt.

Exemplo

Veja o exemplo para CObArray::GetSize.

CObArray::FreeExtra

Libera qualquer memória extra que foi alocada enquanto o array foi crescido.

void FreeExtra();

Observações

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

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

Exemplo

Veja o exemplo para CObArray::GetData.

CObArray::GetAt

Retorna o elemento array no índice especificado.

CObject* GetAt(INT_PTR nIndex) const;

Parâmetros

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

Valor de retorno

O CObject elemento de ponteiro atualmente neste índice.

Observações

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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 de matriz.

INT_PTR GetCount() const;

Valor de retorno

O número de itens na matriz.

Observações

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 do que o maior índice.

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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.

Observações

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

Embora o acesso direto aos elementos de uma matriz possa ajudá-lo a trabalhar mais rapidamente, tenha cuidado ao ligar GetData: quaisquer erros cometidos afetam diretamente os elementos da matriz.

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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;

Observações

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

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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

Devolve o limite superior atual desta matriz.

INT_PTR GetUpperBound() const;

Valor de retorno

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

Observações

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 ao CObArray::GetUpperBound.

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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 pode ser maior do que o valor retornado por GetUpperBound.

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

nCount
O número de vezes que este elemento deve ser inserido (o padrão é 1).

nStartIndex
Um índice inteiro que pode ser maior do que o valor retornado por GetUpperBound.

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

Observações

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

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

A SetAt função, 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 ao CObArray::InsertAt.

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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 um substituto conveniente para as SetAt funções e GetAt .

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

Observações

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

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

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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 CObject objetos.

void RemoveAll();

Observações

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

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

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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 ou igual a 0 e menor ou igual ao valor retornado por GetUpperBound.

nCount
O número de elementos a remover.

Observações

No processo, ele desloca para baixo todos os elementos acima do(s) elemento(s) removido(s). 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 afirma.

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

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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 array no índice especificado.

void SetAt(
    INT_PTR nIndex,
    CObject* newElement);

Parâmetros

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

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

Observações

SetAt não fará com que a matriz cresça. Use SetAtGrow se quiser que o array 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 Debug da biblioteca será declarada.

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

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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 array no índice especificado.

void SetAtGrow(
    INT_PTR nIndex,
    CObject* newElement);

Parâmetros

nIndex
Um índice inteiro maior ou igual a 0.

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

Observações

A matriz cresce 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 ao CObArray::SetAtGrow.

Exemplo

Consulte CObList::CObList para obter uma lista da CAge classe 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; aloca 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 ou igual a 0.

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

Observações

Se o novo tamanho for menor do que o tamanho antigo, a matriz será truncada e toda a memória não utilizada será liberada. Para maior eficiência, chame SetSize para definir o tamanho do array antes de usá-lo. Isso evita a necessidade de realocar e copiar a matriz cada vez que um item é adicionado.

O nGrowBy parâmetro 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 aumentado, todos os ponteiros recém-alocados CObject * serão definidos como NULL.

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

Exemplo

Veja o exemplo para CObArray::GetData.

Ver também

CObject Classe
Gráfico de Hierarquia
CStringArray Classe
CPtrArray Classe
CByteArray Classe
CWordArray Classe
CDWordArray Classe