CAtlArray, classe

Cette classe implémente un objet de tableau.

Syntaxe

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

Paramètres

E
Type de données à stocker dans le tableau.

ETraits
Code utilisé pour copier ou déplacer des éléments.

Members (Membres)

Méthodes

Fonction	Description
Ajouter	Appelez cette méthode pour ajouter un élément à l’objet tableau.
Ajouter	Appelez cette méthode pour ajouter le contenu d’un tableau à la fin d’une autre.
AssertValid	Appelez cette méthode pour vérifier que l’objet tableau est valide.
CAtlArray	Constructeur .
~CAtlArray	Destructeur.
Copy	Appelez cette méthode pour copier les éléments d’un tableau vers un autre.
FreeExtra	Appelez cette méthode pour supprimer les éléments vides du tableau.
GetAt	Appelez cette méthode pour récupérer un élément unique à partir de l’objet tableau.
GetCount	Appelez cette méthode pour retourner le nombre d’éléments stockés dans le tableau.
GetData	Appelez cette méthode pour retourner un pointeur vers le premier élément du tableau.
InsertArrayAt	Appelez cette méthode pour insérer un tableau dans un autre.
InsertAt	Appelez cette méthode pour insérer un nouvel élément (ou plusieurs copies d’un élément) dans l’objet tableau.
IsEmpty	Appelez cette méthode pour tester si le tableau est vide.
RemoveAll	Appelez cette méthode pour supprimer tous les éléments de l’objet tableau.
RemoveAt	Appelez cette méthode pour supprimer un ou plusieurs éléments du tableau.
SetAt	Appelez cette méthode pour définir la valeur d’un élément dans l’objet tableau.
SetAtGrow	Appelez cette méthode pour définir la valeur d’un élément dans l’objet tableau, en développant le tableau en fonction des besoins.
SetCount	Appelez cette méthode pour définir la taille de l’objet tableau.

Opérateurs

Opérateur	Description
operator []	Appelez cet opérateur pour renvoyer une référence à un élément du tableau.

Typedefs

Typedef	Description
INARGTYPE	Type de données à utiliser pour ajouter des éléments au tableau.
OUTARGTYPE	Type de données à utiliser pour récupérer des éléments du tableau.

Notes

CAtlArray fournit des méthodes pour créer et gérer un tableau d’éléments d’un type défini par l’utilisateur. Bien que similaire aux tableaux C standard, l’objet CAtlArray peut réduire et croître dynamiquement si nécessaire. L’index de tableau commence toujours à la position 0, et la limite supérieure peut être fixe ou autorisée à se développer à mesure que de nouveaux éléments sont ajoutés.

Pour les tableaux avec un petit nombre d’éléments, la classe ATL CSimpleArray peut être utilisée.

CAtlArray est étroitement lié à la classe de CArray MFC et fonctionnera dans un projet MFC, bien que sans prise en charge de la sérialisation.

Pour plus d’informations, consultez les classes de collection ATL.

Spécifications

En-tête : atlcoll.h

CAtlArray ::Add

Appelez cette méthode pour ajouter un élément à l’objet tableau.

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

Paramètres

Élément
Élément à ajouter au tableau.

Valeur de retour

Retourne l’index de l’élément ajouté.

Notes

Le nouvel élément est ajouté à la fin du tableau. Si aucun élément n’est fourni, un élément vide est ajouté ; autrement dit, le tableau est augmenté de taille comme si un élément réel a été ajouté. Si l’opération échoue, AtlThrow est appelé avec l’argument E_OUTOFMEMORY.

Exemple

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

Appelez cette méthode pour ajouter le contenu d’un tableau à la fin d’une autre.

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

Paramètres

Asrc
Tableau à ajouter.

Valeur de retour

Retourne l’index du premier élément ajouté.

Notes

Les éléments du tableau fourni sont ajoutés à la fin du tableau existant. Si nécessaire, la mémoire sera allouée pour prendre en charge les nouveaux éléments.

Les tableaux doivent être du même type et il n’est pas possible d’ajouter un tableau lui-même.

Dans les builds de débogage, un ATLASSERT est déclenché si l’argument CAtlArray n’est pas un tableau valide ou si aSrc fait référence au même objet. Dans les builds de mise en production, les arguments non valides peuvent entraîner un comportement imprévisible.

Exemple

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

Appelez cette méthode pour vérifier que l’objet tableau est valide.

void AssertValid() const;

Notes

Si l’objet tableau n’est pas valide, ATLASSERT lève une assertion. Cette méthode est disponible uniquement si _DEBUG est définie.

Exemple

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

CAtlArray ::CAtlArray

Constructeur .

CAtlArray() throw();

Notes

Initialise l’objet tableau.

Exemple

CAtlArray<int> iArray;   

CAtlArray ::~CAtlArray

Destructeur.

~CAtlArray() throw();

Notes

Libère toutes les ressources utilisées par l’objet tableau.

CAtlArray ::Copy

Appelez cette méthode pour copier les éléments d’un tableau vers un autre.

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

Paramètres

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

Notes

Appelez cette méthode pour remplacer les éléments d’un tableau avec les éléments d’un autre tableau. Si nécessaire, la mémoire sera allouée pour prendre en charge les nouveaux éléments. Il n’est pas possible de copier des éléments d’un tableau lui-même.

Si le contenu existant du tableau doit être conservé, utilisez CAtlArray ::Append à la place.

Dans les builds de débogage, un ATLASSERT est déclenché si l’objet existant CAtlArray n’est pas valide ou si aSrc fait référence au même objet. Dans les builds de mise en production, les arguments non valides peuvent entraîner un comportement imprévisible.

Remarque

CAtlArray::Copy ne prend pas en charge les tableaux composés d’éléments créés avec la classe CAutoPtr .

Exemple

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

Appelez cette méthode pour supprimer les éléments vides du tableau.

void FreeExtra() throw();

Notes

Tous les éléments vides sont supprimés, mais la taille et la limite supérieure du tableau restent inchangées.

Dans les builds de débogage, un ATLASSERT est déclenché si l’objet CAtlArray n’est pas valide ou si le tableau dépasse sa taille maximale.

CAtlArray ::GetAt

Appelez cette méthode pour récupérer un élément unique à partir de l’objet tableau.

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

Paramètres

iElement
Valeur d’index de l’élément de tableau à retourner.

Valeur de retour

Retourne une référence à l’élément de tableau requis.

Notes

Dans les builds de débogage, un ATLASSERT est déclenché si iElement dépasse le nombre d’éléments dans le tableau. Dans les builds de mise en production, un argument non valide peut entraîner un comportement imprévisible.

Exemple

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

Appelez cette méthode pour retourner le nombre d’éléments stockés dans le tableau.

size_t GetCount() const throw();

Valeur de retour

Retourne le nombre d’éléments stockés dans le tableau.

Notes

Comme le premier élément du tableau est à la position 0, la valeur retournée par GetCount est toujours supérieure à 1 index le plus grand.

Exemple

Consultez l’exemple de CAtlArray ::GetAt.

CAtlArray ::GetData

Appelez cette méthode pour retourner un pointeur vers le premier élément du tableau.

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

Valeur de retour

Retourne un pointeur vers l’emplacement de mémoire stockant le premier élément du tableau. Si aucun élément n’est disponible, NULL est retourné.

Exemple

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

Type de données à utiliser pour ajouter des éléments au tableau.

typedef ETraits::INARGTYPE INARGTYPE;

CAtlArray ::InsertArrayAt

Appelez cette méthode pour insérer un tableau dans un autre.

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

Paramètres

iStart
Index auquel le tableau doit être inséré.

paNew
Tableau à insérer.

Notes

Les éléments du tableau paNew sont copiés dans l’objet de tableau, en commençant par l’élément iStart. Les éléments de tableau existants sont déplacés pour éviter d’être remplacés.

Dans les builds de débogage, un ATLASSERT est déclenché si l’objet CAtlArray n’est pas valide, ou si le pointeur paNew est NULL ou non valide.

Remarque

CAtlArray::InsertArrayAt ne prend pas en charge les tableaux composés d’éléments créés avec la classe CAutoPtr .

Exemple

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

Appelez cette méthode pour insérer un nouvel élément (ou plusieurs copies d’un élément) dans l’objet tableau.

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

Paramètres

iElement
Index dans lequel l’élément ou les éléments doivent être insérés.

Élément
Valeur de l’élément ou des éléments à insérer.

nCount
Nombre d’éléments à ajouter.

Notes

Insère un ou plusieurs éléments dans le tableau, en commençant à l’index iElement. Les éléments existants sont déplacés pour éviter d’être remplacés.

Dans les builds de débogage, un ATLASSERT est déclenché si l’objet CAtlArray n’est pas valide, le nombre d’éléments à ajouter est égal à zéro, ou le nombre combiné d’éléments est trop grand pour que le tableau contienne. Dans les builds de vente au détail, la transmission de paramètres non valides peut entraîner des résultats imprévisibles.

Exemple

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

Appelez cette méthode pour tester si le tableau est vide.

bool IsEmpty() const throw();

Valeur de retour

Retourne true si le tableau est vide, false sinon.

Notes

Le tableau est dit vide s’il ne contient aucun élément. Par conséquent, même si le tableau contient des éléments vides, il n’est pas vide.

Exemple

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

Appelez cet opérateur pour renvoyer une référence à un élément du tableau.

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

Paramètres

iElement
Valeur d’index de l’élément de tableau à retourner.

Valeur de retour

Retourne une référence à l’élément de tableau requis.

Notes

Exécute une fonction similaire à CAtlArray ::GetAt. Contrairement à la classe MFC CArray, cet opérateur ne peut pas être utilisé comme substitut de CAtlArray ::SetAt.

Dans les builds de débogage, un ATLASSERT est déclenché si iElement dépasse le nombre total d’éléments dans le tableau. Dans les builds de vente au détail, un paramètre non valide peut entraîner des résultats imprévisibles.

CAtlArray ::OUTARGTYPE

Type de données à utiliser pour récupérer des éléments du tableau.

typedef ETraits::OUTARGTYPE OUTARGTYPE;

CAtlArray ::RemoveAll

Appelez cette méthode pour supprimer tous les éléments de l’objet tableau.

void RemoveAll() throw();

Notes

Supprime tous les éléments de l’objet tableau.

Cette méthode appelle CAtlArray ::SetCount pour redimensionner le tableau et libère par la suite toute mémoire allouée.

Exemple

Consultez l’exemple de CAtlArray ::IsEmpty.

CAtlArray ::RemoveAt

Appelez cette méthode pour supprimer un ou plusieurs éléments du tableau.

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

Paramètres

iElement
Index du premier élément à supprimer.

nCount
Nombre d'éléments à supprimer.

Notes

Supprime un ou plusieurs éléments du tableau. Tous les éléments restants sont décalés vers le bas. La limite supérieure est décrémentée, mais la mémoire n’est pas libérée tant qu’un appel à CAtlArray ::FreeExtra n’est pas effectué.

Dans les builds de débogage, un ATLASSERT est déclenché si l’objet CAtlArray n’est pas valide ou si le total combiné d’iElement et nCount dépasse le nombre total d’éléments dans le tableau. Dans les builds de vente au détail, les paramètres non valides peuvent entraîner des résultats imprévisibles.

Exemple

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

Appelez cette méthode pour définir la valeur d’un élément dans l’objet tableau.

void SetAt(size_t iElement, INARGTYPE element);

Paramètres

iElement
Index pointant vers l’élément de tableau à définir.

Élément
Nouvelle valeur de l’élément spécifié.

Notes

Dans les builds de débogage, un ATLASSERT est déclenché si iElement dépasse le nombre d’éléments dans le tableau. Dans les builds de vente au détail, un paramètre non valide peut entraîner des résultats imprévisibles.

Exemple

Consultez l’exemple de CAtlArray ::GetAt.

CAtlArray ::SetCount

Appelez cette méthode pour définir la taille de l’objet tableau.

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

Paramètres

nNewSize
Taille requise du tableau.

nGrowBy
Valeur utilisée pour déterminer la taille de la mémoire tampon. La valeur -1 entraîne l’utilisation d’une valeur calculée en interne.

Valeur de retour

Retourne true si le tableau est correctement redimensionné, false dans le cas contraire.

Notes

Le tableau peut être augmenté ou diminué en taille. En cas d’augmentation, des éléments vides supplémentaires sont ajoutés au tableau. En cas de diminution, les éléments avec les plus grands index sont supprimés et libérés en mémoire.

Utilisez cette méthode pour définir la taille du tableau avant de l’utiliser. Si SetCount ce n’est pas le cas, le processus d’ajout d’éléments ( et l’allocation de mémoire suivante effectuée) réduit les performances et la mémoire fragment.

Exemple

Consultez l’exemple de CAtlArray ::GetData.

CAtlArray ::SetAtGrow

Appelez cette méthode pour définir la valeur d’un élément dans l’objet tableau, en développant le tableau en fonction des besoins.

void SetAtGrow(size_t iElement, INARGTYPE element);

Paramètres

iElement
Index pointant vers l’élément de tableau à définir.

Élément
Nouvelle valeur de l’élément spécifié.

Notes

Remplace la valeur de l’élément pointé par l’index. Si iElement est supérieur à la taille actuelle du tableau, le tableau est automatiquement augmenté à l’aide d’un appel à CAtlArray ::SetCount. Dans les builds de débogage, un ATLASSERT est déclenché si l’objet CAtlArray n’est pas valide. Dans les builds de vente au détail, les paramètres non valides peuvent entraîner des résultats imprévisibles.

Exemple

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

Voir aussi

Exemple MMXSwarm
Exemple DynamicConsumer
Exemple UpdatePV
Exemple de marque
CArray, classe
Vue d’ensemble de la classe