Classe CAtlArray

Artigo
06/16/2023

Essa classe implementa um objeto de matriz.

Sintaxe

template<typename E, class ETraits = CElementTraits<E>>
class CAtlArray

Parâmetros

E
O tipo de dados a serem armazenados na matriz.

ETraits
O código usado para copiar ou mover elementos.

Membros

Métodos

Função	Descrição
Add	Chame esse método para adicionar um elemento ao objeto de matriz.
Acrescenter	Chame esse método para adicionar o conteúdo de uma matriz ao final de outra.
AssertValid	Chame esse método para confirmar se o objeto de matriz é válido.
CAtlArray	O construtor .
~CAtlArray	O destruidor.
Copiar	Chame esse método para copiar os elementos de uma matriz para outra.
FreeExtra	Chame esse método para remover todos os elementos vazios da matriz.
GetAt	Chame esse método para recuperar um único elemento do objeto de matriz.
GetCount	Chame esse método para retornar o número de elementos armazenados na matriz.
GetData	Chame esse método para retornar um ponteiro para o primeiro elemento na matriz.
InsertArrayAt	Chame esse método para inserir uma matriz em outra.
InsertAt	Chame esse método para inserir um novo elemento (ou várias cópias de um elemento) no objeto de matriz.
IsEmpty	Chame esse método para testar se a matriz está vazia.
RemoveAll	Chame esse método para remover todos os elementos do objeto de matriz.
RemoveAt	Chame esse método para remover um ou mais elementos da matriz.
SetAt	Chame esse método para definir o valor de um elemento no objeto de matriz.
SetAtGrow	Chame esse método para definir o valor de um elemento no objeto de matriz, expandindo a matriz conforme necessário.
SetCount	Chame esse método para definir o tamanho do objeto de matriz.

Operadores

Operador	Descrição
`operator []`	Chame esse operador para retornar uma referência a um elemento na matriz.

Typedefs

Typedef	Descrição
INARGTYPE	O tipo de dados a ser usado para adicionar elementos à matriz.
OUTARGTYPE	O tipo de dados a ser usado para recuperar elementos da matriz.

Comentários

CAtlArray fornece métodos para criar e gerenciar uma matriz de elementos de um tipo definido pelo usuário. Embora semelhante a matrizes C padrão, o objeto CAtlArray pode reduzir e crescer dinamicamente conforme necessário. O índice de matriz sempre começa na posição 0 e o limite superior pode ser corrigido ou pode ser expandido à medida que novos elementos são adicionados.

Para matrizes com um pequeno número de elementos, a classe ATL CSimpleArray pode ser usada.

CAtlArray está intimamente relacionado à classe CArray da MFC e funcionará em um projeto MFC, embora sem suporte para serialização.

Para obter mais informações, confira Classes de Coleção da ATL.

Requisitos

Cabeçalho: atlcoll.h

CAtlArray::Add

Chame esse método para adicionar um elemento ao objeto de matriz.

size_t Add(INARGTYPE element);
size_t Add();

Parâmetros

element
O elemento a ser adicionado à matriz.

Valor de Devolução

Retorna o índice do elemento adicionado.

Comentários

O novo elemento é adicionado ao final da matriz. Se nenhum elemento for fornecido, um elemento vazio será adicionado; ou seja, a matriz é aumentada em tamanho como se um elemento real tivesse sido adicionado. Se a operação falhar, AtlThrow será chamado com o argumento E_OUTOFMEMORY.

Exemplo

// Declare an array of integers
CAtlArray<int> iArray;

iArray.Add(1);   // element 0
iArray.Add(2);   // element 1
iArray.Add();    // element 2

ATLASSERT(iArray.GetCount() == 3);

CAtlArray::Append

Chame esse método para adicionar o conteúdo de uma matriz ao final de outra.

size_t Append(const CAtlArray<E, ETraits>& aSrc);

Parâmetros

aSrc
A matriz a ser acrescentada.

Valor de Devolução

Retorna o índice do primeiro elemento acrescentado.

Comentários

Os elementos na matriz fornecida são adicionados ao final da matriz existente. Se necessário, a memória será alocada para acomodar os novos elementos.

As matrizes devem ser do mesmo tipo e não é possível acrescentar uma matriz a si mesma.

Em builds de depuração, um ATLASSERT será gerado se o argumento CAtlArray não for uma matriz válida ou se aSrc se referir ao mesmo objeto. Em builds de versão, argumentos inválidos podem levar a um comportamento imprevisível.

Exemplo

// Declare two integer arrays
CAtlArray<int> iArray1,iArray2;

iArray1.Add(1);   // element 0
iArray1.Add(2);   // element 1

iArray2.Add(3);   // element 0
iArray2.Add(4);   // element 1

// Append iArray2 to iArray1
iArray1.Append(iArray2);

ATLASSERT(iArray1.GetCount() == 4);

CAtlArray::AssertValid

Chame esse método para confirmar se o objeto de matriz é válido.

void AssertValid() const;

Comentários

Se o objeto de matriz não for válido, ATLASSERT lançará uma declaração. Esse método estará disponível somente se _DEBUG estiver definido.

Exemplo

CAtlArray<float> fArray;
// AssertValid only exists in debug builds
#ifdef _DEBUG
fArray.AssertValid();   
#endif

CAtlArray::CAtlArray

O construtor .

CAtlArray() throw();

Comentários

Inicializa o objeto de matriz.

Exemplo

CAtlArray<int> iArray;

CAtlArray::~CAtlArray

O destruidor.

~CAtlArray() throw();

Comentários

Libera todos os recursos usados pelo objeto de matriz.

CAtlArray::Copy

Chame esse método para copiar os elementos de uma matriz para outra.

void Copy(const CAtlArray<E, ETraits>& aSrc);

Parâmetros

aSrc
A origem dos elementos a serem copiados para uma matriz.

Comentários

Chame esse método para substituir elementos de uma matriz pelos elementos de outra matriz. Se necessário, a memória será alocada para acomodar os novos elementos. Não é possível copiar elementos de uma matriz para si mesma.

Se o conteúdo existente da matriz for mantido, use CAtlArray::Append.

Em builds de depuração, um ATLASSERT será gerado se o objeto CAtlArray existente não for válido ou se aSrc se referir ao mesmo objeto. Em builds de versão, argumentos inválidos podem levar a um comportamento imprevisível.

Observação

CAtlArray::Copy não dá suporte a matrizes que consistem em elementos criados com a classe CAutoPtr.

Exemplo

CAtlArray<int> iArrayS, iArrayT;

iArrayS.Add(1);
iArrayS.Add(2);

iArrayT.Add(3);
iArrayT.Add(4);

iArrayT.Copy(iArrayS);

ATLASSERT(iArrayT.GetCount() == 2);
ATLASSERT(iArrayT[0] == 1);
ATLASSERT(iArrayT[1] == 2);

CAtlArray::FreeExtra

Chame esse método para remover todos os elementos vazios da matriz.

void FreeExtra() throw();

Comentários

Todos os elementos vazios são removidos, mas o tamanho e o limite superior da matriz permanecem inalterados.

Em builds de depuração, um ATLASSERT será gerado se o objeto CAtlArray não for válido ou se a matriz exceder o tamanho máximo.

CAtlArray::GetAt

Chame esse método para recuperar um único elemento do objeto de matriz.

const E& GetAt(size_t iElement) const throw();
E& GetAt(size_t iElement) throw();

Parâmetros

iElement
O valor do índice do elemento de matriz a ser retornado.

Valor de Devolução

Retorna uma referência ao elemento exigido da matriz.

Comentários

Em builds de depuração, um ATLASSERT será gerado se o iElement exceder o número de elementos na matriz. Em builds de versão, um argumento inválido pode levar a um comportamento imprevisível.

Exemplo

// Declare an array of integers

CAtlArray<int> iMyArray;
int element;

// Add ten elements to the array
for (int i = 0; i < 10; i++)
{
   iMyArray.Add(i);
}

// Use GetAt and SetAt to modify
// every element in the array

for (size_t i = 0; i < iMyArray.GetCount(); i++)
{
   element = iMyArray.GetAt(i);
   element *= 10;
   iMyArray.SetAt(i, element);
}

CAtlArray::GetCount

Chame esse método para retornar o número de elementos armazenados na matriz.

size_t GetCount() const throw();

Valor de Devolução

Retorna o número de elementos armazenados na matriz.

Comentários

Como o primeiro elemento na matriz está na posição 0, o valor retornado por GetCount é sempre 1 maior que o maior índice.

Exemplo

Confira o exemplo de CAtlArray::GetAt.

CAtlArray::GetData

Chame esse método para retornar um ponteiro para o primeiro elemento na matriz.

E* GetData() throw();
const E* GetData() const throw();

Valor de Devolução

Retorna um ponteiro para a localização de memória que armazena o primeiro elemento na matriz. Se nenhum elemento estiver disponível, NULL será retornado.

Exemplo

// Define an array of integers
CAtlArray<int> MyArray;

// Define a pointer
int* pData;

// Allocate enough space for 32 elements
// with buffer increase to be calculated
// automatically
MyArray.SetCount(32, -1);

// Set the pointer to the first element
pData = MyArray.GetData();

// Set array values directly
for (int j = 0; j < 32; j++, pData++)
{
   *pData = j * 10;   
}

CAtlArray::INARGTYPE

O tipo de dados a ser usado para adicionar elementos à matriz.

typedef ETraits::INARGTYPE INARGTYPE;

CAtlArray::InsertArrayAt

Chame esse método para inserir uma matriz em outra.

void InsertArrayAt(size_t iStart, const CAtlArray<E, ETraits>* paNew);

Parâmetros

iStart
O índice no qual a matriz deve ser inserida.

paNew
A matriz a ser inserida.

Comentários

Os elementos da matriz paNew são copiados para o objeto de matriz, começando no elemento iStart. Os elementos de matriz existentes são movidos para evitar serem substituídos.

Em builds de depuração, um ATLASSERT será gerado se o objeto CAtlArray não for válido ou se o ponteiro paNew for NULL ou inválido.

Observação

CAtlArray::InsertArrayAt não dá suporte a matrizes que consistem em elementos criados com a classe CAutoPtr.

Exemplo

// Define two integer arrays
CAtlArray<int> iTargetArray, iSourceArray;

// Add elements to first array
for (int x = 0; x < 10; x++)
{
   iTargetArray.Add(x);
}

// Add elements to the second array
for (int x = 0; x < 10; x++)
{
   iSourceArray.Add(x * 10);
}

// Insert the Source array into the Target
// array, starting at the 5th element.
iTargetArray.InsertArrayAt(5, &iSourceArray);

CAtlArray::InsertAt

Chame esse método para inserir um novo elemento (ou várias cópias de um elemento) no objeto de matriz.

void InsertAt(size_t iElement, INARGTYPE element, size_t nCount = 1);

Parâmetros

iElement
O índice em que o elemento ou os elementos devem ser inseridos.

element
O valor do elemento ou elementos a serem inseridos.

nCount
O número de elementos a serem adicionados.

Comentários

Insere um ou mais elementos na matriz, começando no índice iElement. Os elementos existentes são movidos para evitar serem substituídos.

Em builds de depuração, um ATLASSERT será gerado se o objeto CAtlArray for inválido, o número de elementos a serem adicionados for zero ou o número combinado de elementos for muito grande para a matriz conter. Em builds de varejo, passar parâmetros inválidos pode causar resultados imprevisíveis.

Exemplo

// Declare an array of integers
CAtlArray<int> iBuffer;

// Add elements to the array
for (int b = 0; b < 10; b++)
{
   iBuffer.Add(0);
}

// Instert ten 1's into the array
// at position 5
iBuffer.InsertAt(5, 1, 10);

CAtlArray::IsEmpty

Chame esse método para testar se a matriz está vazia.

bool IsEmpty() const throw();

Valor de Devolução

Retornará true se a matriz estiver vazia. Caso contrário, retornará false.

Comentários

Diz-se que a matriz está vazia se não contiver elementos. Portanto, mesmo que a matriz contenha elementos vazios, ela não estará vazia.

Exemplo

// Define an array of chars
CAtlArray<char> cArray;

// Add an element
cArray.Add('a');

// Confirm array is not empty
ATLASSERT(!cArray.IsEmpty());

// Remove all elements
cArray.RemoveAll();

// Confirm array is empty
ATLASSERT(cArray.IsEmpty());

CAtlArray::operator []

Chame esse operador para retornar uma referência a um elemento na matriz.

E& operator[](size_t ielement) throw();
const E& operator[](size_t ielement) const throw();

Parâmetros

iElement
O valor do índice do elemento de matriz a ser retornado.

Valor de Devolução

Retorna uma referência ao elemento exigido da matriz.

Comentários

Executa uma função semelhante a CAtlArray::GetAt. Ao contrário da classe da MFC CArray, esse operador não pode ser usado como um substituto para CAtlArray::SetAt.

Em builds de depuração, um ATLASSERT será gerado se o iElement exceder o número total de elementos na matriz. Em builds de varejo, um parâmetro inválido pode causar resultados imprevisíveis.

CAtlArray::OUTARGTYPE

O tipo de dados a ser usado para recuperar elementos da matriz.

typedef ETraits::OUTARGTYPE OUTARGTYPE;

CAtlArray::RemoveAll

Chame esse método para remover todos os elementos do objeto de matriz.

void RemoveAll() throw();

Comentários

Remove todos os elementos do objeto de matriz.

Esse método chama CAtlArray::SetCount para redimensionar a matriz e, posteriormente, libera qualquer memória alocada.

Exemplo

Confira o exemplo de CAtlArray::IsEmpty.

CAtlArray::RemoveAt

Chame esse método para remover um ou mais elementos da matriz.

void RemoveAt(size_t iElement, size_t nCount = 1);

Parâmetros

iElement
O índice do primeiro elemento a ser removido.

nCount
O número de elementos a serem removidos.

Comentários

Remove um ou mais elementos da matriz. Todos os elementos restantes são deslocados para baixo. O limite superior é decrementado, mas a memória não é liberada até que uma chamada para CAtlArray::FreeExtra seja feita.

Em builds de depuração, um ATLASSERT será gerado se o objeto CAtlArray não for válido ou se o total combinado de iElement e nCount exceder o número total de elementos na matriz. Em builds de varejo, parâmetros inválidos podem causar resultados imprevisíveis.

Exemplo

// Declare an array of chars
CAtlArray<char> cMyArray;

// Add ten elements to the array
for (int a = 0; a < 10; a++)
{
   cMyArray.Add('*');
}

// Remove five elements starting with
// the element at position 1
cMyArray.RemoveAt(1, 5);

// Free memory
cMyArray.FreeExtra();

// Confirm size of array
ATLASSERT(cMyArray.GetCount() == 5);

CAtlArray::SetAt

Chame esse método para definir o valor de um elemento no objeto de matriz.

void SetAt(size_t iElement, INARGTYPE element);

Parâmetros

iElement
O índice que aponta para o elemento de matriz a ser definido.

element
O novo valor do elemento especificado.

Comentários

Em builds de depuração, um ATLASSERT será gerado se o iElement exceder o número de elementos na matriz. Em builds de varejo, um parâmetro inválido pode acarretar resultados imprevisíveis.

Exemplo

Confira o exemplo de CAtlArray::GetAt.

CAtlArray::SetCount

Chame esse método para definir o tamanho do objeto de matriz.

bool SetCount(size_t nNewSize, int nGrowBy = - 1);

Parâmetros

nNewSize
O tamanho necessário da matriz.

nGrowBy
Um valor usado para determinar o tamanho do buffer. Um valor de -1 faz com que um valor calculado internamente seja usado.

Valor de Devolução

Retornará true se a matriz for redimensionada com êxito. Caso contrário, false.

Comentários

A matriz pode ser aumentada ou reduzida de tamanho. Se aumentada, elementos vazios extras serão adicionados à matriz. Se reduzida, os elementos com os maiores índices serão excluídos e a memória será liberada.

Use esse método para definir o tamanho da matriz antes de usá-la. Se SetCount não for usado, o processo de adição de elementos – e a alocação de memória subsequente executada – reduzirá o desempenho e a memória do fragmento.

Exemplo

Confira o exemplo de CAtlArray::GetData.

CAtlArray::SetAtGrow

Chame esse método para definir o valor de um elemento no objeto de matriz, expandindo a matriz conforme necessário.

void SetAtGrow(size_t iElement, INARGTYPE element);

Parâmetros

iElement
O índice que aponta para o elemento de matriz a ser definido.

element
O novo valor do elemento especificado.

Comentários

Substitui o valor do elemento apontado pelo índice. Se iElement for maior que o tamanho atual da matriz, esta será automaticamente aumentada usando uma chamada para CAtlArray::SetCount. Em builds de depuração, um ATLASSERT será gerado se o objeto CAtlArray não for válido. Em builds de varejo, parâmetros inválidos podem causar resultados imprevisíveis.

Exemplo

// Declare an array of integers
CAtlArray<int> iGrowArray;

// Add an element
iGrowArray.Add(0);

// Add an extra element at position 19.
// This will grow the array to accommodate.
iGrowArray.SetAtGrow(19, 0);

// Confirm size of new array
ATLASSERT(iGrowArray.GetCount() == 20);

// Note: the values at position 1 to 18
// are undefined.

Confira também

MMXSwarm Sample
Exemplo de DynamicConsumer
Amostra de UpdatePV
Amostra de letreiro
Classe CArray
Visão geral da classe