Classe `CArray`

Artigo
06/16/2023

Dá suporte a matrizes semelhantes a matrizes C, mas que podem diminuir e crescer dinamicamente conforme necessário.

Sintaxe

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

Parâmetros

TYPE
Parâmetro de modelo que especifica o tipo dos objetos armazenados na matriz. TYPE é um parâmetro retornado por CArray.

ARG_TYPE
Parâmetro de modelo que especifica o tipo de argumento usado para acessar objetos armazenados na matriz. Frequentemente, uma referência a TYPE. ARG_TYPE é um parâmetro passado para CArray.

Membros

Construtores públicos

Nome	Descrição
`CArray::CArray`	Constrói uma matriz vazia.

Métodos públicos

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

Operadores públicos

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

Comentários

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ê adicionar elementos além do limite atual. A memória é alocada contiguamente ao limite superior, mesmo que alguns elementos sejam nulos.

Observação

A maioria dos métodos que redimensionam um objeto CArray ou adicionam elementos a ele usam memcpy_s para mover elementos. Isso é um problema porque memcpy_s não é compatível com nenhum objeto que exige que o construtor seja chamado. Se os itens no CArray não forem compatíveis com memcpy_s, você precisará criar um CArray com o tamanho apropriado. Em seguida, você precisará usar CArray::Copy e CArray::SetAt para preencher a nova matriz, pois esses métodos usam um operador de atribuição em vez de memcpy_s.

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

Dica

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.

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

Determinadas funções membro dessa classe chamam funções auxiliares globais que precisam ser personalizadas para a maioria dos usos da classe CArray. Consulte o tópico Auxiliares de classe de coleção na seção sobre Macros e globais do MFC.

A derivação de classe de matriz é semelhante à derivação de lista.

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

Hierarquia de herança

CObject

CArray

Requisitos

Cabeçalho: afxtempl.h

`CArray::Add`

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

INT_PTR Add(ARG_TYPE newElement);

Parâmetros

ARG_TYPE
Parâmetro de modelo que especifica o tipo dos argumentos que fazem referência a elementos nessa matriz.

newElement
O elemento 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.

Exemplo

// 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 essa função membro para adicionar o conteúdo de uma matriz ao final de outra.

INT_PTR Append(const CArray& src);

Parâmetros

src
Origem dos elementos a serem acrescentados a uma 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.

Exemplo

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 uma matriz vazia.

CArray();

Comentários

A matriz expande um elemento de cada vez.

Exemplo

CArray<CPoint, CPoint> ptArray;

`CArray::Copy`

Use essa função membro para copiar os elementos de uma matriz para outra.

void Copy(const CArray& src);

Parâmetros

src
Origem dos elementos a serem copiados para uma matriz.

Comentários

Chame essa função membro para substituir os elementos de uma matriz pelos de outra matriz.

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

Exemplo

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`

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

TYPE& ElementAt(INT_PTR nIndex);
const TYPE& ElementAt(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

Uma referência a um elemento de matriz.

Comentários

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

Exemplo

Confira o exemplo de GetSize.

`CArray::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.

Exemplo

Confira o exemplo de GetData.

`CArray::GetAt`

Retorna o elemento de matriz no índice especificado.

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

Parâmetros

TYPE
Parâmetro de modelo que especifica o tipo dos elementos de matriz.

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 matriz atualmente neste índice.

Comentários

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

Exemplo

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`

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. Chamar esse método gera o mesmo resultado que o do método CArray::GetSize.

Exemplo

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 essa função membro para obter acesso direto aos elementos em uma matriz.

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

Parâmetros

TYPE
Parâmetro de modelo que especifica o tipo dos elementos de matriz.

Valor de retorno

Um ponteiro para um elemento de matriz.

Comentários

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

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.

Exemplo

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`

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. Chamar esse método gera o mesmo resultado que o do método CArray::GetCount.

Exemplo

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`

Retorna o limite superior atual dessa matriz.

INT_PTR GetUpperBound() const;

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.

Exemplo

Confira o exemplo de CArray::GetAt.

`CArray::InsertAt`

A primeira versão de InsertAt insere um elemento (ou várias cópias de um elemento) em um índice especificado em uma matriz.

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 poderá ser maior que o valor retornado por GetUpperBound.

ARG_TYPE
Parâmetro de modelo que especifica o tipo dos elementos nessa matriz.

newElement
O elemento a ser colocado na matriz.

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

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 CArray, 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.

Exemplo

// 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 a matriz está vazia.

BOOL IsEmpty() const;

Valor de retorno

Diferente de zero se a matriz contiver elementos; caso contrário, 0.

`CArray::operator []`

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

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

Parâmetros

TYPE
Parâmetro de modelo que especifica o tipo dos elementos nessa matriz.

nIndex
Índice do elemento a ser acessado.

Comentários

O primeiro operador, chamado para matrizes que não são const, pode ser usado à direita (valor-r) ou à esquerda (valor-l) 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.

Exemplo

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 dados para um novo buffer quando a matriz 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 a matriz de elementos.

pData
A antiga matriz de elementos.

nCount
Número de elementos na matriz antiga.

Comentários

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

A implementação CArray usa esse método para copiar os dados antigos para um novo buffer quando a matriz deve crescer ou diminuir (quando SetSize ou FreeExtra é chamado). A implementação padrão apenas copia os dados.

Para matrizes em que um elemento contém um ponteiro para um dos próprios membros ou em que outra estrutura contém um ponteiro para um dos elementos da matriz, os ponteiros não são atualizados na cópia sem formatação. Nesse caso, você pode corrigir os ponteiros implementando uma especialização de RelocateElements com os tipos relevantes. Você também é responsável pela cópia de dados.

`CArray::RemoveAll`

Remove todos os elementos dessa matriz.

void RemoveAll();

Comentários

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

Exemplo

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

Exemplo

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 de matriz no índice especificado.

void SetAt(INT_PTR nIndex, ARG_TYPE newElement);

Parâmetros

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

ARG_TYPE
Parâmetro de modelo que especifica o tipo dos argumentos usados para fazer referência a elementos da matriz.

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

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.

Exemplo

Confira o exemplo de GetAt.

`CArray::SetAtGrow`

Define o elemento de matriz no índice especificado.

void SetAtGrow(INT_PTR nIndex, ARG_TYPE newElement);

Parâmetros

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

ARG_TYPE
Parâmetro de modelo que especifica o tipo dos elementos na matriz.

newElement
O elemento 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).

Exemplo

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

Use essa função para definir o tamanho da matriz antes de começar a usá-la. 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.

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 valor padrão for usado, o MFC alocará memória de maneira calculada para evitar a fragmentação de memória e otimizar a eficiência para a maioria dos casos.

Exemplo

Confira o exemplo de GetData.

Confira também

Exemplo de MFC COLLECT
Classe CObject
Gráfico da hierarquia
Classe CObArray
Auxiliares da classe de coleção

Compartilhar via

Classe CArray

Sintaxe

Parâmetros

Membros

Construtores públicos

Métodos públicos

Operadores públicos

Comentários

Hierarquia de herança

Requisitos

CArray::Add

Parâmetros

Valor de retorno

Comentários

Exemplo

CArray::Append

Parâmetros

Valor de retorno

Comentários

Exemplo

CArray::CArray

Comentários

Exemplo

CArray::Copy

Parâmetros

Comentários

Exemplo

CArray::ElementAt

Parâmetros

Valor de retorno

Comentários

Exemplo

CArray::FreeExtra

Comentários

Exemplo

CArray::GetAt

Parâmetros

Valor de retorno

Comentários

Exemplo

CArray::GetCount

Valor de retorno

Comentários

Exemplo

CArray::GetData

Parâmetros

Valor de retorno

Comentários

Exemplo

CArray::GetSize

Comentários

Exemplo

CArray::GetUpperBound

Comentários

Exemplo

CArray::InsertAt

Parâmetros

Comentários

Exemplo

CArray::IsEmpty

Valor de retorno

CArray::operator []

Parâmetros

Comentários

Exemplo

CArray::RelocateElements

Parâmetros

Comentários

CArray::RemoveAll

Comentários

Exemplo

CArray::RemoveAt

Parâmetros

Comentários

Exemplo

CArray::SetAt

Parâmetros

Comentários

Exemplo

Classe `CArray`

`CArray::Add`

`CArray::Append`

`CArray::CArray`

`CArray::Copy`

`CArray::ElementAt`

`CArray::FreeExtra`

`CArray::GetAt`

`CArray::GetCount`

`CArray::GetData`

`CArray::GetSize`

`CArray::GetUpperBound`

`CArray::InsertAt`

`CArray::IsEmpty`

`CArray::operator []`

`CArray::RelocateElements`

`CArray::RemoveAll`

`CArray::RemoveAt`

`CArray::SetAt`

`CArray::SetAtGrow`

`CArray::SetSize`