CAtlArray-Klasse

Diese Klasse implementiert ein Arrayobjekt.

Syntax

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

Parameter

E
Der Typ der im Array gespeicherten Daten.

ETraits
Der Code zum Kopieren oder Verschieben von Elementen.

Member

Methoden

Funktion	Beschreibung
Add (Hinzufügen)	Rufen Sie diese Methode auf, um dem Arrayobjekt ein Element hinzuzufügen.
Append (Anfügen)	Rufen Sie diese Methode auf, um den Inhalt eines Arrays am Ende eines anderen hinzuzufügen.
AssertValid	Rufen Sie diese Methode auf, um zu bestätigen, dass das Arrayobjekt gültig ist.
CAtlArray	Der Konstruktor.
~CAtlArray	Der Destruktor.
Kopieren	Rufen Sie diese Methode auf, um die Elemente eines Arrays in ein anderes zu kopieren.
FreeExtra	Rufen Sie diese Methode auf, um alle leeren Elemente aus dem Array zu entfernen.
GetAt	Rufen Sie diese Methode auf, um ein einzelnes Element aus dem Arrayobjekt abzurufen.
GetCount	Rufen Sie diese Methode auf, um die Anzahl der im Array gespeicherten Elemente zurückzugeben.
GetData	Rufen Sie diese Methode auf, um einen Zeiger auf das erste Element im Array zurückzugeben.
InsertArrayAt	Rufen Sie diese Methode auf, um ein Array in ein anderes einzufügen.
InsertAt	Rufen Sie diese Methode auf, um ein neues Element (oder mehrere Kopien eines Elements) in das Arrayobjekt einzufügen.
IsEmpty	Rufen Sie diese Methode auf, um zu testen, ob das Array leer ist.
RemoveAll	Rufen Sie diese Methode auf, um alle Elemente aus dem Arrayobjekt zu entfernen.
RemoveAt	Rufen Sie diese Methode auf, um ein oder mehrere Elemente aus dem Array zu entfernen.
SetAt	Rufen Sie diese Methode auf, um den Wert eines Elements im Arrayobjekt festzulegen.
SetAtGrow	Rufen Sie diese Methode auf, um den Wert eines Elements im Arrayobjekt festzulegen und das Array nach Bedarf zu erweitern.
SetCount	Rufen Sie diese Methode auf, um die Größe des Arrayobjekts festzulegen.

Operatoren

Operator	Beschreibung
operator []	Rufen Sie diesen Operator auf, um einen Verweis auf ein Element im Array zurückzugeben.

TypeDefs

TypeDef	Beschreibung
INARGTYPE	Der Datentyp, der zum Hinzufügen von Elementen zum Array verwendet werden soll.
OUTARGTYPE	Der Datentyp, der zum Abrufen von Elementen aus dem Array verwendet werden soll.

Hinweise

CAtlArray stellt Methoden zum Erstellen und Verwalten eines Arrays von Elementen eines benutzerdefinierten Typs bereit. Ähnlich wie standardmäßige C-Arrays kann das CAtlArray Objekt bei Bedarf dynamisch verkleinern und wachsen. Der Arrayindex beginnt immer an Position 0, und die obere Grenze kann fixiert oder erweitert werden, wenn neue Elemente hinzugefügt werden.

Für Arrays mit einer kleinen Anzahl von Elementen kann die ATL-Klasse CSimpleArray verwendet werden.

CAtlArray ist eng mit der Klasse von CArray MFC verbunden und wird in einem MFC-Projekt arbeiten, wenn auch ohne Serialisierungsunterstützung.

Weitere Informationen finden Sie unter ATL-Auflistungsklassen.

Anforderungen

Kopfzeile: atlcoll.h

CAtlArray::Add

Rufen Sie diese Methode auf, um dem Arrayobjekt ein Element hinzuzufügen.

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

Parameter

Element
Das Element, das dem Array hinzugefügt werden soll.

Rückgabewert

Gibt den Index des hinzugefügten Elements zurück.

Hinweise

Das neue Element wird am Ende des Arrays hinzugefügt. Wenn kein Element angegeben wird, wird ein leeres Element hinzugefügt. d. h., das Array wird vergrößert, als ob ein echtes Element hinzugefügt wurde. Wenn der Vorgang fehlschlägt, wird AtlThrow mit dem Argument E_OUTOFMEMORY aufgerufen.

Beispiel

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

Rufen Sie diese Methode auf, um den Inhalt eines Arrays am Ende eines anderen hinzuzufügen.

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

Parameter

aSrc
Das anzufügende Array.

Rückgabewert

Gibt den Index des ersten angefügten Elements zurück.

Hinweise

Die Elemente im angegebenen Array werden am Ende des vorhandenen Arrays hinzugefügt. Bei Bedarf wird Speicher zugewiesen, um die neuen Elemente aufzunehmen.

Die Arrays müssen denselben Typ aufweisen, und es ist nicht möglich, ein Array an sich selbst anzufügen.

In Debugbuilds wird ein ATLASSERT ausgelöst, wenn das CAtlArray Argument kein gültiges Array ist oder aSrc auf dasselbe Objekt verweist. In Releasebuilds können ungültige Argumente zu unvorhersehbaren Verhaltensweisen führen.

Beispiel

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

Rufen Sie diese Methode auf, um zu bestätigen, dass das Arrayobjekt gültig ist.

void AssertValid() const;

Hinweise

Wenn das Arrayobjekt ungültig ist, löst ATLASSERT eine Assertion aus. Diese Methode ist nur verfügbar, wenn _DEBUG definiert ist.

Beispiel

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

CAtlArray::CAtlArray

Der Konstruktor.

CAtlArray() throw();

Hinweise

Initialisiert das Arrayobjekt.

Beispiel

CAtlArray<int> iArray;   

CAtlArray::~CAtlArray

Der Destruktor.

~CAtlArray() throw();

Hinweise

Gibt alle vom Arrayobjekt verwendeten Ressourcen frei.

CAtlArray::Copy

Rufen Sie diese Methode auf, um die Elemente eines Arrays in ein anderes zu kopieren.

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

Parameter

aSrc
Die Quelle der Elemente, die in ein Array kopiert werden sollen.

Hinweise

Rufen Sie diese Methode auf, um Elemente eines Arrays mit den Elementen eines anderen Arrays zu überschreiben. Bei Bedarf wird Speicher zugewiesen, um die neuen Elemente aufzunehmen. Es ist nicht möglich, Elemente eines Arrays auf sich selbst zu kopieren.

Wenn der vorhandene Inhalt des Arrays beibehalten werden soll, verwenden Sie stattdessen "CAtlArray::Append" .

In Debugbuilds wird ein ATLASSERT ausgelöst, wenn das vorhandene CAtlArray Objekt ungültig ist oder aSrc auf dasselbe Objekt verweist. In Releasebuilds können ungültige Argumente zu unvorhersehbaren Verhaltensweisen führen.

Beispiel

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

Rufen Sie diese Methode auf, um alle leeren Elemente aus dem Array zu entfernen.

void FreeExtra() throw();

Hinweise

Alle leeren Elemente werden entfernt, aber die Größe und obere Grenze des Arrays bleiben unverändert.

In Debugbuilds wird ein ATLASSERT ausgelöst, wenn das CAtlArray-Objekt ungültig ist oder wenn das Array seine maximale Größe überschreitet.

CAtlArray::GetAt

Rufen Sie diese Methode auf, um ein einzelnes Element aus dem Arrayobjekt abzurufen.

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

Parameter

iElement
Der Indexwert des zurückzugebenden Arrayelements.

Rückgabewert

Gibt einen Verweis auf das erforderliche Arrayelement zurück.

Hinweise

In Debugbuilds wird ein ATLASSERT ausgelöst, wenn iElement die Anzahl der Elemente im Array überschreitet. In Releasebuilds kann ein ungültiges Argument zu unvorhersehbaren Verhaltensweisen führen.

Beispiel

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

Rufen Sie diese Methode auf, um die Anzahl der im Array gespeicherten Elemente zurückzugeben.

size_t GetCount() const throw();

Rückgabewert

Gibt die Anzahl der im Array gespeicherten Elemente zurück.

Hinweise

Wenn das erste Element im Array an Position 0 liegt, ist der von GetCount diesem zurückgegebene Wert immer 1 größer als der größte Index.

Beispiel

Sehen Sie sich das Beispiel für CAtlArray::GetAt an.

CAtlArray::GetData

Rufen Sie diese Methode auf, um einen Zeiger auf das erste Element im Array zurückzugeben.

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

Rückgabewert

Gibt einen Zeiger auf den Speicherspeicherort zurück, der das erste Element im Array speichert. Wenn keine Elemente verfügbar sind, wird NULL zurückgegeben.

Beispiel

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

Der Datentyp, der zum Hinzufügen von Elementen zum Array verwendet werden soll.

typedef ETraits::INARGTYPE INARGTYPE;

CAtlArray::InsertArrayAt

Rufen Sie diese Methode auf, um ein Array in ein anderes einzufügen.

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

Parameter

iStart
Der Index, an dem das Array eingefügt werden soll.

paNew
Das einzufügende Array.

Hinweise

Elemente aus dem Array paNew werden in das Arrayobjekt kopiert, beginnend bei Element iStart. Die vorhandenen Arrayelemente werden verschoben, um zu vermeiden, dass sie überschrieben werden.

In Debugbuilds wird ein ATLASSERT ausgelöst, wenn das CAtlArray Objekt ungültig ist oder der paNew-Zeiger NULL oder ungültig ist.

Beispiel

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

Rufen Sie diese Methode auf, um ein neues Element (oder mehrere Kopien eines Elements) in das Arrayobjekt einzufügen.

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

Parameter

iElement
Der Index, in den das Element oder die Elemente eingefügt werden sollen.

Element
Der Wert des einzufügenden Elements oder elements.

nCount
Die Anzahl der hinzuzufügenden Elemente.

Hinweise

Fügt ein oder mehrere Elemente in das Array ein, beginnend bei index iElement. Vorhandene Elemente werden verschoben, um zu vermeiden, dass sie überschrieben werden.

In Debugbuilds wird ein ATLASSERT ausgelöst, wenn das CAtlArray Objekt ungültig ist, die Anzahl der hinzuzufügenden Elemente null ist oder die kombinierte Anzahl von Elementen zu groß ist, damit das Array enthalten kann. In Einzelhandelsbuilds kann das Übergeben ungültiger Parameter zu unvorhersehbaren Ergebnissen führen.

Beispiel

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

Rufen Sie diese Methode auf, um zu testen, ob das Array leer ist.

bool IsEmpty() const throw();

Rückgabewert

Gibt true zurück, wenn das Array leer ist, andernfalls "false".

Hinweise

Das Array soll leer sein, wenn es keine Elemente enthält. Selbst wenn das Array leere Elemente enthält, ist es daher nicht leer.

Beispiel

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

Rufen Sie diesen Operator auf, um einen Verweis auf ein Element im Array zurückzugeben.

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

Parameter

iElement
Der Indexwert des zurückzugebenden Arrayelements.

Rückgabewert

Gibt einen Verweis auf das erforderliche Arrayelement zurück.

Hinweise

Führt eine ähnliche Funktion wie CAtlArray::GetAt aus. Im Gegensatz zur MFC-Klasse CArray kann dieser Operator nicht als Ersatz für CAtlArray::SetAt verwendet werden.

Bei Debugbuilds wird ein ATLASSERT ausgelöst, wenn iElement die Gesamtanzahl der Elemente im Array überschreitet. In Einzelhandelsbuilds kann ein ungültiger Parameter zu unvorhersehbaren Ergebnissen führen.

CAtlArray::OUTARGTYPE

Der Datentyp, der zum Abrufen von Elementen aus dem Array verwendet werden soll.

typedef ETraits::OUTARGTYPE OUTARGTYPE;

CAtlArray::RemoveAll

Rufen Sie diese Methode auf, um alle Elemente aus dem Arrayobjekt zu entfernen.

void RemoveAll() throw();

Hinweise

Entfernt alle Elemente aus dem Arrayobjekt.

Diese Methode ruft CAtlArray::SetCount auf, um die Größe des Arrays zu ändern und anschließend alle zugeordneten Speicher freizugeben.

Beispiel

Sehen Sie sich das Beispiel für CAtlArray::IsEmpty an.

CAtlArray::RemoveAt

Rufen Sie diese Methode auf, um ein oder mehrere Elemente aus dem Array zu entfernen.

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

Parameter

iElement
Der Index des ersten zu entfernenden Elements.

nCount
Die Anzahl der zu entfernenden Elemente.

Hinweise

Entfernt ein oder mehrere Elemente aus dem Array. Alle verbleibenden Elemente werden nach unten verschoben. Die obere Grenze wird erhöht, der Arbeitsspeicher wird jedoch erst freigegeben, wenn ein Aufruf von CAtlArray::FreeExtra erfolgt.

In Debugbuilds wird ein ATLASSERT ausgelöst, wenn das CAtlArray Objekt ungültig ist oder wenn die kombinierte Summe von iElement und nCount die Gesamtanzahl der Elemente im Array überschreitet. In Einzelhandelsbuilds können ungültige Parameter zu unvorhersehbaren Ergebnissen führen.

Beispiel

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

Rufen Sie diese Methode auf, um den Wert eines Elements im Arrayobjekt festzulegen.

void SetAt(size_t iElement, INARGTYPE element);

Parameter

iElement
Der Index, der auf das festzulegende Arrayelement zeigt.

Element
Der neue Wert des angegebenen Elements.

Hinweise

In Debugbuilds wird ein ATLASSERT ausgelöst, wenn iElement die Anzahl der Elemente im Array überschreitet. In Einzelhandelsbuilds kann ein ungültiger Parameter zu unvorhersehbaren Ergebnissen führen.

Beispiel

Sehen Sie sich das Beispiel für CAtlArray::GetAt an.

CAtlArray::SetCount

Rufen Sie diese Methode auf, um die Größe des Arrayobjekts festzulegen.

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

Parameter

nNewSize
Die erforderliche Größe des Arrays.

nGrowBy
Ein Wert, der verwendet wird, um zu bestimmen, wie groß der Puffer wird. Ein Wert von -1 bewirkt, dass ein intern berechneter Wert verwendet wird.

Rückgabewert

Gibt true zurück, wenn die Größe des Arrays erfolgreich geändert wurde, andernfalls "false".

Hinweise

Das Array kann vergrößert oder verkleinert werden. Wenn dies erhöht wird, werden dem Array zusätzliche leere Elemente hinzugefügt. Wenn die Elemente verringert werden, werden die Elemente mit den größten Indizes gelöscht und der Speicher freigegeben.

Verwenden Sie diese Methode, um die Größe des Arrays festzulegen, bevor Sie es verwenden. Wenn SetCount dies nicht der Fall ist, verringert sich der Prozess des Hinzufügens von Elementen – und der nachfolgenden ausgeführten Speicherzuweisung – zur Leistungs- und Fragmentspeicherung.

Beispiel

Sehen Sie sich das Beispiel für CAtlArray::GetData an.

CAtlArray::SetAtGrow

Rufen Sie diese Methode auf, um den Wert eines Elements im Arrayobjekt festzulegen und das Array nach Bedarf zu erweitern.

void SetAtGrow(size_t iElement, INARGTYPE element);

Parameter

iElement
Der Index, der auf das festzulegende Arrayelement zeigt.

Element
Der neue Wert des angegebenen Elements.

Hinweise

Ersetzt den Wert des Elements, auf das durch den Index verwiesen wird. Wenn iElement größer als die aktuelle Größe des Arrays ist, wird das Array automatisch mithilfe eines Aufrufs von CAtlArray::SetCount erhöht. In Debugbuilds wird ein ATLASSERT ausgelöst, wenn das CAtlArray Objekt ungültig ist. In Einzelhandelsbuilds können ungültige Parameter zu unvorhersehbaren Ergebnissen führen.

Beispiel

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

Siehe auch

MMXSwarm-Beispiel
DynamicConsumer-Beispiel
UpdatePV-Beispiel
Beispiel für Festrahmen
CArray-Klasse
Klassenübersicht