CArray Classe

Suporta arrays semelhantes a arrays C, mas que podem reduzir e crescer dinamicamente conforme necessário.

Sintaxe

template <class TYPE, class ARG_TYPE = const TYPE&>
class CArray : public CObject

Parâmetros

TYPE
Parâmetro template que especifica o tipo de objetos armazenados no array. TYPE é um parâmetro que é devolvido por CArray.

ARG_TYPE
Parâmetro template que especifica o tipo de argumento usado para aceder a objetos armazenados no array. Frequentemente uma referência a TYPE. ARG_TYPE é um parâmetro que é passado para CArray.

Membros

Construtores Públicos

Métodos Públicos

Operadores Públicos

Observações

Os índices de array começam sempre na posição 0. Podes decidir se corriges o limite superior ou se permites que o array se expanda quando adicionas elementos para além do limite atual. A memória é atribuída contíguamente ao limite superior, mesmo que alguns elementos sejam nulos.

Tal como num array C, o tempo de acesso para um CArray elemento indexado é constante e independente do tamanho do array.

Se precisar de um dump de elementos individuais num array, deve definir a profundidade do CDumpContext objeto para 1 ou maior.

Certas funções membros desta classe chamam funções auxiliares globais que têm de ser personalizadas para a maioria dos usos da CArray classe. Consulte o tópico Ajudantes de Classe de Coleção na secção de Macros e Globais do MFC.

A derivação de classes de array é semelhante à derivação por lista.

Para mais informações sobre como usar CArray, consulte o artigo Coleções.

Hierarquia de herança

CObject

CArray

Requerimentos

Cabeçalho:afxtempl.h

CArray::Add

Adiciona um novo elemento ao final de um array, aumentando o array em 1.

INT_PTR Add(ARG_TYPE newElement);

Parâmetros

ARG_TYPE
Parâmetro template que especifica o tipo de argumentos que referenciam elementos neste array.

newElement
O elemento a ser adicionado a esta matriz.

Valor de retorno

O índice do elemento adicionado.

Observações

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

Example

// example for CArray::Add
CArray<CPoint, CPoint> ptArray;

CPoint pt(10, 20);
ptArray.Add(pt);             // Element 0
ptArray.Add(CPoint(30, 40)); // Element 1

CArray::Append

Chame esta função membro para adicionar o conteúdo de um array ao final de outro.

INT_PTR Append(const CArray& src);

Parâmetros

src
Fonte dos elementos a acrescentar a um array.

Valor de retorno

O índice do primeiro elemento anexado.

Observações

Os arrays devem ser do mesmo tipo.

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

Example

CArray<CPoint, CPoint> myArray1, myArray2;

// Add elements to the second array.
myArray2.Add(CPoint(11, 22));
myArray2.Add(CPoint(12, 42));

// Add elements to the first array and also append the second array.
myArray1.Add(CPoint(1, 2));
myArray1.Append(myArray2);

CArray::CArray

Constrói um array vazio.

CArray();

Observações

A matriz cresce um elemento de cada vez.

Example

CArray<CPoint, CPoint> ptArray;

CArray::Copy

Use esta função membro para copiar os elementos de um array para outro.

void Copy(const CArray& src);

Parâmetros

src
Fonte dos elementos a copiar para um array.

Observações

Chame esta função membro para sobrescrever os elementos de um array pelos elementos de outro array.

Copy não liberta a memória; no entanto, se necessário, Copy pode alocar memória extra para acomodar os elementos copiados para o array.

Example

CArray<CPoint, CPoint> myArray1, myArray2;

// Add elements to the second array.
myArray2.Add(CPoint(11, 22));
myArray2.Add(CPoint(12, 42));

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

CArray::ElementAt

Devolve uma referência temporária ao elemento especificado dentro do array.

TYPE& ElementAt(INT_PTR nIndex);
const TYPE& ElementAt(INT_PTR nIndex) const;

Parâmetros

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

Valor de retorno

Uma referência a um elemento de array.

Observações

É usado para implementar o operador de atribuição do lado esquerdo para arrays.

Example

Veja o exemplo para GetSize.

CArray::FreeExtra

Liberta qualquer memória extra que tenha sido alocada enquanto o array foi crescido.

void FreeExtra();

Observações

Esta função não tem efeito no tamanho ou no limite superior do array.

Example

Veja o exemplo para GetData.

CArray::GetAt

Devolve o elemento do array no índice especificado.

TYPE& GetAt(INT_PTR nIndex);
const TYPE& GetAt(INT_PTR nIndex) const;

Parâmetros

TYPE
Parâmetro modelo que especifica o tipo dos elementos do array.

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

Valor de retorno

O elemento do array atualmente neste índice.

Observações

Passar um valor negativo ou um valor superior ao valor devolvido por GetUpperBound resultará numa afirmação falhada.

Example

CArray<CPoint, CPoint> myArray;
CPoint pt;

// Add elements to the array.
for (int i = 0; i < 10; i++)
{
   myArray.Add(CPoint(i, 2 * i));
}

// Modify all the points in the array.
for (int i = 0; i <= myArray.GetUpperBound(); i++)
{
   pt = myArray.GetAt(i);
   pt.x = 0;
   myArray.SetAt(i, pt);
}

CArray::GetCount

Devolve o número de elementos do array.

INT_PTR GetCount() const;

Valor de retorno

O número de itens no array.

Observações

Chame este método para recuperar o número de elementos no array. Como os índices são baseados em zero, o tamanho é 1 maior do que o maior índice. Chamar este método gerará o mesmo resultado que o CArray::GetSize método.

Example

CArray<CPoint, CPoint> myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
   myArray.Add(CPoint(i, 2 * i));

// Modify all the points in the array.
for (int i = 0; i < myArray.GetCount(); i++)
{
   CPoint &pt = myArray.ElementAt(i);
   pt.x = 0;
}

CArray::GetData

Use esta função membro para obter acesso direto aos elementos de um array.

const TYPE* GetData() const;
TYPE* GetData();

Parâmetros

TYPE
Parâmetro modelo que especifica o tipo dos elementos do array.

Valor de retorno

Um apontador para um elemento do array.

Observações

Se não houver elementos disponíveis, GetData devolve um valor nulo.

Embora o acesso direto aos elementos de um array possa ajudá-lo a trabalhar mais rapidamente, tenha cuidado ao chamar GetData; quaisquer erros que cometa afetam diretamente os elementos do seu array.

Example

CArray<CPoint, CPoint> myArray;

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

// Add elements to the array.
CPoint *pPt = (CPoint *)myArray.GetData();
for (int i = 0; i < 32; i++, pPt++)
{
   *pPt = CPoint(i, 2 * i);
}

// Only keep first 5 elements and free extra (unused) bytes.
myArray.SetSize(5, 128);
myArray.FreeExtra();

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

CArray::GetSize

Devolve o tamanho do array.

INT_PTR GetSize() const;

Observações

Como os índices são baseados em zero, o tamanho é 1 maior do que o maior índice. Chamar este método gerará o mesmo resultado que o CArray::GetCount método.

Example

CArray<CPoint, CPoint> myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
   myArray.Add(CPoint(i, 2 * i));

// Modify all the points in the array.
for (int i = 0; i < myArray.GetSize(); i++)
{
   CPoint &pt = myArray.ElementAt(i);
   pt.x = 0;
}

CArray::GetUpperBound

Devolve o limite superior atual desta matriz.

INT_PTR GetUpperBound() const;

Observações

Como os índices dos arrays são baseados em zero, esta função devolve um valor 1 menor que GetSize.

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

Example

Veja o exemplo para CArray::GetAt.

CArray::InsertAt

A primeira versão de InsertAt insere um elemento (ou múltiplas cópias de um elemento) num índice especificado num array.

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

void InsertAt(
    INT_PTR nStartIndex,
    CArray* pNewArray);

Parâmetros

nIndex
Um índice inteiro que pode ser maior do que o valor devolvido por GetUpperBound.

ARG_TYPE
Parâmetro template que especifica o tipo de elementos neste array.

newElement
O elemento a ser colocado neste arranjo.

nCount
O número de vezes que este elemento deve ser inserido (por defeito é 1).

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

pNewArray
Outro array que contém elementos a serem adicionados a este array.

Observações

No processo, 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 CArray coleção, começando pela nStartIndex posição.

A SetAt função, em contraste, substitui um elemento do array especificado e não desloca nenhum elemento.

Example

// example for CArray::InsertAt

CArray<CPoint, CPoint> ptArray;

ptArray.Add(CPoint(10, 20));         // Element 0
ptArray.Add(CPoint(30, 40));         // Element 1 (will become element 2)
ptArray.InsertAt(1, CPoint(50, 60)); // New element 1

CArray::IsEmpty

Determina se o array está vazio.

BOOL IsEmpty() const;

Valor de retorno

Não nulo se o array não contiver elementos; caso contrário, 0.

CArray::operator []

Estes operadores de subscrito são um substituto conveniente para as SetAt funções e.GetAt

TYPE& operator[](int_ptr nindex);
const TYPE& operator[](int_ptr nindex) const;

Parâmetros

TYPE
Parâmetro template que especifica o tipo de elementos neste array.

nIndex
Índice do elemento a ser acedido.

Observações

O primeiro operador, chamado para arrays que não constsão , pode ser usado tanto na direita (valor r) como na esquerda (valor l) de uma instrução de atribuição. A segunda, chamada para const arrays, pode ser usada apenas à direita.

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

Example

CArray<CPoint, CPoint> myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
{
   myArray.Add(CPoint(i, 2 * i));
}

// Modify all the points in the array.
for (int i = 0; i <= myArray.GetUpperBound(); i++)
{
   myArray[i].x = 0;
}

CArray::RelocateElements

Realoca os dados para um novo buffer quando o array deve crescer ou diminuir.

template<class TYPE, class ARG_TYPE>
AFX_INLINE void CArray<TYPE, ARG_TYPE>::RelocateElements(
    TYPE* pNewData,
    const TYPE* pData,
    INT_PTR nCount);

Parâmetros

pNewData
Um novo buffer para o array de elementos.

pData
O antigo conjunto de elementos.

nCount
Número de elementos na matriz antiga.

Observações

pNewData é sempre grande o suficiente para conter todos os pData elementos.

A CArray implementação utiliza este método para copiar os dados antigos para um novo buffer quando o array deve crescer ou diminuir (quando SetSize ou FreeExtra são chamados). A implementação padrão apenas copia os dados.

Para arrays em que um elemento contém um ponteiro para um dos seus próprios membros, ou outra estrutura contém um ponteiro para um dos elementos do array, os ponteiros não são atualizados em cópia simples. Neste caso, pode corrigir ponteiros implementando uma especialização de RelocateElements com os tipos relevantes. Também é responsável pela cópia dos dados.

CArray::RemoveAll

Remove todos os elementos deste array.

void RemoveAll();

Observações

Se o array já estiver vazio, a função continua a funcionar.

Example

CArray<CPoint, CPoint> myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
   myArray.Add(CPoint(i, 2 * i));

myArray.RemoveAll();

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

CArray::RemoveAt

Remove um ou mais elementos a partir de um índice especificado num array.

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

Parâmetros

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

nCount
O número de elementos a remover.

Observações

No processo, desloca todos os elementos acima do(s) elemento(s) removido(s). Decremente o limite superior do array, mas não liberta memória.

Se tentar remover mais elementos do que o array acima do ponto de remoção, então a versão Debug da biblioteca afirma.

Example

CArray<CPoint, CPoint> myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
{
   myArray.Add(CPoint(i, 2 * i));
}

myArray.RemoveAt(5);

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

CArray::SetAt

Define o elemento do array no índice especificado.

void SetAt(INT_PTR nIndex, ARG_TYPE newElement);

Parâmetros

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

ARG_TYPE
Parâmetro template que especifica o tipo de argumentos usados para referenciar elementos de array.

newElement
O novo valor do elemento será armazenado na posição especificada.

Observações

SetAt Não fará crescer o arrumação. Usa SetAtGrow se quiseres que o array cresça automaticamente.

Deve garantir que o valor do seu índice representa uma posição válida no array. Se estiver fora dos limites, então a versão Debug da biblioteca afirma.

Example

Veja o exemplo para GetAt.

CArray::SetAtGrow

Define o elemento do array no índice especificado.

void SetAtGrow(INT_PTR nIndex, ARG_TYPE newElement);

Parâmetros

nIndex
Um índice inteiro maior ou igual a 0.

ARG_TYPE
Parâmetro template que especifica o tipo de elementos no array.

newElement
O elemento a ser adicionado a esta matriz. Um NULL valor é permitido.

Observações

O array cresce automaticamente se necessário (ou seja, o limite superior é ajustado para acomodar o novo elemento).

Example

// example for CArray::SetAtGrow
CArray<CPoint, CPoint> ptArray;

ptArray.Add(CPoint(10, 20)); // Element 0
ptArray.Add(CPoint(30, 40)); // Element 1
// Element 2 deliberately skipped
ptArray.SetAtGrow(3, CPoint(50, 60)); // Element 3

CArray::SetSize

Estabelece o tamanho de um array vazio ou existente; aloca memória se necessário.

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

Parâmetros

nNewSize
O novo tamanho do array (número de elementos). Deve ser maior ou igual a 0.

nGrowBy
O número mínimo de espaços para elementos a alocar caso seja necessário aumentar o tamanho.

Observações

Se o novo tamanho for menor do que o antigo, então o array é truncado e toda a memória não utilizada é libertada.

Use esta função para definir o tamanho do seu array antes de começar a usar o array. Se não usar SetSize, adicionar elementos ao seu array faz com que este seja frequentemente realocado e copiado. A realocação e cópia frequentes são ineficientes e podem fragmentar a memória.

O nGrowBy parâmetro afeta a alocação interna de memória enquanto o array está a crescer. A sua utilização nunca afeta o tamanho do array conforme reportado por GetSize e GetUpperBound. Se for usado o valor por defeito, a MFC aloca a memória de forma calculada para evitar fragmentação da memória e otimizar a eficiência na maioria dos casos.

Example

Veja o exemplo para GetData.

Consulte também

Exemplo MFC COLLECT
CObject Classe
Gráfico de Hierarquia
CObArray Classe
Auxiliares da Classe de Coleção