Classe CAtlArray

Esta classe implementa um objeto de array.

Sintaxe

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

Parâmetros

E
O tipo de dados a armazenar no array.

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

Membros

Methods

Operadores

Typedefs (definições de tipos)

Observações

CAtlArray fornece métodos para criar e gerir um array de elementos de um tipo definido pelo utilizador. Embora semelhante às matrizes C padrão, o CAtlArray objeto pode encolher e crescer dinamicamente conforme necessário. O índice do array começa sempre na posição 0, e o limite superior pode ser fixo, ou permitido expandir-se à medida que novos elementos são adicionados.

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

CAtlArray está intimamente relacionado com a classe do CArray MFC e funcionará num projeto MFC, embora sem suporte para serialização.

Para mais informações, consulte Aulas de Coleção ATL.

Requerimentos

Cabeçalho: atlcoll.h

CAtlArray::Add

Chame este método para adicionar um elemento ao objeto do array.

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

Parâmetros

elemento
O elemento a ser adicionado ao array.

Valor de retorno

Devolve o índice do elemento adicionado.

Observações

O novo elemento é adicionado à extremidade do array. Se não for fornecido elemento, adiciona-se um elemento vazio; ou seja, o array é aumentado de tamanho como se um elemento real tivesse sido adicionado. Se a operação falhar, AtlThrow é chamado com o argumento E_OUTOFMEMORY.

Example

// 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::Anexar

Chame este método para adicionar o conteúdo de um array ao final de outro.

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

Parâmetros

aSrc
O array para anexar.

Valor de retorno

Devolve o índice do primeiro elemento anexado.

Observações

Os elementos do array fornecido são adicionados ao final do array existente. Se necessário, a memória será alocada para acomodar os novos elementos.

Os arrays devem ser do mesmo tipo, e não é possível anexar um array a si próprio.

Em builds de depuração, um ATLASSERT será levantado se o CAtlArray argumento não for um array válido ou se aSrc se referir ao mesmo objeto. Em versões de release, argumentos inválidos podem levar a comportamentos imprevisíveis.

Example

// 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 este método para confirmar que o objeto array é válido.

void AssertValid() const;

Observações

Se o objeto do array não for válido, o ATLASSERT lançará uma asserção. Este método está disponível apenas se _DEBUG estiver definido.

Example

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

CAtlArray::CAtlArray

O construtor.

CAtlArray() throw();

Observações

Inicializa o objeto do array.

Example

CAtlArray<int> iArray;   

CAtlArray::~CAtlArray

O destruidor.

~CAtlArray() throw();

Observações

Liberta quaisquer recursos usados pelo objeto do array.

CAtlArray::Copiar

Chame este método para copiar os elementos de um array para outro.

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

Parâmetros

aSrc
A fonte dos elementos a copiar para um array.

Observações

Chame este método para sobrescrever elementos de um array pelos elementos de outro array. Se necessário, a memória será alocada para acomodar os novos elementos. Não é possível copiar elementos de um array para si próprio.

Se o conteúdo existente do array for mantido, use CAtlArray::Append em vez disso.

Em builds de depuração, um ATLASSERT será levantado se o objeto existente CAtlArray não for válido, ou se aSrc se referir ao mesmo objeto. Em versões de release, argumentos inválidos podem levar a comportamentos imprevisíveis.

Example

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 este método para remover quaisquer elementos vazios do array.

void FreeExtra() throw();

Observações

Quaisquer elementos vazios são removidos, mas o tamanho e o limite superior do array permanecem inalterados.

Em compilações de depuração, um ATLASSERT será ativado se o objeto CAtlArray não for válido, ou se o array exceder o seu tamanho máximo.

CAtlArray::GetAt

Chame este método para recuperar um único elemento do objeto do array.

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

Parâmetros

iElement
O valor do índice do elemento do array a devolver.

Valor de retorno

Devolve uma referência ao elemento do array requerido.

Observações

Em builds de depuração, um ATLASSERT será ativado se o iElement exceder o número de elementos no array. Em versões de release, um argumento inválido pode levar a comportamentos imprevisíveis.

Example

// 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 este método para devolver o número de elementos armazenados no array.

size_t GetCount() const throw();

Valor de retorno

Devolve o número de elementos armazenados no array.

Observações

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

Example

Veja o exemplo do CAtlArray::GetAt.

CAtlArray::GetData

Chame este método para devolver um ponteiro ao primeiro elemento do array.

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

Valor de retorno

Devolve um ponteiro para a localização de memória que armazena o primeiro elemento do array. Se não houver elementos disponíveis, NULL é devolvido.

Example

// 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 dado a usar para adicionar elementos ao array.

typedef ETraits::INARGTYPE INARGTYPE;

CAtlArray::InsertArrayAt

Chame este método para inserir um array noutro.

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

Parâmetros

iStart
O índice onde o array deve ser inserido.

paNew
O array a inserir.

Observações

Os elementos do array paNew são copiados para o objeto do array, começando no elemento iStart. Os elementos existentes do array são movidos para evitar serem sobrescritos.

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

Example

// 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 este método para inserir um novo elemento (ou múltiplas cópias de um elemento) no objeto do array.

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

Parâmetros

iElement
O índice onde o elemento ou elementos devem ser inseridos.

elemento
O valor do elemento ou elementos a inserir.

nContagem
O número de elementos a adicionar.

Observações

Insere um ou mais elementos no array, começando no índice iElement. Os elementos existentes são movidos para evitar serem sobrepostos.

Em builds de depuração, um ATLASSERT será criado se o CAtlArray objeto for inválido, o número de elementos a adicionar for zero, ou se o número combinado de elementos for demasiado grande para o array conter. Em versões de retalho, passar parâmetros inválidos pode causar resultados imprevisíveis.

Example

// 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 este método para testar se o array está vazio.

bool IsEmpty() const throw();

Valor de retorno

Retorna true se o array estiver vazio, false caso contrário.

Observações

Diz-se que o array é vazio se não contiver elementos. Portanto, mesmo que o array contenha elementos vazios, não é vazio.

Example

// 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 este operador para devolver uma referência a um elemento no array.

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

Parâmetros

iElement
O valor do índice do elemento do array a devolver.

Valor de retorno

Devolve uma referência ao elemento do array requerido.

Observações

Desempenha uma função semelhante ao CAtlArray::GetAt. Ao contrário da classe MFC CArray, este operador não pode ser usado como substituto do CAtlArray::SetAt.

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

CAtlArray::OUTARGTYPE

O tipo de dados a usar para recuperar elementos do array.

typedef ETraits::OUTARGTYPE OUTARGTYPE;

CAtlArray::RemoveAll

Chame este método para remover todos os elementos do objeto do array.

void RemoveAll() throw();

Observações

Remove todos os elementos do objeto do array.

Este método chama CAtlArray::SetCount para redimensionar o array e, subsequentemente, liberta qualquer memória alocada.

Example

Veja o exemplo de CAtlArray::IsEmpty.

CAtlArray::RemoveAt

Chame este método para remover um ou mais elementos do array.

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

Parâmetros

iElement
O índice do primeiro elemento a remover.

nContagem
O número de elementos a remover.

Observações

Remove um ou mais elementos do array. Quaisquer elementos restantes são deslocados para baixo. O limite superior é decrementado, mas a memória não é libertada até ser feita uma chamada para CAtlArray::FreeExtra .

Em builds de depuração, um ATLASSERT será levantado se o CAtlArray objeto não for válido, ou se o total combinado de iElement e nCount exceder o número total de elementos no array. Em versões de retalho, parâmetros inválidos podem causar resultados imprevisíveis.

Example

// 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 este método para definir o valor de um elemento no objeto do array.

void SetAt(size_t iElement, INARGTYPE element);

Parâmetros

iElement
O índice aponta para o elemento do array para definir.

elemento
O novo valor do elemento especificado.

Observações

Em builds de depuração, um ATLASSERT será ativado se o iElement exceder o número de elementos no array. Em builds de retalho, um parâmetro inválido pode resultar em resultados imprevisíveis.

Example

Veja o exemplo do CAtlArray::GetAt.

CAtlArray::SetCount

Chame este método para definir o tamanho do objeto do array.

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

Parâmetros

nNewSize
O tamanho necessário do array.

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

Valor de retorno

Retorna verdadeiro se o array for redimensionado com sucesso, falso caso contrário.

Observações

A matriz pode ser aumentada ou diminuída em tamanho. Se aumentados, elementos vazios extra são adicionados ao array. Se diminuído, os elementos com os maiores índices serão eliminados e a memória libertada.

Use este método para definir o tamanho do array antes de o usar. Se SetCount não for utilizada, o processo de adição de elementos — e a subsequente alocação de memória realizada — reduzirá o desempenho e fragmentar a memória.

Example

Veja o exemplo do CAtlArray::GetData.

CAtlArray::SetAtGrow

Chame este método para definir o valor de um elemento no objeto do array, expandindo o array conforme necessário.

void SetAtGrow(size_t iElement, INARGTYPE element);

Parâmetros

iElement
O índice aponta para o elemento do array para definir.

elemento
O novo valor do elemento especificado.

Observações

Substitui o valor do elemento apontado pelo índice. Se o iElement for maior do que o tamanho atual do array, o array é automaticamente aumentado usando uma chamada para CAtlArray::SetCount. Em builds de depuração, um ATLASSERT será ativado se o CAtlArray objeto não for válido. Em versões de retalho, parâmetros inválidos podem causar resultados imprevisíveis.

Example

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

Consulte também

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