Partager via


La classe CArray

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