Classe CAtlArray

Questa classe implementa un oggetto matrice.

Sintassi

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

Parametri

E
Tipo di dati da memorizzare nella matrice.

ETraits
Codice utilizzato per copiare o spostare elementi.

Membri

Metodi

Funzione	Descrizione
Aggiunta	Chiamare questo metodo per aggiungere un elemento all'oggetto matrice.
Aggiunta	Chiamare questo metodo per aggiungere il contenuto di una matrice alla fine di un'altra.
AssertValid	Chiamare questo metodo per verificare che l'oggetto matrice sia valido.
CAtlArray	Costruttore.
~CAtlArray	Distruttore.
Copia	Chiamare questo metodo per copiare gli elementi di una matrice in un'altra.
FreeExtra	Chiamare questo metodo per rimuovere tutti gli elementi vuoti dalla matrice.
GetAt	Chiamare questo metodo per recuperare un singolo elemento dall'oggetto matrice.
GetCount	Chiamare questo metodo per restituire il numero di elementi archiviati nella matrice.
GetData	Chiamare questo metodo per restituire un puntatore al primo elemento della matrice.
InsertArrayAt	Chiamare questo metodo per inserire una matrice in un'altra.
InsertAt	Chiamare questo metodo per inserire un nuovo elemento (o più copie di un elemento) nell'oggetto matrice.
IsEmpty	Chiamare questo metodo per verificare se la matrice è vuota.
RemoveAll	Chiamare questo metodo per rimuovere tutti gli elementi dall'oggetto matrice.
RemoveAt	Chiamare questo metodo per rimuovere uno o più elementi dalla matrice.
SetAt	Chiamare questo metodo per impostare il valore di un elemento nell'oggetto matrice.
SetAtGrow	Chiamare questo metodo per impostare il valore di un elemento nell'oggetto matrice, espandendo la matrice in base alle esigenze.
SetCount	Chiamare questo metodo per impostare le dimensioni dell'oggetto matrice.

Operatori

Operatore	Descrizione
operator []	Chiamare questo operatore per restituire un riferimento a un elemento nella matrice.

Typedef

Typedef	Descrizione
INARGTYPE	Tipo di dati da utilizzare per l'aggiunta di elementi alla matrice.
OUTARGTYPE	Tipo di dati da utilizzare per il recupero di elementi dalla matrice.

Osservazioni:

CAtlArray fornisce metodi per la creazione e la gestione di una matrice di elementi di un tipo definito dall'utente. Anche se simile alle matrici C standard, l'oggetto CAtlArray può ridursi e crescere in modo dinamico in base alle esigenze. L'indice della matrice inizia sempre alla posizione 0 e il limite superiore può essere fisso oppure può espandersi man mano che vengono aggiunti nuovi elementi.

Per le matrici con un numero ridotto di elementi, è possibile usare la classe ATL CSimpleArray .

CAtlArray è strettamente correlato alla classe MFC CArray e funzionerà in un progetto MFC, anche se senza supporto di serializzazione.

Per altre informazioni, vedere Classi di raccolta ATL.

Requisiti

Intestazione: atlcoll.h

CAtlArray::Add

Chiamare questo metodo per aggiungere un elemento all'oggetto matrice.

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

Parametri

Elemento
Elemento da aggiungere alla matrice.

Valore restituito

Restituisce l'indice dell'elemento aggiunto.

Osservazioni:

Il nuovo elemento viene aggiunto alla fine della matrice. Se non viene fornito alcun elemento, viene aggiunto un elemento vuoto; ovvero, la matrice viene aumentata di dimensioni come se fosse stato aggiunto un elemento reale. Se l'operazione ha esito negativo, AtlThrow viene chiamato con l'argomento E_OUTOFMEMORY.

Esempio

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

Chiamare questo metodo per aggiungere il contenuto di una matrice alla fine di un'altra.

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

Parametri

aSrc
Matrice da accodare.

Valore restituito

Restituisce l'indice del primo elemento accodato.

Osservazioni:

Gli elementi nella matrice fornita vengono aggiunti alla fine della matrice esistente. Se necessario, la memoria verrà allocata per contenere i nuovi elementi.

Le matrici devono essere dello stesso tipo e non è possibile accodare una matrice a se stessa.

Nelle compilazioni di debug, verrà generato un ATLASSERT se l'argomento CAtlArray non è una matrice valida o se aSrc fa riferimento allo stesso oggetto. Nelle build di rilascio, gli argomenti non validi possono causare un comportamento imprevedibile.

Esempio

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

Chiamare questo metodo per verificare che l'oggetto matrice sia valido.

void AssertValid() const;

Osservazioni:

Se l'oggetto matrice non è valido, ATLASSERT genererà un'asserzione. Questo metodo è disponibile solo se è definito _DEBUG.

Esempio

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

CAtlArray::CAtlArray

Costruttore.

CAtlArray() throw();

Osservazioni:

Inizializza l'oggetto matrice.

Esempio

CAtlArray<int> iArray;   

CAtlArray::~CAtlArray

Distruttore.

~CAtlArray() throw();

Osservazioni:

Libera tutte le risorse usate dall'oggetto matrice.

CAtlArray::Copy

Chiamare questo metodo per copiare gli elementi di una matrice in un'altra.

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

Parametri

aSrc
Origine degli elementi da copiare in una matrice.

Osservazioni:

Chiamare questo metodo per sovrascrivere gli elementi di una matrice con gli elementi di un'altra matrice. Se necessario, la memoria verrà allocata per contenere i nuovi elementi. Non è possibile copiare elementi di una matrice in se stesso.

Se il contenuto esistente della matrice deve essere conservato, usare invece CAtlArray::Append .

Nelle compilazioni di debug, verrà generato un ATLASSERT se l'oggetto esistente CAtlArray non è valido o se aSrc fa riferimento allo stesso oggetto. Nelle build di rilascio, gli argomenti non validi possono causare un comportamento imprevedibile.

Esempio

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

Chiamare questo metodo per rimuovere tutti gli elementi vuoti dalla matrice.

void FreeExtra() throw();

Osservazioni:

Tutti gli elementi vuoti vengono rimossi, ma le dimensioni e il limite superiore della matrice rimangono invariati.

Nelle compilazioni di debug verrà generato un elemento ATLASSERT se l'oggetto CAtlArray non è valido o se la matrice supererebbe le dimensioni massime.

CAtlArray::GetAt

Chiamare questo metodo per recuperare un singolo elemento dall'oggetto matrice.

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

Parametri

iElement
Valore di indice dell'elemento della matrice da restituire.

Valore restituito

Restituisce un riferimento all'elemento della matrice richiesto.

Osservazioni:

Nelle compilazioni di debug verrà generato un elemento ATLASSERT se iElement supera il numero di elementi nella matrice. Nelle build di rilascio, un argomento non valido può causare un comportamento imprevedibile.

Esempio

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

Chiamare questo metodo per restituire il numero di elementi archiviati nella matrice.

size_t GetCount() const throw();

Valore restituito

Restituisce il numero di elementi archiviati nella matrice.

Osservazioni:

Poiché il primo elemento della matrice si trova nella posizione 0, il valore restituito da GetCount è sempre 1 maggiore dell'indice più grande.

Esempio

Vedere l'esempio per CAtlArray::GetAt.

CAtlArray::GetData

Chiamare questo metodo per restituire un puntatore al primo elemento della matrice.

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

Valore restituito

Restituisce un puntatore alla posizione di memoria in cui è archiviato il primo elemento nella matrice. Se non sono disponibili elementi, viene restituito NULL.

Esempio

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

Tipo di dati da utilizzare per l'aggiunta di elementi alla matrice.

typedef ETraits::INARGTYPE INARGTYPE;

CAtlArray::InsertArrayAt

Chiamare questo metodo per inserire una matrice in un'altra.

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

Parametri

iStart
Indice in corrispondenza del quale deve essere inserita la matrice.

paNew
Matrice da inserire.

Osservazioni:

Gli elementi della matrice paNew vengono copiati nell'oggetto matrice, a partire dall'elemento iStart. Gli elementi della matrice esistenti vengono spostati per evitare di sovrascrivere.

Nelle compilazioni di debug, verrà generato un ATLASSERT se l'oggetto CAtlArray non è valido o se il puntatore paNew è NULL o non valido.

Esempio

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

Chiamare questo metodo per inserire un nuovo elemento (o più copie di un elemento) nell'oggetto matrice.

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

Parametri

iElement
Indice in cui inserire l'elemento o gli elementi.

Elemento
Valore dell'elemento o degli elementi da inserire.

nCount
Numero di elementi da aggiungere.

Osservazioni:

Inserisce uno o più elementi nella matrice, a partire dall'indice iElement. Gli elementi esistenti vengono spostati per evitare la sovrascrittura.

Nelle compilazioni di debug, verrà generato un ATLASSERT se l'oggetto CAtlArray non è valido, il numero di elementi da aggiungere è zero o il numero combinato di elementi è troppo grande per la matrice da contenere. Nelle build di vendita al dettaglio, il passaggio di parametri non validi può causare risultati imprevedibili.

Esempio

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

Chiamare questo metodo per verificare se la matrice è vuota.

bool IsEmpty() const throw();

Valore restituito

Restituisce true se la matrice è vuota, false in caso contrario.

Osservazioni:

La matrice viene detta vuota se non contiene elementi. Pertanto, anche se la matrice contiene elementi vuoti, non è vuota.

Esempio

// 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 []

Chiamare questo operatore per restituire un riferimento a un elemento nella matrice.

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

Parametri

iElement
Valore di indice dell'elemento della matrice da restituire.

Valore restituito

Restituisce un riferimento all'elemento della matrice richiesto.

Osservazioni:

Esegue una funzione simile a CAtlArray::GetAt. A differenza della classe MFC CArray, questo operatore non può essere usato come sostituto di CAtlArray::SetAt.

Nelle compilazioni di debug verrà generato un elemento ATLASSERT se iElement supera il numero totale di elementi nella matrice. Nelle build di vendita al dettaglio un parametro non valido può causare risultati imprevedibili.

CAtlArray::OUTARGTYPE

Tipo di dati da utilizzare per il recupero di elementi dalla matrice.

typedef ETraits::OUTARGTYPE OUTARGTYPE;

CAtlArray::RemoveAll

Chiamare questo metodo per rimuovere tutti gli elementi dall'oggetto matrice.

void RemoveAll() throw();

Osservazioni:

Rimuove tutti gli elementi dall'oggetto matrice.

Questo metodo chiama CAtlArray::SetCount per ridimensionare la matrice e successivamente libera qualsiasi memoria allocata.

Esempio

Vedere l'esempio per CAtlArray::IsEmpty.

CAtlArray::RemoveAt

Chiamare questo metodo per rimuovere uno o più elementi dalla matrice.

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

Parametri

iElement
Indice del primo elemento da rimuovere.

nCount
Numero di elementi da rimuovere.

Osservazioni:

Rimuove uno o più elementi dalla matrice. Tutti gli elementi rimanenti vengono spostati verso il basso. Il limite superiore viene decrementato, ma la memoria non viene liberata finché non viene effettuata una chiamata a CAtlArray::FreeExtra .

Nelle compilazioni di debug, verrà generato un ATLASSERT se l'oggetto CAtlArray non è valido o se il totale combinato di iElement e nCount supera il numero totale totale di elementi nella matrice. Nelle build di vendita al dettaglio, i parametri non validi possono causare risultati imprevedibili.

Esempio

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

Chiamare questo metodo per impostare il valore di un elemento nell'oggetto matrice.

void SetAt(size_t iElement, INARGTYPE element);

Parametri

iElement
Indice che punta all'elemento della matrice da impostare.

Elemento
Nuovo valore dell'elemento specificato.

Osservazioni:

Nelle compilazioni di debug verrà generato un elemento ATLASSERT se iElement supera il numero di elementi nella matrice. Nelle build di vendita al dettaglio un parametro non valido può causare risultati imprevedibili.

Esempio

Vedere l'esempio per CAtlArray::GetAt.

CAtlArray::SetCount

Chiamare questo metodo per impostare le dimensioni dell'oggetto matrice.

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

Parametri

nNewSize
Dimensione richiesta della matrice.

nGrowBy
Valore utilizzato per determinare la dimensione del buffer. Il valore -1 determina l'utilizzo di un valore calcolato internamente.

Valore restituito

Restituisce true se la matrice viene ridimensionata correttamente, false in caso contrario.

Osservazioni:

La matrice può essere aumentata o ridotta in dimensioni. Se viene aumentato, alla matrice vengono aggiunti elementi vuoti aggiuntivi. Se diminuito, gli elementi con gli indici più grandi verranno eliminati e la memoria liberata.

Usare questo metodo per impostare le dimensioni della matrice prima di usarla. Se SetCount non viene usato, il processo di aggiunta di elementi e l'allocazione di memoria successiva eseguita ridurrà le prestazioni e la memoria frammentata.

Esempio

Vedere l'esempio per CAtlArray::GetData.

CAtlArray::SetAtGrow

Chiamare questo metodo per impostare il valore di un elemento nell'oggetto matrice, espandendo la matrice in base alle esigenze.

void SetAtGrow(size_t iElement, INARGTYPE element);

Parametri

iElement
Indice che punta all'elemento della matrice da impostare.

Elemento
Nuovo valore dell'elemento specificato.

Osservazioni:

Sostituisce il valore dell'elemento a cui punta l'indice. Se iElement è maggiore della dimensione corrente della matrice, la matrice viene aumentata automaticamente usando una chiamata a CAtlArray::SetCount. Nelle compilazioni di debug, verrà generato un ATLASSERT se l'oggetto CAtlArray non è valido. Nelle build di vendita al dettaglio, i parametri non validi possono causare risultati imprevedibili.

Esempio

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

Vedi anche

Esempio di MMXSwarm
Esempio DynamicConsumer
Esempio updatePV
Esempio di marquee
Classe CArray
Cenni preliminari sulla classe