La classe `CArray`

Article
06/16/2023

Prend en charge les tableaux qui sont comme des tableaux C, mais peuvent réduire et croître dynamiquement selon les besoins.

Syntaxe

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

Paramètres

TYPE
Paramètre de modèle qui spécifie le type d’objets stockés dans le tableau. TYPE est un paramètre retourné par CArray.

ARG_TYPE
Paramètre de modèle qui spécifie le type d’argument utilisé pour accéder aux objets stockés dans le tableau. Souvent une référence à TYPE. ARG_TYPE est un paramètre passé à CArray.

Membres

Constructeurs publics

Nom	Description
`CArray::CArray`	Construit un tableau vide.

Méthodes publiques

Nom	Description
`CArray::Add`	Ajoute un élément à la fin du tableau ; étend le tableau si nécessaire.
`CArray::Append`	Ajoute un autre tableau au tableau ; augmente le tableau si nécessaire
`CArray::Copy`	Copie un autre tableau dans le tableau ; étend le tableau si nécessaire.
`CArray::ElementAt`	Retourne une référence temporaire au pointeur d'élément dans le tableau.
`CArray::FreeExtra`	Libère toute la mémoire inutilisée au-dessus de la limite supérieure actuelle.
`CArray::GetAt`	Retourne la valeur à un index donné.
`CArray::GetCount`	Obtient le nombre d'éléments dans ce tableau.
`CArray::GetData`	Autorise l'accès aux éléments du tableau. Peut être `NULL`.
`CArray::GetSize`	Obtient le nombre d'éléments dans ce tableau.
`CArray::GetUpperBound`	Retourne le plus grand index valide.
`CArray::InsertAt`	Insère un élément (ou tous les éléments d'un autre tableau) à un index spécifique.
`CArray::IsEmpty`	Détermine si le tableau est vide.
`CArray::RemoveAll`	Supprime tous les éléments de ce tableau.
`CArray::RemoveAt`	Supprime un élément à un index spécifique.
`CArray::SetAt`	Définit la valeur d'un index donné. Le tableau n'est pas autorisé à s'étendre.
`CArray::SetAtGrow`	Définit la valeur d'un index donné. Le tableau est étendu si nécessaire.
`CArray::SetSize`	Définit le nombre d'éléments que ce tableau doit contenir.

Opérateurs publics

Nom	Description
`operator[]`	Définit ou obtient l'élément au niveau de l'index spécifié.

Notes

Les index de tableau commencent toujours à la position 0. Vous pouvez décider de corriger la limite supérieure ou d’activer le tableau à développer lorsque vous ajoutez des éléments au-delà de la limite actuelle. La mémoire est allouée contiguëment à la limite supérieure, même si certains éléments sont null.

Remarque

La plupart des méthodes qui redimensionnent un CArray objet ou ajoutent des éléments à son utilisation memcpy_s pour déplacer des éléments. Il s’agit d’un problème, car memcpy_s il n’est pas compatible avec les objets qui nécessitent l’appel du constructeur. Si les éléments du fichier CArray ne sont pas compatibles avec memcpy_s, vous devez créer une nouvelle CArray taille appropriée. Vous devez ensuite utiliser CArray::Copy et CArray::SetAt remplir le nouveau tableau, car ces méthodes utilisent un opérateur d’affectation au lieu de memcpy_s.

Comme avec un tableau C, l’heure d’accès d’un CArray élément indexé est constante et est indépendante de la taille du tableau.

Conseil

Avant d'utiliser un tableau, utilisez SetSize pour définir sa taille et lui allouer la mémoire nécessaire. Si vous n'utilisez pas SetSize, l'ajout d'éléments à votre tableau risque d'entraîner de fréquentes opérations de réallocation et de copie de ce dernier. Les opérations fréquentes de réallocation et de copie sont inefficaces et peuvent fragmenter la mémoire.

Si vous avez besoin d’un vidage d’éléments individuels dans un tableau, vous devez définir la profondeur de l’objet CDumpContext sur 1 ou plus.

Certaines fonctions membres de cette classe appellent des fonctions d’assistance globales qui doivent être personnalisées pour la plupart des utilisations de la CArray classe. Consultez les helpers de la collection de rubriques dans la section Macros et globals MFC.

La dérivation de classe array est semblable à la dérivation de liste.

Pour plus d’informations sur l’utilisation CArray, consultez l’article Collections.

Hiérarchie d'héritage

CObject

CArray

Spécifications

En-tête : afxtempl.h

`CArray::Add`

Ajoute un nouvel élément à la fin d’un tableau, augmentant le tableau de 1.

INT_PTR Add(ARG_TYPE newElement);

Paramètres

ARG_TYPE
Paramètre de modèle spécifiant le type d’arguments référençant des éléments dans ce tableau.

newElement
Élément à ajouter à ce tableau.

Valeur de retour

Index de l’élément ajouté.

Notes

Si SetSize elle a été utilisée avec une nGrowBy valeur supérieure à 1, une mémoire supplémentaire peut être allouée. Toutefois, la limite supérieure augmente de seulement 1.

Exemple

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

Appelez cette fonction membre pour ajouter le contenu d’un tableau à la fin d’une autre.

INT_PTR Append(const CArray& src);

Paramètres

src
Source des éléments à ajouter à un tableau.

Valeur de retour

Index du premier élément ajouté.

Notes

Les tableaux doivent être du même type.

Si nécessaire, Append peut allouer de la mémoire supplémentaire pour prendre en charge les éléments ajoutés au tableau.

Exemple

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`

Construit un tableau vide.

CArray();

Notes

Le tableau augmente un élément à la fois.

Exemple

CArray<CPoint, CPoint> ptArray;

`CArray::Copy`

Utilisez cette fonction membre pour copier les éléments d’un tableau vers un autre.

void Copy(const CArray& src);

Paramètres

src
Source des éléments à copier dans un tableau.

Notes

Appelez cette fonction membre pour remplacer les éléments d’un tableau avec les éléments d’un autre tableau.

Copy ne libère pas de mémoire ; Toutefois, si nécessaire, Copy peut allouer de la mémoire supplémentaire pour prendre en charge les éléments copiés dans le tableau.

Exemple

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`

Retourne une référence temporaire à l’élément spécifié dans le tableau.

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

Paramètres

nIndex
Index entier supérieur ou égal à 0 et inférieur ou égal à la valeur retournée par GetUpperBound.

Valeur de retour

Référence à un élément de tableau.

Notes

Il est utilisé pour implémenter l’opérateur d’affectation de gauche pour les tableaux.

Exemple

Consultez l’exemple pour GetSize.

`CArray::FreeExtra`

Libère toute mémoire supplémentaire allouée pendant la croissance du tableau.

void FreeExtra();

Notes

Cette fonction n’a aucun effet sur la taille ou la limite supérieure du tableau.

Exemple

Consultez l’exemple pour GetData.

`CArray::GetAt`

Retourne l’élément de tableau à l’index spécifié.

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

Paramètres

TYPE
Paramètre de modèle spécifiant le type des éléments de tableau.

nIndex
Index entier supérieur ou égal à 0 et inférieur ou égal à la valeur retournée par GetUpperBound.

Valeur de retour

Élément de tableau actuellement à cet index.

Notes

Le passage d’une valeur négative ou d’une valeur supérieure à la valeur retournée entraîne GetUpperBound une assertion ayant échoué.

Exemple

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`

Retourne le nombre d’éléments de tableau.

INT_PTR GetCount() const;

Valeur de retour

Nombre d’éléments dans le tableau.

Notes

Appelez cette méthode pour récupérer le nombre d’éléments dans le tableau. Étant donné que les index sont de base zéro, la taille est supérieure à 1 index le plus grand. L’appel de cette méthode génère le même résultat que la CArray::GetSize méthode.

Exemple

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`

Utilisez cette fonction membre pour accéder directement aux éléments d’un tableau.

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

Paramètres

TYPE
Paramètre de modèle spécifiant le type des éléments de tableau.

Valeur de retour

Pointeur vers un élément de tableau.

Notes

Si aucun élément n’est disponible, GetData retourne une valeur Null.

Bien que l’accès direct aux éléments d’un tableau puisse vous aider à travailler plus rapidement, utilisez la prudence lors de l’appel GetData; toutes les erreurs que vous effectuez affectent directement les éléments de votre tableau.

Exemple

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`

Retourne la taille du tableau.

INT_PTR GetSize() const;

Notes

Étant donné que les index sont de base zéro, la taille est supérieure à 1 index le plus grand. L’appel de cette méthode génère le même résultat que la CArray::GetCount méthode.

Exemple

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`

Retourne la limite supérieure actuelle de ce tableau.

INT_PTR GetUpperBound() const;

Notes

Étant donné que les index de tableau sont de base zéro, cette fonction retourne une valeur inférieure à 1 GetSize.

La condition GetUpperBound( ) = -1 indique que le tableau ne contient aucun élément.

Exemple

Consultez l’exemple pour CArray::GetAt.

`CArray::InsertAt`

La première version d’insère InsertAt un élément (ou plusieurs copies d’un élément) à un index spécifié dans un tableau.

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

void InsertAt(
    INT_PTR nStartIndex,
    CArray* pNewArray);

Paramètres

nIndex
Index entier qui peut être supérieur à la valeur retournée par GetUpperBound.

ARG_TYPE
Paramètre de modèle spécifiant le type d’éléments dans ce tableau.

newElement
Élément à placer dans ce tableau.

nCount
Nombre de fois où cet élément doit être inséré (valeur par défaut : 1).

nStartIndex
Index entier qui peut être supérieur à la valeur retournée par GetUpperBound.

pNewArray
Autre tableau qui contient des éléments à ajouter à ce tableau.

Notes

Dans le processus, il se déplace vers le haut (en incrémentant l’index) l’élément existant à cet index, et il déplace tous les éléments au-dessus de celui-ci.

La deuxième version insère tous les éléments d’une autre CArray collection, en commençant à la nStartIndex position.

La SetAt fonction, en revanche, remplace un élément de tableau spécifié et ne déplace aucun élément.

Exemple

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

Détermine si le tableau est vide.

BOOL IsEmpty() const;

Valeur de retour

Différent de zéro si le tableau ne contient aucun élément ; sinon 0.

`CArray::operator []`

Ces opérateurs d’indice sont un substitut pratique pour les fonctions et GetAt les SetAt fonctions.

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

Paramètres

TYPE
Paramètre de modèle spécifiant le type d’éléments dans ce tableau.

nIndex
Index de l’élément à accéder.

Notes

Le premier opérateur, appelé pour les tableaux qui ne sont pas const, peut être utilisé à droite (r-value) ou à gauche (l-value) d’une instruction d’affectation. La deuxième, appelée pour const les tableaux, peut être utilisée uniquement à droite.

La version de débogage de la bibliothèque affirme si l’indice (à gauche ou à droite d’une instruction d’affectation) est hors limites.

Exemple

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`

Déplace les données vers une nouvelle mémoire tampon lorsque le tableau doit croître ou réduire.

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

Paramètres

pNewData
Nouvelle mémoire tampon pour le tableau d’éléments.

pData
Ancien tableau d’éléments.

nCount
Nombre d’éléments dans l’ancien tableau.

Notes

pNewData est toujours assez grand pour contenir tous les pData éléments.

L’implémentation CArray utilise cette méthode pour copier les anciennes données dans une nouvelle mémoire tampon lorsque le tableau doit croître ou réduire (quand SetSize ou FreeExtra sont appelés). L’implémentation par défaut copie simplement les données.

Pour les tableaux dans lesquels un élément contient un pointeur vers l’un de ses propres membres, ou une autre structure contient un pointeur vers l’un des éléments de tableau, les pointeurs ne sont pas mis à jour en copie simple. Dans ce cas, vous pouvez corriger les pointeurs en implémentant une spécialisation avec RelocateElements les types appropriés. Vous êtes également responsable de la copie des données.

`CArray::RemoveAll`

Supprime tous les éléments de ce tableau.

void RemoveAll();

Notes

Si le tableau est déjà vide, la fonction fonctionne toujours.

Exemple

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`

Supprime un ou plusieurs éléments commençant à un index spécifié dans un tableau.

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

Paramètres

nIndex
Index entier supérieur ou égal à 0 et inférieur ou égal à la valeur retournée par GetUpperBound.

nCount
Nombre d'éléments à supprimer.

Notes

Dans le processus, il déplace tous les éléments au-dessus du ou des éléments supprimés. Il décrémente la limite supérieure du tableau, mais ne libère pas de mémoire.

Si vous essayez de supprimer plus d’éléments que ceux contenus dans le tableau au-dessus du point de suppression, la version de débogage de la bibliothèque affirme.

Exemple

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`

Définit l’élément de tableau à l’index spécifié.

void SetAt(INT_PTR nIndex, ARG_TYPE newElement);

Paramètres

nIndex
Index entier supérieur ou égal à 0 et inférieur ou égal à la valeur retournée par GetUpperBound.

ARG_TYPE
Paramètre de modèle spécifiant le type d’arguments utilisé pour référencer des éléments de tableau.

newElement
Nouvelle valeur d’élément à stocker à la position spécifiée.

Notes

SetAt ne provoquera pas la croissance du tableau. Utilisez SetAtGrow si vous souhaitez que le tableau augmente automatiquement.

Vous devez vous assurer que votre valeur d’index représente une position valide dans le tableau. S’il est hors limites, la version de débogage de la bibliothèque affirme.

Exemple

Consultez l’exemple pour GetAt.

`CArray::SetAtGrow`

Définit l’élément de tableau à l’index spécifié.

void SetAtGrow(INT_PTR nIndex, ARG_TYPE newElement);

Paramètres

nIndex
Index entier supérieur ou égal à 0.

ARG_TYPE
Paramètre de modèle spécifiant le type d’éléments dans le tableau.

newElement
Élément à ajouter à ce tableau. Une NULL valeur est autorisée.

Notes

Le tableau augmente automatiquement si nécessaire (autrement dit, la limite supérieure est ajustée pour prendre en charge le nouvel élément).

Exemple

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

Établit la taille d’un tableau vide ou existant ; alloue de la mémoire si nécessaire.

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

Paramètres

nNewSize
Nouvelle taille de tableau (nombre d’éléments). Doit être supérieur ou égal à 0.

nGrowBy
Nombre minimal d’emplacements d’élément à allouer si une augmentation de taille est nécessaire.

Notes

Si la nouvelle taille est inférieure à l’ancienne taille, le tableau est tronqué et toutes les mémoires inutilisées sont libérées.

Utilisez cette fonction pour définir la taille de votre tableau avant de commencer à utiliser le tableau. Si vous n'utilisez pas SetSize, l'ajout d'éléments à votre tableau risque d'entraîner de fréquentes opérations de réallocation et de copie de ce dernier. Les opérations fréquentes de réallocation et de copie sont inefficaces et peuvent fragmenter la mémoire.

Le nGrowBy paramètre affecte l’allocation de mémoire interne pendant la croissance du tableau. Son utilisation n’affecte jamais la taille du tableau comme indiqué par GetSize et GetUpperBound. Si la valeur par défaut est utilisée, MFC alloue de la mémoire d’une manière calculée pour éviter la fragmentation de la mémoire et optimiser l’efficacité pour la plupart des cas.

Exemple

Consultez l’exemple pour GetData.

Voir aussi

Exemple MFC COLLECT
CObject Classe
Graphique hiérarchique
CObArray Classe
Programmes d’assistance pour les classes de collection

Partager via

La classe CArray

Syntaxe

Paramètres

Membres

Constructeurs publics

Méthodes publiques

Opérateurs publics

Notes

Hiérarchie d'héritage

Spécifications

CArray::Add

Paramètres

Valeur de retour

Notes

Exemple

CArray::Append

Paramètres

Valeur de retour

Notes

Exemple

CArray::CArray

Notes

Exemple

CArray::Copy

Paramètres

Notes

Exemple

CArray::ElementAt

Paramètres

Valeur de retour

Notes

Exemple

CArray::FreeExtra

Notes

Exemple

CArray::GetAt

Paramètres

Valeur de retour

Notes

Exemple

CArray::GetCount

Valeur de retour

Notes

Exemple

CArray::GetData

Paramètres

Valeur de retour

Notes

Exemple

CArray::GetSize

Notes

Exemple

CArray::GetUpperBound

Notes

Exemple

CArray::InsertAt

Paramètres

Notes

Exemple

CArray::IsEmpty

Valeur de retour

CArray::operator []

Paramètres

Notes

Exemple

CArray::RelocateElements

Paramètres

Notes

CArray::RemoveAll

Notes

Exemple

CArray::RemoveAt

Paramètres

Notes

Exemple

CArray::SetAt

Paramètres

Notes

Exemple

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