Classe `CArray`

Articolo
10/12/2023

Supporta matrici simili a matrici C, ma può ridurre e aumentare dinamicamente in base alle esigenze.

Sintassi

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

Parametri

TYPE
Parametro modello che specifica il tipo di oggetti archiviati nella matrice. TYPE è un parametro restituito da CArray.

ARG_TYPE
Parametro modello che specifica il tipo di argomento utilizzato per accedere agli oggetti archiviati nella matrice. Spesso un riferimento a TYPE. ARG_TYPE è un parametro passato a CArray.

Membri

Costruttori pubblici

Nome	Descrizione
`CArray::CArray`	Costruisce una matrice vuota.

Metodi pubblici

Nome	Descrizione
`CArray::Add`	Aggiunge un elemento alla fine della matrice; se necessario, aumenta le dimensioni della matrice.
`CArray::Append`	Aggiunge un'altra matrice alla matrice; aumenta la matrice, se necessario
`CArray::Copy`	Copia nella matrice un'altra matrice; se necessario, aumenta le dimensioni della matrice.
`CArray::ElementAt`	Restituisce un riferimento temporaneo al puntatore dell'elemento nella matrice.
`CArray::FreeExtra`	Libera tutta la memoria non utilizzata oltre limite il superiore corrente.
`CArray::GetAt`	Restituisce il valore in corrispondenza di un indice specificato.
`CArray::GetCount`	Ottiene il numero di elementi nella matrice.
`CArray::GetData`	Consente l'accesso a tutti gli elementi nella matrice. Può essere `NULL`.
`CArray::GetSize`	Ottiene il numero di elementi nella matrice.
`CArray::GetUpperBound`	Restituisce il massimo indice valido.
`CArray::InsertAt`	Inserisce un elemento (o tutti gli elementi di un'altra matrice) in corrispondenza di un indice specificato.
`CArray::IsEmpty`	Determina se la matrice è vuota.
`CArray::RemoveAll`	Rimuove tutti gli elementi dalla matrice.
`CArray::RemoveAt`	Rimuove un elemento in corrispondenza di un indice specificato.
`CArray::SetAt`	Imposta il valore per un indice specificato; l'aumento di dimensioni della matrice non è consentito.
`CArray::SetAtGrow`	Imposta il valore per un indice specificato; se necessario, aumenta le dimensioni della matrice.
`CArray::SetSize`	Imposta il numero di elementi che la matrice deve contenere.

Operatori pubblici

Nome	Descrizione
`operator[]`	Imposta o ottiene l'elemento in corrispondenza dell'indice specificato.

Osservazioni:

Gli indici di matrice iniziano sempre alla posizione 0. È possibile decidere se correggere il limite superiore o abilitare l'espansione della matrice quando si aggiungono elementi oltre il limite corrente. La memoria viene allocata in modo contiguo al limite superiore, anche se alcuni elementi sono Null.

Nota

La maggior parte dei metodi che ridimensionano un CArray oggetto o aggiungono elementi da utilizzare memcpy_s per spostare gli elementi. Si tratta di un problema perché memcpy_s non è compatibile con gli oggetti che richiedono la chiamata del costruttore. Se gli elementi in CArray non sono compatibili con memcpy_s, è necessario creare una nuova CArray dimensione appropriata. È quindi necessario usare CArray::Copy e CArray::SetAt per popolare la nuova matrice perché questi metodi usano un operatore di memcpy_sassegnazione anziché .

Come per una matrice C, il tempo di accesso per un CArray elemento indicizzato è costante ed è indipendente dalle dimensioni della matrice.

Suggerimento

Prima di usare una matrice, usare SetSize per determinarne le dimensioni e allocare la necessaria memoria. Se non si usa SetSize, l'aggiunta di elementi alla matrice ne causa la riallocazione e la copia frequente. Le operazioni di riallocazione e copia frequenti sono inefficienti e possono frammentare la memoria.

Se è necessario un dump di singoli elementi in una matrice, è necessario impostare la profondità dell'oggetto CDumpContext su 1 o superiore.

Alcune funzioni membro di questa classe chiamano funzioni helper globali che devono essere personalizzate per la maggior parte degli usi della CArray classe . Vedere l'argomento Collection Class Helpers (Helper di classi di raccolta) nella sezione Macro e globals MFC.

La derivazione della classe array è simile alla derivazione list.

Per altre informazioni su come usare CArray, vedere l'articolo Raccolte.

Gerarchia di ereditarietà

CObject

CArray

Requisiti

Intestazione: afxtempl.h

`CArray::Add`

Aggiunge un nuovo elemento alla fine di una matrice, aumentando la matrice di 1.

INT_PTR Add(ARG_TYPE newElement);

Parametri

ARG_TYPE
Parametro modello che specifica il tipo di argomenti che fanno riferimento agli elementi in questa matrice.

newElement
Elemento da aggiungere a questa matrice.

Valore restituito

Indice dell'elemento aggiunto.

Osservazioni:

Se SetSize è stato usato con un nGrowBy valore maggiore di 1, è possibile allocare memoria aggiuntiva. Tuttavia, il limite superiore aumenterà solo di 1.

Esempio

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

Chiamare questa funzione membro per aggiungere il contenuto di una matrice alla fine di un'altra.

INT_PTR Append(const CArray& src);

Parametri

src
Origine degli elementi da aggiungere a una matrice.

Valore restituito

Indice del primo elemento accodato.

Osservazioni:

Le matrici devono essere dello stesso tipo.

Se necessario, Append può allocare memoria aggiuntiva per contenere gli elementi aggiunti alla matrice.

Esempio

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`

Costruisce una matrice vuota.

CArray();

Osservazioni:

La matrice aumenta di un elemento alla volta.

Esempio

CArray<CPoint, CPoint> ptArray;

`CArray::Copy`

Utilizzare questa funzione membro per copiare gli elementi di una matrice in un'altra.

void Copy(const CArray& src);

Parametri

src
Origine degli elementi da copiare in una matrice.

Osservazioni:

Chiamare questa funzione membro per sovrascrivere gli elementi di una matrice con gli elementi di un'altra matrice.

Copy non libera memoria; Tuttavia, se necessario, Copy può allocare memoria aggiuntiva per contenere gli elementi copiati nella matrice.

Esempio

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`

Restituisce un riferimento temporaneo all'elemento specificato all'interno della matrice.

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

Parametri

nIndex
Indice integer maggiore o uguale a 0 e minore o uguale al valore restituito da GetUpperBound.

Valore restituito

Riferimento a un elemento di matrice.

Osservazioni:

Viene usato per implementare l'operatore di assegnazione sul lato sinistro per le matrici.

Esempio

Vedere l'esempio per GetSize.

`CArray::FreeExtra`

Libera qualsiasi memoria aggiuntiva allocata mentre la matrice è cresciuta.

void FreeExtra();

Osservazioni:

Questa funzione non ha alcun effetto sulle dimensioni o sul limite superiore della matrice.

Esempio

Vedere l'esempio per GetData.

`CArray::GetAt`

Restituisce l'elemento della matrice in corrispondenza dell'indice specificato.

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

Parametri

TYPE
Parametro del modello che specifica il tipo degli elementi della matrice.

nIndex
Indice integer maggiore o uguale a 0 e minore o uguale al valore restituito da GetUpperBound.

Valore restituito

Elemento matrice attualmente in corrispondenza di questo indice.

Osservazioni:

Se si passa un valore negativo o un valore maggiore del valore restituito da GetUpperBound , verrà restituita un'asserzione non riuscita.

Esempio

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`

Restituisce il numero di elementi della matrice.

INT_PTR GetCount() const;

Valore restituito

Numero di elementi nella matrice.

Osservazioni:

Chiamare questo metodo per recuperare il numero di elementi nella matrice. Poiché gli indici sono in base zero, la dimensione è 1 maggiore dell'indice più grande. La chiamata a questo metodo genererà lo stesso risultato del CArray::GetSize metodo .

Esempio

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`

Usare questa funzione membro per ottenere l'accesso diretto agli elementi in una matrice.

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

Parametri

TYPE
Parametro del modello che specifica il tipo degli elementi della matrice.

Valore restituito

Puntatore a un elemento della matrice.

Osservazioni:

Se non sono disponibili elementi, GetData restituisce un valore Null.

Anche se l'accesso diretto agli elementi di una matrice consente di lavorare più rapidamente, prestare attenzione quando si chiama GetData. Gli errori che si verificano influiscono direttamente sugli elementi della matrice.

Esempio

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`

Restituisce le dimensioni della matrice.

INT_PTR GetSize() const;

Osservazioni:

Poiché gli indici sono in base zero, la dimensione è 1 maggiore dell'indice più grande. La chiamata a questo metodo genererà lo stesso risultato del CArray::GetCount metodo .

Esempio

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`

Restituisce il limite superiore corrente di questa matrice.

INT_PTR GetUpperBound() const;

Osservazioni:

Poiché gli indici di matrice sono in base zero, questa funzione restituisce un valore 1 minore di GetSize.

La condizione GetUpperBound( ) = -1 indica che la matrice non contiene elementi.

Esempio

Vedere l'esempio per CArray::GetAt.

`CArray::InsertAt`

La prima versione di InsertAt inserisce un elemento (o più copie di un elemento) in corrispondenza di un indice specificato in una matrice.

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

void InsertAt(
    INT_PTR nStartIndex,
    CArray* pNewArray);

Parametri

nIndex
Indice integer che può essere maggiore del valore restituito da GetUpperBound.

ARG_TYPE
Parametro modello che specifica il tipo di elementi in questa matrice.

newElement
Elemento da inserire in questa matrice.

nCount
Numero di volte in cui questo elemento deve essere inserito (il valore predefinito è 1).

nStartIndex
Indice integer che può essere maggiore del valore restituito da GetUpperBound.

pNewArray
Un'altra matrice che contiene elementi da aggiungere a questa matrice.

Osservazioni:

Nel processo, sposta verso l'alto (incrementando l'indice) l'elemento esistente in corrispondenza di questo indice e sposta verso l'alto tutti gli elementi sopra di esso.

La seconda versione inserisce tutti gli elementi di un'altra CArray raccolta, a partire dalla nStartIndex posizione.

La SetAt funzione, al contrario, sostituisce un elemento di matrice specificato e non sposta alcun elemento.

Esempio

// 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 la matrice è vuota.

BOOL IsEmpty() const;

Valore restituito

Diverso da zero se la matrice non contiene elementi; in caso contrario, 0.

`CArray::operator []`

Questi operatori di pedice sono un utile sostituto delle SetAt funzioni e GetAt .

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

Parametri

TYPE
Parametro modello che specifica il tipo di elementi in questa matrice.

nIndex
Indice dell'elemento a cui accedere.

Osservazioni:

Il primo operatore, chiamato per matrici che non constsono , può essere usato a destra (r-value) o a sinistra (l-value) di un'istruzione di assegnazione. Il secondo, chiamato per const le matrici, può essere usato solo a destra.

La versione debug della libreria asserisce se l'indice (a sinistra o a destra di un'istruzione di assegnazione) è fuori dai limiti.

Esempio

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`

Riloca i dati in un nuovo buffer quando la matrice deve aumentare o ridurre.

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

Parametri

pNewData
Nuovo buffer per la matrice di elementi.

pData
Matrice di elementi precedente.

nCount
Numero di elementi nella matrice precedente.

Osservazioni:

pNewData è sempre abbastanza grande da contenere tutti gli pData elementi.

L'implementazione CArray usa questo metodo per copiare i dati precedenti in un nuovo buffer quando la matrice deve aumentare o compattare (quando SetSize o FreeExtra vengono chiamati). L'implementazione predefinita copia solo i dati.

Per le matrici in cui un elemento contiene un puntatore a uno dei propri membri o un'altra struttura contiene un puntatore a uno degli elementi della matrice, i puntatori non vengono aggiornati nella copia normale. In questo caso, è possibile correggere i puntatori implementando una specializzazione di RelocateElements con i tipi pertinenti. L'utente è anche responsabile della copia dei dati.

`CArray::RemoveAll`

Rimuove tutti gli elementi dalla matrice.

void RemoveAll();

Osservazioni:

Se la matrice è già vuota, la funzione funziona ancora.

Esempio

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`

Rimuove uno o più elementi a partire da un indice specificato in una matrice.

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

Parametri

nIndex
Indice integer maggiore o uguale a 0 e minore o uguale al valore restituito da GetUpperBound.

nCount
Numero di elementi da rimuovere.

Osservazioni:

Nel processo, sposta verso il basso tutti gli elementi sopra gli elementi rimossi. Decrementa il limite superiore della matrice ma non libera memoria.

Se si tenta di rimuovere più elementi di quelli contenuti nella matrice sopra il punto di rimozione, la versione Debug della libreria asserisce.

Esempio

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`

Imposta l'elemento della matrice in corrispondenza dell'indice specificato.

void SetAt(INT_PTR nIndex, ARG_TYPE newElement);

Parametri

nIndex
Indice integer maggiore o uguale a 0 e minore o uguale al valore restituito da GetUpperBound.

ARG_TYPE
Parametro modello che specifica il tipo di argomenti utilizzati per fare riferimento agli elementi della matrice.

newElement
Valore del nuovo elemento da archiviare nella posizione specificata.

Osservazioni:

SetAt non causerà l'aumento della matrice. Usare SetAtGrow se si vuole che la matrice cresca automaticamente.

È necessario assicurarsi che il valore di indice rappresenti una posizione valida nella matrice. Se non è vincolato, la versione di debug della libreria asserisce.

Esempio

Vedere l'esempio per GetAt.

`CArray::SetAtGrow`

Imposta l'elemento della matrice in corrispondenza dell'indice specificato.

void SetAtGrow(INT_PTR nIndex, ARG_TYPE newElement);

Parametri

nIndex
Indice integer maggiore o uguale a 0.

ARG_TYPE
Parametro del modello che specifica il tipo di elementi nella matrice.

newElement
Elemento da aggiungere a questa matrice. È consentito un NULL valore.

Osservazioni:

Se necessario, la matrice aumenta automaticamente, ovvero il limite superiore viene regolato in base al nuovo elemento.

Esempio

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

Stabilisce le dimensioni di una matrice vuota o esistente; alloca memoria, se necessario.

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

Parametri

nNewSize
Nuova dimensione della matrice (numero di elementi). Deve essere maggiore o uguale a 0.

nGrowBy
Numero minimo di slot di elemento da allocare se è necessario un aumento delle dimensioni.

Osservazioni:

Se le nuove dimensioni sono inferiori alle dimensioni precedenti, la matrice viene troncata e viene rilasciata tutta la memoria inutilizzata.

Usare questa funzione per impostare le dimensioni della matrice prima di iniziare a usare la matrice. Se non si usa SetSize, l'aggiunta di elementi alla matrice ne causa la riallocazione e la copia frequente. Le operazioni di riallocazione e copia frequenti sono inefficienti e possono frammentare la memoria.

Il nGrowBy parametro influisce sull'allocazione di memoria interna durante l'aumento della matrice. L'uso non influisce mai sulle dimensioni della matrice come indicato da GetSize e GetUpperBound. Se viene usato il valore predefinito, MFC alloca la memoria in modo da evitare la frammentazione della memoria e ottimizzare l'efficienza per la maggior parte dei casi.

Esempio

Vedere l'esempio per GetData.

Vedi anche

Esempio MFC COLLECT
CObject Classe
Grafico della gerarchia
CObArray Classe
Supporti delle classi di raccolte

Condividi tramite

Classe CArray

Sintassi

Parametri

Membri

Costruttori pubblici

Metodi pubblici

Operatori pubblici

Osservazioni:

Gerarchia di ereditarietà

Requisiti

CArray::Add

Parametri

Valore restituito

Osservazioni:

Esempio

CArray::Append

Parametri

Valore restituito

Osservazioni:

Esempio

CArray::CArray

Osservazioni:

Esempio

CArray::Copy

Parametri

Osservazioni:

Esempio

CArray::ElementAt

Parametri

Valore restituito

Osservazioni:

Esempio

CArray::FreeExtra

Osservazioni:

Esempio

CArray::GetAt

Parametri

Valore restituito

Osservazioni:

Esempio

CArray::GetCount

Valore restituito

Osservazioni:

Esempio

CArray::GetData

Parametri

Valore restituito

Osservazioni:

Esempio

CArray::GetSize

Osservazioni:

Esempio

CArray::GetUpperBound

Osservazioni:

Esempio

CArray::InsertAt

Parametri

Osservazioni:

Esempio

CArray::IsEmpty

Valore restituito

CArray::operator []

Parametri

Osservazioni:

Esempio

CArray::RelocateElements

Parametri

Osservazioni:

CArray::RemoveAll

Osservazioni:

Esempio

CArray::RemoveAt

Parametri

Osservazioni:

Esempio

CArray::SetAt

Parametri

Osservazioni:

Esempio

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`