CArray-Klasse

Unterstützt Arrays, die wie C-Arrays sind, aber bei Bedarf dynamisch reduzieren und wachsen können.

Syntax

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

Parameter

TYPE
Vorlagenparameter, der den Typ der im Array gespeicherten Objekte angibt. TYPE ist ein Parameter, der von CArray.

ARG_TYPE
Vorlagenparameter, der den Argumenttyp angibt, der für den Zugriff auf im Array gespeicherte Objekte verwendet wird. Häufig ein Verweis auf TYPE. ARG_TYPE ist ein Parameter, der CArrayan .

Member

Öffentliche Konstruktoren

Name	Beschreibung
CArray::CArray	Erstellt ein leeres Array.

Öffentliche Methoden

Name	Beschreibung
CArray::Add	Fügt am Ende des Arrays ein Element hinzu; vergrößert das Array bei Bedarf.
CArray::Append	Fügt ein weiteres Array an das Array an; wächst bei Bedarf das Array.
CArray::Copy	Kopiert ein anderes Array in das Array; vergrößert das Array bei Bedarf.
CArray::ElementAt	Gibt einen temporären Verweis auf den Elementzeiger innerhalb des Arrays zurück.
CArray::FreeExtra	Gibt den gesamten nicht verwendeten Arbeitsspeicher über der aktuellen Obergrenze frei.
CArray::GetAt	Gibt den Wert an einem bestimmten Index zurück.
CArray::GetCount	Ruft die Anzahl der Elemente im Array ab.
CArray::GetData	Ermöglicht den Zugriff auf Elemente im Array. Kann NULL sein.
CArray::GetSize	Ruft die Anzahl der Elemente im Array ab.
CArray::GetUpperBound	Gibt den größten gültigen Index zurück.
CArray::InsertAt	Fügt ein Element (oder alle Elemente in einem anderen Array) am angegebenen Index ein.
CArray::IsEmpty	Bestimmt, ob das Array leer ist.
CArray::RemoveAll	Entfernt alle Elemente aus diesem Array.
CArray::RemoveAt	Entfernt ein Element an einem spezifischen Index.
CArray::SetAt	Legt den Wert für einen bestimmten Index fest; Array darf nicht vergrößert werden.
CArray::SetAtGrow	Legt den Wert für einen bestimmten Index fest; vergrößert das Array bei Bedarf.
CArray::SetSize	Legt die Anzahl der Elemente im Array fest.

Öffentliche Operatoren

Name	Beschreibung
operator[]	Legt das Element am angegebenen Index fest oder ruft es ab.

Hinweise

Arrayindizes beginnen immer an Position 0. Sie können entscheiden, ob die obere Grenze behoben oder das Array erweitert werden soll, wenn Sie Elemente über die aktuelle Grenze einfügen. Der Arbeitsspeicher wird zusammenhängend der oberen Grenze zugewiesen, auch wenn einige Elemente null sind.

Hinweis

Die meisten Methoden, mit denen die Größe eines CArray Objekts geändert oder Elemente hinzugefügt werden, die zum Verschieben von Elementen verwendet werden memcpy_s . Dies ist ein Problem, da memcpy_s sie nicht mit Objekten kompatibel ist, für die der Konstruktor aufgerufen werden muss. Wenn die Elemente in der Datei CArray nicht kompatibel memcpy_ssind, müssen Sie eine neue CArray Größe erstellen. Anschließend müssen Sie das neue Array verwenden CArray::Copy und CArray::SetAt auffüllen, da diese Methoden einen Zuordnungsoperator anstelle von memcpy_s.

Wie bei einem C-Array ist die Zugriffszeit für ein CArray indiziertes Element konstant und unabhängig von der Arraygröße.

Tipp

Vor dem Verwenden eines Arrays, verwenden Sie SetSize, um dessen Größe festzustellen, und weisen dafür Arbeitsspeicher zu. Wenn Sie SetSize nicht verwenden, kann das Hinzufügen von Elementen zu Ihrem Array dazu führen, dass es häufig neu zugeordnet und kopiert wird. Häufige Neuzuordnungen und Kopiervorgänge sind ineffizient und können zu einer Fragmentierung des Arbeitsspeichers führen.

Wenn Sie ein Dump einzelner Elemente in einem Array benötigen, müssen Sie die Tiefe des CDumpContext Objekts auf 1 oder größer festlegen.

Bestimmte Memberfunktionen dieser Klasse rufen globale Hilfsfunktionen auf, die für die meisten Verwendungen der CArray Klasse angepasst werden müssen. Weitere Informationen finden Sie im Abschnitt "MFC-Makros und Globals" der Themensammlungsklassenhilfsprogramme.

Die Arrayklassenableitung ist wie die Listenableitung.

Weitere Informationen zur Verwendung CArrayfinden Sie im Artikel "Sammlungen".

Vererbungshierarchie

CObject

CArray

Anforderungen

Headerafxtempl.h:

CArray::Add

Fügt am Ende eines Arrays ein neues Element hinzu, wobei das Array um 1 wächst.

INT_PTR Add(ARG_TYPE newElement);

Parameter

ARG_TYPE
Vorlagenparameter, der den Typ von Argumenten angibt, die auf Elemente in diesem Array verweisen.

newElement
Das Element, das diesem Array hinzugefügt werden soll.

Rückgabewert

Der Index des hinzugefügten Elements.

Hinweise

Wenn SetSize sie mit einem nGrowBy Wert verwendet wurde, der größer als 1 ist, kann zusätzlicher Arbeitsspeicher zugewiesen werden. Die obere Grenze wird jedoch nur um 1 erhöht.

Beispiel

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

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

INT_PTR Append(const CArray& src);

Parameter

src
Quelle der Elemente, die an ein Array angefügt werden sollen.

Rückgabewert

Der Index des ersten angefügten Elements.

Hinweise

Die Arrays müssen denselben Typ aufweisen.

Falls erforderlich, kann zusätzlichen Arbeitsspeicher zugewiesen werden, um die elemente aufzunehmen, Append die an das Array angefügt sind.

Beispiel

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

Erstellt ein leeres Array.

CArray();

Hinweise

Das Array vergrößert jeweils ein Element.

Beispiel

CArray<CPoint, CPoint> ptArray;

CArray::Copy

Verwenden Sie diese Memberfunktion, um die Elemente eines Arrays in ein anderes zu kopieren.

void Copy(const CArray& src);

Parameter

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

Hinweise

Rufen Sie diese Memberfunktion auf, um die Elemente eines Arrays mit den Elementen eines anderen Arrays zu überschreiben.

Copy gibt keinen Arbeitsspeicher frei; Bei Bedarf kann jedoch zusätzlichen Arbeitsspeicher zugewiesen werden, um die elemente, die in das Array kopiert wurden, Copy aufzunehmen.

Beispiel

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

Gibt einen temporären Verweis auf das angegebene Element innerhalb des Arrays zurück.

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

Parameter

nIndex
Ein ganzzahliger Index, der größer oder gleich 0 und kleiner als oder gleich dem wert ist, der von GetUpperBound.

Rückgabewert

Ein Verweis auf ein Arrayelement.

Hinweise

Es wird verwendet, um den linksseitigen Zuordnungsoperator für Arrays zu implementieren.

Beispiel

Sehen Sie sich das Beispiel für GetSize.

CArray::FreeExtra

Gibt zusätzlichen Arbeitsspeicher frei, der während des Arrays zugeordnet wurde.

void FreeExtra();

Hinweise

Diese Funktion hat keine Auswirkungen auf die Größe oder obere Grenze des Arrays.

Beispiel

Sehen Sie sich das Beispiel für GetData.

CArray::GetAt

Gibt das Arrayelement am angegebenen Index zurück.

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

Parameter

TYPE
Vorlagenparameter, der den Typ der Arrayelemente angibt.

nIndex
Ein ganzzahliger Index, der größer oder gleich 0 und kleiner als oder gleich dem wert ist, der von GetUpperBound.

Rückgabewert

Das Arrayelement, das sich derzeit in diesem Index befindet.

Hinweise

Das Übergeben eines negativen Werts oder eines Werts, der größer als der zurückgegebene GetUpperBound Wert ist, führt zu einer fehlgeschlagenen Assertion.

Beispiel

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

Gibt die Anzahl der Arrayelemente zurück.

INT_PTR GetCount() const;

Rückgabewert

Die Anzahl der Elemente im Array.

Hinweise

Rufen Sie diese Methode auf, um die Anzahl der Elemente im Array abzurufen. Da Indizes nullbasiert sind, ist die Größe 1 größer als der größte Index. Durch Aufrufen dieser Methode wird dasselbe Ergebnis wie die CArray::GetSize Methode generiert.

Beispiel

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

Verwenden Sie diese Memberfunktion, um direkten Zugriff auf die Elemente in einem Array zu erhalten.

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

Parameter

TYPE
Vorlagenparameter, der den Typ der Arrayelemente angibt.

Rückgabewert

Ein Zeiger auf ein Arrayelement.

Hinweise

Wenn keine Elemente verfügbar sind, GetData wird ein Nullwert zurückgegeben.

Während der direkte Zugriff auf die Elemente eines Arrays Ihnen helfen kann, schneller zu arbeiten, verwenden Sie Vorsicht beim Aufrufen GetData; alle Fehler, die Sie direkt vornehmen, wirken sich auf die Elemente Ihres Arrays aus.

Beispiel

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

Gibt die Größe des Arrays zurück.

INT_PTR GetSize() const;

Hinweise

Da Indizes nullbasiert sind, ist die Größe 1 größer als der größte Index. Durch Aufrufen dieser Methode wird dasselbe Ergebnis wie die CArray::GetCount Methode generiert.

Beispiel

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

Gibt die aktuelle obere Grenze dieses Arrays zurück.

INT_PTR GetUpperBound() const;

Hinweise

Da Arrayindizes nullbasiert sind, gibt diese Funktion einen Wert von 1 kleiner als GetSizezurück.

Die Bedingung GetUpperBound( ) = -1 gibt an, dass das Array keine Elemente enthält.

Beispiel

Sehen Sie sich das Beispiel für CArray::GetAt.

CArray::InsertAt

Die erste Version von InsertAt Elementen fügt ein Element (oder mehrere Kopien eines Elements) an einem angegebenen Index in einem Array ein.

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

void InsertAt(
    INT_PTR nStartIndex,
    CArray* pNewArray);

Parameter

nIndex
Ein ganzzahliger Index, der größer als der von GetUpperBound.

ARG_TYPE
Vorlagenparameter, der den Typ der Elemente in diesem Array angibt.

newElement
Das Element, das in diesem Array platziert werden soll.

nCount
Die Häufigkeit, mit der dieses Element eingefügt werden soll (Standardwert ist 1).

nStartIndex
Ein ganzzahliger Index, der größer als der von GetUpperBound.

pNewArray
Ein weiteres Array, das Elemente enthält, die diesem Array hinzugefügt werden sollen.

Hinweise

Im Prozess verschiebt es das vorhandene Element in diesem Index nach oben (indem es den Index erhöht), und er verschiebt alle darüber stehenden Elemente nach oben.

Die zweite Version fügt alle Elemente aus einer anderen CArray Auflistung ein, beginnend an der nStartIndex Position.

Die SetAt Funktion ersetzt dagegen ein angegebenes Arrayelement und verschiebt keine Elemente.

Beispiel

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

Bestimmt, ob das Array leer ist.

BOOL IsEmpty() const;

Rückgabewert

Nonzero, wenn das Array keine Elemente enthält; andernfalls 0.

CArray::operator []

Diese tiefgestellten Operatoren sind ein praktischer Ersatz für die SetAt und GetAt Funktionen.

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

Parameter

TYPE
Vorlagenparameter, der den Typ der Elemente in diesem Array angibt.

nIndex
Index des elements, auf das zugegriffen werden soll.

Hinweise

Der erste Operator, der nicht für Arrays aufgerufen wird const, kann entweder auf der rechten (r-Wert) oder links (l-Wert) einer Zuordnungsanweisung verwendet werden. Die zweite, die für const Arrays aufgerufen wird, kann nur auf der rechten Seite verwendet werden.

Die Debugversion der Bibliothek bestätigt, ob das Tiefgestellt (entweder auf der linken oder rechten Seite einer Zuordnungsanweisung) außerhalb der Grenzen liegt.

Beispiel

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

Verschlegt Daten in einen neuen Puffer, wenn das Array vergrößert oder verkleinern soll.

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

Parameter

pNewData
Ein neuer Puffer für das Array von Elementen.

pData
Das alte Array von Elementen.

nCount
Anzahl der Elemente im alten Array.

Hinweise

pNewData ist immer groß genug, um alle pData Elemente zu halten.

Die CArray Implementierung verwendet diese Methode, um die alten Daten in einen neuen Puffer zu kopieren, wenn das Array vergrößert oder verkleinern soll (wenn SetSize oder FreeExtra aufgerufen wird). Die Standardimplementierung kopiert nur die Daten.

Bei Arrays, in denen ein Element einen Zeiger auf eines seiner eigenen Elemente enthält, oder eine andere Struktur einen Zeiger auf eines der Arrayelemente enthält, werden die Zeiger nicht in nur-Kopie aktualisiert. In diesem Fall können Sie Zeiger korrigieren, indem Sie eine Spezialisierung RelocateElements mit den relevanten Typen implementieren. Sie sind auch für das Kopieren von Daten verantwortlich.

CArray::RemoveAll

Entfernt alle Elemente aus diesem Array.

void RemoveAll();

Hinweise

Wenn das Array bereits leer ist, funktioniert die Funktion weiterhin.

Beispiel

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

Entfernt ein oder mehrere Elemente, die mit einem angegebenen Index in einem Array beginnen.

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

Parameter

nIndex
Ein ganzzahliger Index, der größer oder gleich 0 und kleiner als oder gleich dem wert ist, der von GetUpperBound.

nCount
Die Anzahl der zu entfernenden Elemente.

Hinweise

Im Prozess verschiebt er alle Elemente oberhalb der entfernten Elemente nach unten. Sie erhöht die obere Grenze des Arrays, freigibt jedoch keinen Arbeitsspeicher.

Wenn Sie versuchen, mehr Elemente zu entfernen, als im Array oberhalb des Entfernungspunkts enthalten sind, wird die Debugversion der Bibliothek bestätigt.

Beispiel

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

Legt das Arrayelement am angegebenen Index fest.

void SetAt(INT_PTR nIndex, ARG_TYPE newElement);

Parameter

nIndex
Ein ganzzahliger Index, der größer oder gleich 0 und kleiner als oder gleich dem wert ist, der von GetUpperBound.

ARG_TYPE
Vorlagenparameter, der den Typ der Argumente angibt, die für verweisende Arrayelemente verwendet werden.

newElement
Der neue Elementwert, der an der angegebenen Position gespeichert werden soll.

Hinweise

SetAt führt nicht dazu, dass das Array vergrößert wird. Verwenden Sie SetAtGrow diesen Vorgang, wenn das Array automatisch vergrößert werden soll.

Sie müssen sicherstellen, dass ihr Indexwert eine gültige Position im Array darstellt. Wenn sie außerhalb der Grenzen liegt, wird die Debugversion der Bibliothek bestätigt.

Beispiel

Sehen Sie sich das Beispiel für GetAt.

CArray::SetAtGrow

Legt das Arrayelement am angegebenen Index fest.

void SetAtGrow(INT_PTR nIndex, ARG_TYPE newElement);

Parameter

nIndex
Ein ganzzahliger Index, der größer oder gleich 0 ist.

ARG_TYPE
Vorlagenparameter, der den Typ der Elemente im Array angibt.

newElement
Das Element, das diesem Array hinzugefügt werden soll. Ein NULL Wert ist zulässig.

Hinweise

Das Array wird bei Bedarf automatisch wächst (d. a. die obere Grenze wird an das neue Element angepasst).

Beispiel

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

Legt die Größe eines leeren oder vorhandenen Arrays fest; ordnet bei Bedarf Arbeitsspeicher zu.

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

Parameter

nNewSize
Die neue Arraygröße (Anzahl der Elemente). Muss größer als oder gleich 0 sein.

nGrowBy
Die Mindestanzahl der Elementplätze, die zugewiesen werden sollen, wenn eine Größenerhöhung erforderlich ist.

Hinweise

Wenn die neue Größe kleiner als die alte Größe ist, wird das Array abgeschnitten, und der gesamte nicht verwendete Arbeitsspeicher wird freigegeben.

Verwenden Sie diese Funktion, um die Größe Ihres Arrays festzulegen, bevor Sie mit der Verwendung des Arrays beginnen. Wenn Sie SetSize nicht verwenden, kann das Hinzufügen von Elementen zu Ihrem Array dazu führen, dass es häufig neu zugeordnet und kopiert wird. Häufige Neuzuordnungen und Kopiervorgänge sind ineffizient und können zu einer Fragmentierung des Arbeitsspeichers führen.

Der nGrowBy Parameter wirkt sich auf die interne Speicherzuordnung aus, während das Array wächst. Die Verwendung wirkt sich niemals auf die Arraygröße aus, wie von GetSize und GetUpperBound. Wenn der Standardwert verwendet wird, weist MFC Speicher auf eine Weise zu, die berechnet wird, um Speicherfragmentierung zu vermeiden und die Effizienz für die meisten Fälle zu optimieren.

Beispiel

Sehen Sie sich das Beispiel für GetData.

Siehe auch

MFC-Beispiel COLLECT
CObject Klasse
Hierarchiediagramm
CObArray Klasse
Hilfsfunktionen für die Auflistungsklasse