`CArray` Klasa

Artykuł
10/12/2023

Obsługuje tablice, które są podobne do tablic języka C, ale mogą dynamicznie zmniejszać i rozwijać się w razie potrzeby.

Składnia

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

Parametry

TYPE
Parametr szablonu określający typ obiektów przechowywanych w tablicy. TYPE jest parametrem zwracanym przez CArrayparametr .

ARG_TYPE
Parametr szablonu określający typ argumentu używany do uzyskiwania dostępu do obiektów przechowywanych w tablicy. Często odwołanie do TYPE. ARG_TYPE jest parametrem przekazywanym do CArray.

Członkowie

Konstruktory publiczne

Nazwa/nazwisko	opis
`CArray::CArray`	Tworzy pustą tablicę.

Metody publiczne

Nazwa/nazwisko	opis
`CArray::Add`	Dodaje element na końcu tablicy; w razie potrzeby zwiększa tablicę.
`CArray::Append`	Dołącza kolejną tablicę do tablicy; zwiększa tablicę w razie potrzeby
`CArray::Copy`	Kopiuje kolejną tablicę do tablicy; w razie potrzeby zwiększa tablicę.
`CArray::ElementAt`	Zwraca tymczasowe odwołanie do wskaźnika elementu w tablicy.
`CArray::FreeExtra`	Zwalnia całą nieużywaną pamięć powyżej bieżącej górnej granicy.
`CArray::GetAt`	Zwraca wartość dla danego indeksu.
`CArray::GetCount`	Pobiera liczbę elementów w tej tablicy.
`CArray::GetData`	Umożliwia dostęp do elementów w tablicy. Może to być `NULL`.
`CArray::GetSize`	Pobiera liczbę elementów w tej tablicy.
`CArray::GetUpperBound`	Zwraca największy prawidłowy indeks.
`CArray::InsertAt`	Wstawia element (lub wszystkie elementy w innej tablicy) w określonym indeksie.
`CArray::IsEmpty`	Określa, czy tablica jest pusta.
`CArray::RemoveAll`	Usuwa wszystkie elementy z tej tablicy.
`CArray::RemoveAt`	Usuwa element w określonym indeksie.
`CArray::SetAt`	Ustawia wartość dla danego indeksu; tablica nie może rosnąć.
`CArray::SetAtGrow`	Ustawia wartość dla danego indeksu; w razie potrzeby zwiększa tablicę.
`CArray::SetSize`	Ustawia liczbę elementów, które mają być zawarte w tej tablicy.

Operatory publiczne

Nazwa/nazwisko	opis
`operator[]`	Ustawia lub pobiera element w określonym indeksie.

Uwagi

Indeksy tablic zawsze zaczynają się od pozycji 0. Możesz zdecydować, czy naprawić górną granicę, czy umożliwić rozwinięcie tablicy podczas dodawania elementów poza bieżącą granicą. Pamięć jest przydzielana stale do górnej granicy, nawet jeśli niektóre elementy mają wartość null.

Uwaga

Większość metod zmiany rozmiaru CArray obiektu lub dodawania do niego elementów służy memcpy_s do przenoszenia elementów. Jest to problem, ponieważ memcpy_s nie jest zgodny z żadnymi obiektami, które wymagają wywołania konstruktora. Jeśli elementy w obiekcie CArray nie są zgodne z memcpy_sprogramem , należy utworzyć nowy CArray odpowiedni rozmiar. Następnie należy użyć polecenia CArray::Copy i CArray::SetAt , aby wypełnić nową tablicę, ponieważ te metody używają operatora przypisania zamiast memcpy_s.

Podobnie jak w przypadku tablicy C, czas dostępu dla CArray indeksowanego elementu jest stały i jest niezależny od rozmiaru tablicy.

Napiwek

Przed użyciem tablicy użyj polecenia SetSize , aby ustanowić jego rozmiar i przydzielić dla niej pamięć. Jeśli nie używasz polecenia SetSize, dodanie elementów do tablicy powoduje, że jest on często ponownie przydzielany i kopiowany. Częste reallokowanie i kopiowanie są nieefektywne i mogą fragmentować pamięć.

Jeśli potrzebujesz zrzutu poszczególnych elementów w tablicy, musisz ustawić głębokość CDumpContext obiektu na 1 lub większą.

Niektóre funkcje składowe tej klasy wywołają globalne funkcje pomocnika, które muszą być dostosowane do większości zastosowań CArray klasy. Zapoznaj się z tematem Collection Class Helpers (Pomocnicy klas kolekcji) w sekcji Makra i globals MFC.

Wyprowadzanie klas tablicy jest podobne do wyprowadzania list.

Aby uzyskać więcej informacji na temat używania programu CArray, zobacz artykuł Kolekcje.

Hierarchia dziedziczenia

CObject

CArray

Wymagania

Nagłówka:afxtempl.h

`CArray::Add`

Dodaje nowy element na końcu tablicy, zwiększając tablicę o 1.

INT_PTR Add(ARG_TYPE newElement);

Parametry

ARG_TYPE
Parametr szablonu określający typ argumentów odwołujące się do elementów w tej tablicy.

newElement
Element, który ma zostać dodany do tej tablicy.

Wartość zwracana

Indeks dodanego elementu.

Uwagi

Jeśli SetSize użyto wartości większej niż 1, można przydzielić dodatkową nGrowBy pamięć. Jednak górna granica zwiększy się o tylko 1.

Przykład

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

Wywołaj tę funkcję składową, aby dodać zawartość jednej tablicy na końcu innej.

INT_PTR Append(const CArray& src);

Parametry

src
Źródło elementów do dołączenia do tablicy.

Wartość zwracana

Indeks pierwszego dołączonego elementu.

Uwagi

Tablice muszą być tego samego typu.

W razie potrzeby może przydzielić dodatkową pamięć, Append aby uwzględnić elementy dołączone do tablicy.

Przykład

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`

Tworzy pustą tablicę.

CArray();

Uwagi

Tablica zwiększa jeden element naraz.

Przykład

CArray<CPoint, CPoint> ptArray;

`CArray::Copy`

Użyj tej funkcji składowej, aby skopiować elementy jednej tablicy do innej.

void Copy(const CArray& src);

Parametry

src
Źródło elementów do skopiowania do tablicy.

Uwagi

Wywołaj tę funkcję składową, aby zastąpić elementy jednej tablicy elementami innej tablicy.

Copy nie zwalnia pamięci; jednak w razie potrzeby Copy może przydzielić dodatkową pamięć, aby pomieścić elementy skopiowane do tablicy.

Przykład

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`

Zwraca tymczasowe odwołanie do określonego elementu w tablicy.

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

Parametry

nIndex
Indeks liczby całkowitej, który jest większy lub równy 0 i mniejszy niż lub równy wartości zwracanej przez GetUpperBoundwartość .

Wartość zwracana

Odwołanie do elementu tablicy.

Uwagi

Służy do implementowania operatora przypisania po lewej stronie dla tablic.

Przykład

Zobacz przykład dla elementu GetSize.

`CArray::FreeExtra`

Zwalnia wszelkie dodatkowe pamięci przydzielone podczas powiększania tablicy.

void FreeExtra();

Uwagi

Ta funkcja nie ma wpływu na rozmiar lub górną granicę tablicy.

Przykład

Zobacz przykład dla elementu GetData.

`CArray::GetAt`

Zwraca element tablicy w określonym indeksie.

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

Parametry

TYPE
Parametr szablonu określający typ elementów tablicy.

nIndex
Indeks liczby całkowitej, który jest większy lub równy 0 i mniejszy niż lub równy wartości zwracanej przez GetUpperBoundwartość .

Wartość zwracana

Element tablicy obecnie w tym indeksie.

Uwagi

Przekazanie wartości ujemnej lub wartości większej niż wartość zwrócona przez GetUpperBound spowoduje niepowodzenie asercji.

Przykład

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`

Zwraca liczbę elementów tablicy.

INT_PTR GetCount() const;

Wartość zwracana

Liczba elementów w tablicy.

Uwagi

Wywołaj tę metodę, aby pobrać liczbę elementów w tablicy. Ponieważ indeksy są oparte na zera, rozmiar jest 1 większy niż największy indeks. Wywołanie tej metody spowoduje wygenerowanie tego samego wyniku co CArray::GetSize metoda.

Przykład

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`

Użyj tej funkcji składowej, aby uzyskać bezpośredni dostęp do elementów w tablicy.

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

Parametry

TYPE
Parametr szablonu określający typ elementów tablicy.

Wartość zwracana

Wskaźnik do elementu tablicy.

Uwagi

Jeśli żadne elementy nie są dostępne, GetData zwraca wartość null.

Chociaż bezpośredni dostęp do elementów tablicy może pomóc szybciej pracować, należy zachować ostrożność podczas wywoływania GetData; wszelkie błędy, które są wykonywane bezpośrednio, wpływają na elementy tablicy.

Przykład

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`

Zwraca rozmiar tablicy.

INT_PTR GetSize() const;

Uwagi

Ponieważ indeksy są oparte na zera, rozmiar jest 1 większy niż największy indeks. Wywołanie tej metody spowoduje wygenerowanie tego samego wyniku co CArray::GetCount metoda.

Przykład

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`

Zwraca bieżącą górną granicę tej tablicy.

INT_PTR GetUpperBound() const;

Uwagi

Ponieważ indeksy tablic są oparte na zerach, ta funkcja zwraca wartość 1 mniejszą niż GetSize.

Warunek GetUpperBound( ) = -1 wskazuje, że tablica nie zawiera żadnych elementów.

Przykład

Zobacz przykład dla elementu CArray::GetAt.

`CArray::InsertAt`

Pierwsza wersja InsertAt wstawia jeden element (lub wiele kopii elementu) w określonym indeksie w tablicy.

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

void InsertAt(
    INT_PTR nStartIndex,
    CArray* pNewArray);

Parametry

nIndex
Indeks liczby całkowitej, który może być większy niż wartość zwracana przez GetUpperBoundwartość .

ARG_TYPE
Parametr szablonu określający typ elementów w tej tablicy.

newElement
Element, który ma zostać umieszczony w tej tablicy.

nCount
Liczba wstawień tego elementu (wartość domyślna to 1).

nStartIndex
Indeks liczby całkowitej, który może być większy niż wartość zwracana przez GetUpperBoundwartość .

pNewArray
Kolejna tablica zawierająca elementy do dodania do tej tablicy.

Uwagi

W procesie przesuwa się w górę (zwiększając indeks) istniejący element w tym indeksie i przesuwa w górę wszystkie elementy nad nim.

Druga wersja wstawia wszystkie elementy z innej CArray kolekcji, począwszy od nStartIndex pozycji.

Natomiast SetAt funkcja zastępuje jeden określony element tablicy i nie przesuwa żadnych elementów.

Przykład

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

Określa, czy tablica jest pusta.

BOOL IsEmpty() const;

Wartość zwracana

Niezerowe, jeśli tablica nie zawiera żadnych elementów; w przeciwnym razie 0.

`CArray::operator []`

Te operatory indeksu dolnego są wygodnym zamiennikiem SetAt funkcji i GetAt .

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

Parametry

TYPE
Parametr szablonu określający typ elementów w tej tablicy.

nIndex
Indeks elementu do uzyskania dostępu.

Uwagi

Pierwszy operator, wywoływany dla tablic, które nie constsą , może być używany po prawej stronie (r-value) lub po lewej (l-wartość) instrukcji przypisania. Drugi, wywoływany dla const tablic, może być używany tylko po prawej stronie.

Wersja debugowania biblioteki potwierdza, czy indeks dolny (po lewej lub prawej stronie instrukcji przypisania) jest poza granicami.

Przykład

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`

Przenosi dane do nowego buforu, gdy tablica powinna rosnąć lub zmniejszać.

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

Parametry

pNewData
Nowy bufor dla tablicy elementów.

pData
Stara tablica elementów.

nCount
Liczba elementów w starej tablicy.

Uwagi

pNewData jest zawsze wystarczająco duży, aby przechowywać wszystkie pData elementy.

Implementacja CArray używa tej metody, aby skopiować stare dane do nowego buforu, gdy tablica powinna rosnąć lub zmniejszać (gdy SetSize lub FreeExtra są wywoływane). Domyślna implementacja po prostu kopiuje dane.

W przypadku tablic, w których element zawiera wskaźnik do jednego z własnych elementów członkowskich, lub inna struktura zawiera wskaźnik do jednego z elementów tablicy, wskaźniki nie są aktualizowane w postaci zwykłego kopiowania. W takim przypadku można poprawić wskaźniki, implementując specjalizację RelocateElements z odpowiednimi typami. Odpowiadasz również za kopiowanie danych.

`CArray::RemoveAll`

Usuwa wszystkie elementy z tej tablicy.

void RemoveAll();

Uwagi

Jeśli tablica jest już pusta, funkcja nadal działa.

Przykład

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`

Usuwa co najmniej jeden element rozpoczynający się od określonego indeksu w tablicy.

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

Parametry

nIndex
Indeks liczby całkowitej, który jest większy lub równy 0 i mniejszy niż lub równy wartości zwracanej przez GetUpperBoundwartość .

nCount
Liczba elementów do usunięcia.

Uwagi

W procesie przesuwa wszystkie elementy powyżej usuniętych elementów. Spowoduje to obniżenie górnej granicy tablicy, ale nie zwalnia pamięci.

Jeśli spróbujesz usunąć więcej elementów niż znajdują się w tablicy powyżej punktu usuwania, wówczas asercyjna wersja debugowania biblioteki.

Przykład

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`

Ustawia element tablicy w określonym indeksie.

void SetAt(INT_PTR nIndex, ARG_TYPE newElement);

Parametry

nIndex
Indeks liczby całkowitej, który jest większy lub równy 0 i mniejszy niż lub równy wartości zwracanej przez GetUpperBoundwartość .

ARG_TYPE
Parametr szablonu określający typ argumentów używanych do odwoływania się do elementów tablicy.

newElement
Nowa wartość elementu, która ma być przechowywana w określonej pozycji.

Uwagi

SetAt nie spowoduje wzrostu tablicy. Użyj SetAtGrow polecenia , jeśli chcesz, aby tablica automatycznie rosła.

Należy upewnić się, że wartość indeksu reprezentuje prawidłową pozycję w tablicy. Jeśli jest poza granicami, oznacza to, że wersja debugowania biblioteki jest asercyjna.

Przykład

Zobacz przykład dla elementu GetAt.

`CArray::SetAtGrow`

Ustawia element tablicy w określonym indeksie.

void SetAtGrow(INT_PTR nIndex, ARG_TYPE newElement);

Parametry

nIndex
Indeks liczby całkowitej, który jest większy lub równy 0.

ARG_TYPE
Parametr szablonu określający typ elementów w tablicy.

newElement
Element, który ma zostać dodany do tej tablicy. Dozwolona NULL jest wartość.

Uwagi

Tablica zwiększa się automatycznie, jeśli jest to konieczne (oznacza to, że górna granica jest dostosowana do nowego elementu).

Przykład

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

Określa rozmiar pustej lub istniejącej tablicy; przydziela pamięć w razie potrzeby.

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

Parametry

nNewSize
Nowy rozmiar tablicy (liczba elementów). Musi być większe lub równe 0.

nGrowBy
Minimalna liczba miejsc elementów do przydzielenia, jeśli wymagany jest wzrost rozmiaru.

Uwagi

Jeśli nowy rozmiar jest mniejszy niż stary, tablica zostanie obcięta i zostanie zwolniona wszystkie nieużywane pamięci.

Użyj tej funkcji, aby ustawić rozmiar tablicy przed rozpoczęciem korzystania z tablicy. Jeśli nie używasz polecenia SetSize, dodanie elementów do tablicy powoduje, że jest on często ponownie przydzielany i kopiowany. Częste reallokowanie i kopiowanie są nieefektywne i mogą fragmentować pamięć.

Parametr nGrowBy wpływa na wewnętrzną alokację pamięci, gdy tablica rośnie. Jego użycie nigdy nie ma wpływu na rozmiar tablicy zgłoszone przez GetSize i GetUpperBound. Jeśli jest używana wartość domyślna, MFC przydziela pamięć w sposób obliczony w celu uniknięcia fragmentacji pamięci i optymalizacji wydajności w większości przypadków.

Przykład

Zobacz przykład dla elementu GetData.

Zobacz też

Przykład MFC COLLECT
CObject Klasa
Wykres hierarchii
CObArray Klasa
Pomocnicy klasy kolekcji

CArray Klasa

Składnia

Parametry

Członkowie

Konstruktory publiczne

Metody publiczne

Operatory publiczne

Uwagi

Hierarchia dziedziczenia

Wymagania

CArray::Add

Parametry

Wartość zwracana

Uwagi

Przykład

CArray::Append

Parametry

Wartość zwracana

Uwagi

Przykład

CArray::CArray

Uwagi

Przykład

CArray::Copy

Parametry

Uwagi

Przykład

CArray::ElementAt

Parametry

Wartość zwracana

Uwagi

Przykład

CArray::FreeExtra

Uwagi

Przykład

CArray::GetAt

Parametry

Wartość zwracana

Uwagi

Przykład

CArray::GetCount

Wartość zwracana

Uwagi

Przykład

CArray::GetData

Parametry

Wartość zwracana

Uwagi

Przykład

CArray::GetSize

Uwagi

Przykład

CArray::GetUpperBound

Uwagi

Przykład

CArray::InsertAt

Parametry

Uwagi

Przykład

CArray::IsEmpty

Wartość zwracana

CArray::operator []

Parametry

Uwagi

Przykład

CArray::RelocateElements

Parametry

Uwagi

CArray::RemoveAll

Uwagi

Przykład

CArray::RemoveAt

Parametry

Uwagi

Przykład

CArray::SetAt

Parametry

Uwagi

Przykład

CArray::SetAtGrow

`CArray` Klasa

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