`CArray` Třída

Článek
10/12/2023

Podporuje pole, která jsou podobná polím jazyka C, ale může dynamicky snižovat a růst podle potřeby.

Syntaxe

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

Parametry

TYPE
Parametr šablony, který určuje typ objektů uložených v poli. TYPE je parametr vrácený parametrem CArray.

ARG_TYPE
Parametr šablony, který určuje typ argumentu, který se používá pro přístup k objektům uloženým v poli. Často odkaz na TYPE. ARG_TYPEje parametr, který je předán .CArray

Členové

Veřejné konstruktory

Název	Popis
`CArray::CArray`	Vytvoří prázdné pole.

Veřejné metody

Název	Popis
`CArray::Add`	Přidá prvek na konec pole; v případě potřeby pole zvětšuje.
`CArray::Append`	Připojí k matici další pole; v případě potřeby zvětšuje pole.
`CArray::Copy`	Zkopíruje další pole do pole; v případě potřeby pole zvětšuje.
`CArray::ElementAt`	Vrátí dočasný odkaz na ukazatel prvku v rámci pole.
`CArray::FreeExtra`	Uvolní veškerou nevyužitou paměť nad aktuální horní mez.
`CArray::GetAt`	Vrátí hodnotu v daném indexu.
`CArray::GetCount`	Získá počet prvků v tomto poli.
`CArray::GetData`	Umožňuje přístup k prvkům v poli. Může to být `NULL`.
`CArray::GetSize`	Získá počet prvků v tomto poli.
`CArray::GetUpperBound`	Vrátí největší platný index.
`CArray::InsertAt`	Vloží prvek (nebo všechny prvky v jiném poli) do zadaného indexu.
`CArray::IsEmpty`	Určuje, zda je pole prázdné.
`CArray::RemoveAll`	Odebere všechny prvky z tohoto pole.
`CArray::RemoveAt`	Odebere prvek v určitém indexu.
`CArray::SetAt`	Nastaví hodnotu pro daný index; pole nelze zvětšit.
`CArray::SetAtGrow`	Nastaví hodnotu pro daný index; v případě potřeby pole zvětšuje.
`CArray::SetSize`	Nastaví počet prvků, které mají být obsaženy v tomto poli.

Veřejné operátory

Název	Popis
`operator[]`	Nastaví nebo získá prvek v zadaném indexu.

Poznámky

Indexy pole vždy začínají na pozici 0. Můžete se rozhodnout, jestli chcete opravit horní mez, nebo povolit rozbalení pole, když přidáte prvky za aktuální vazbu. Paměť je přidělena souvisle horní mez, i když některé prvky mají hodnotu null.

Poznámka:

Většina metod, které mění velikost objektu CArray nebo přidávají prvky do objektu, slouží memcpy_s k přesunutí prvků. Jedná se o problém, protože memcpy_s není kompatibilní s žádnými objekty, které vyžadují, aby byl volána konstruktor. Pokud nejsou položky v souboru CArray kompatibilní memcpy_s, je nutné vytvořit novou CArray odpovídající velikost. Pak je nutné použít CArray::Copy a CArray::SetAt naplnit nové pole, protože tyto metody používají operátor přiřazení místo memcpy_s.

Stejně jako u pole jazyka C je doba přístupu indexovaného CArray prvku konstantní a je nezávislá na velikosti pole.

Tip

Před použitím pole použijte SetSize k vytvoření jeho velikosti a přidělení paměti. Pokud nepoužíváte SetSize, přidání prvků do pole způsobí, že se často relokuje a kopíruje. Časté relokace a kopírování jsou neefektivní a můžou fragmentovat paměť.

Pokud potřebujete výpis jednotlivých prvků v poli, musíte nastavit hloubku objektu CDumpContext na 1 nebo větší.

Některé členské funkce této třídy volají globální pomocné funkce, které musí být přizpůsobeny pro většinu použití CArray třídy. Viz téma Pomocné rutiny třídy kolekce v části Makra a globální knihovny MFC.

Odvození třídy pole je podobné odvození seznamu.

Další informace o použití CArraynaleznete v článku Kolekce.

Hierarchie dědičnosti

CObject

CArray

Požadavky

Záhlaví: afxtempl.h

`CArray::Add`

Přidá nový prvek na konec pole a zvětšuje matici o 1.

INT_PTR Add(ARG_TYPE newElement);

Parametry

ARG_TYPE
Parametr šablony určující typ argumentů odkazujících na elementy v tomto poli.

newElement
Prvek, který má být přidán do tohoto pole.

Návratová hodnota

Index přidaného prvku.

Poznámky

Pokud SetSize byla použita s nGrowBy hodnotou větší než 1, může být přidělena dodatečná paměť. Horní mez se však zvýší pouze o 1.

Příklad

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

Voláním této členské funkce přidáte obsah jednoho pole na konec druhé.

INT_PTR Append(const CArray& src);

Parametry

src
Zdroj prvků, které mají být připojeny k poli.

Návratová hodnota

Index prvního připojeného prvku.

Poznámky

Matice musí být stejného typu.

V případě potřeby Append může přidělit dodatečnou paměť pro přizpůsobení prvků připojených k poli.

Příklad

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`

Vytvoří prázdné pole.

CArray();

Poznámky

Pole najednou roste o jeden prvek.

Příklad

CArray<CPoint, CPoint> ptArray;

`CArray::Copy`

Tato členová funkce slouží ke zkopírování prvků jednoho pole do druhého.

void Copy(const CArray& src);

Parametry

src
Zdroj prvků, které se mají zkopírovat do pole.

Poznámky

Voláním této členské funkce přepíšete prvky jednoho pole prvky jiného pole.

Copy neuvolní paměť; V případě potřeby však může přidělit dodatečnou paměť pro Copy přizpůsobení prvků zkopírovaných do pole.

Příklad

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`

Vrátí dočasný odkaz na zadaný prvek v rámci pole.

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

Parametry

nIndex
Celočíselná hodnota, která je větší nebo rovna 0 a menší nebo rovna hodnotě GetUpperBoundvrácené hodnotou .

Návratová hodnota

Odkaz na prvek pole.

Poznámky

Slouží k implementaci operátoru přiřazení na levé straně pro pole.

Příklad

Podívejte se na příklad pro GetSize.

`CArray::FreeExtra`

Uvolní veškerou nadbytečnou paměť přidělenou při matici.

void FreeExtra();

Poznámky

Tato funkce nemá žádný vliv na velikost nebo horní mez pole.

Příklad

Podívejte se na příklad pro GetData.

`CArray::GetAt`

Vrátí prvek pole v zadaném indexu.

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

Parametry

TYPE
Parametr šablony určující typ prvků pole.

nIndex
Celočíselná hodnota, která je větší nebo rovna 0 a menší nebo rovna hodnotě GetUpperBoundvrácené hodnotou .

Návratová hodnota

Prvek pole, který je aktuálně v tomto indexu.

Poznámky

Předání záporné hodnoty nebo hodnoty větší než hodnota vrácená GetUpperBound výsledkem bude neúspěšný kontrolní výraz.

Příklad

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`

Vrátí počet prvků pole.

INT_PTR GetCount() const;

Návratová hodnota

Počet položek v poli

Poznámky

Voláním této metody načtěte počet prvků v poli. Vzhledem k tomu, že indexy jsou založené na nule, je velikost 1 větší než největší index. Voláním této metody se vygeneruje stejný výsledek jako metoda CArray::GetSize .

Příklad

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`

Pomocí této členské funkce získáte přímý přístup k prvkům v poli.

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

Parametry

TYPE
Parametr šablony určující typ prvků pole.

Návratová hodnota

Ukazatel na prvek pole.

Poznámky

Pokud nejsou k dispozici žádné prvky, GetData vrátí hodnotu null.

I když přímý přístup k prvkům pole vám může pomoct rychleji pracovat, při volání GetDatabuďte opatrní. Všechny chyby, které uděláte přímo, ovlivní prvky pole.

Příklad

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`

Vrátí velikost pole.

INT_PTR GetSize() const;

Poznámky

Vzhledem k tomu, že indexy jsou založené na nule, je velikost 1 větší než největší index. Voláním této metody se vygeneruje stejný výsledek jako metoda CArray::GetCount .

Příklad

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`

Vrátí aktuální horní mez tohoto pole.

INT_PTR GetUpperBound() const;

Poznámky

Vzhledem k tomu, že indexy pole jsou založené na nule, vrátí tato funkce hodnotu 1 menší než GetSize.

Podmínka GetUpperBound( ) = -1 označuje, že pole neobsahuje žádné prvky.

Příklad

Podívejte se na příklad pro CArray::GetAt.

`CArray::InsertAt`

První verze InsertAt vloží jeden prvek (nebo více kopií elementu) do zadaného indexu v poli.

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

void InsertAt(
    INT_PTR nStartIndex,
    CArray* pNewArray);

Parametry

nIndex
Celočíselné indexy, které mohou být větší než hodnota vrácená GetUpperBoundhodnotou .

ARG_TYPE
Parametr šablony určující typ prvků v tomto poli.

newElement
Prvek, který má být umístěn v tomto poli.

nCount
Počet vložení tohoto prvku (výchozí hodnota je 1).

nStartIndex
Celočíselné indexy, které mohou být větší než hodnota vrácená GetUpperBoundhodnotou .

pNewArray
Další pole, které obsahuje prvky, které mají být přidány do tohoto pole.

Poznámky

V procesu se posune nahoru (zvýšením indexu) existující prvek v tomto indexu a posune všechny prvky nad ním.

Druhá verze vloží všechny prvky z jiné CArray kolekce počínaje nStartIndex pozicí.

Funkce SetAt naproti tomu nahradí jeden zadaný prvek pole a nepřesouvají žádné prvky.

Příklad

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

Určuje, zda je pole prázdné.

BOOL IsEmpty() const;

Návratová hodnota

Nenulové, pokud pole neobsahuje žádné prvky; jinak 0.

`CArray::operator []`

Tyto operátory dolního indexu představují pohodlnou náhradu SetAt za funkce a GetAt funkce.

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

Parametry

TYPE
Parametr šablony určující typ prvků v tomto poli.

nIndex
Index prvku, ke který se má přistupovat.

Poznámky

První operátor, který volá pole, která nejsou const, lze použít na pravé straně (r-hodnota) nebo vlevo (l-hodnota) příkazu přiřazení. Druhý, volaný pro const pole, lze použít pouze na pravé straně.

Ladicí verze knihovny se používá, pokud je dolní index (na levé nebo pravé straně příkazu přiřazení) mimo hranice.

Příklad

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`

Přemísťuje data do nové vyrovnávací paměti, když by se pole mělo zvětšit nebo zmenšit.

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

Parametry

pNewData
Nová vyrovnávací paměť pro pole prvků.

pData
Původní pole prvků.

nCount
Počet prvků ve starém poli

Poznámky

pNewData je vždy dostatečně velký, aby držel všechny pData prvky.

Implementace CArray používá tuto metodu ke zkopírování starých dat do nové vyrovnávací paměti, když má pole zvětšit nebo zmenšit (když SetSize nebo FreeExtra jsou volána). Výchozí implementace pouze zkopíruje data.

Pro pole, ve kterých prvek obsahuje ukazatel na jeden z jeho vlastních členů, nebo jiná struktura obsahuje ukazatel na jeden z prvků pole, ukazatele nejsou aktualizovány ve formátu prosté kopie. V tomto případě můžete opravit ukazatele implementací specializace RelocateElements s příslušnými typy. Zodpovídáte také za kopírování dat.

`CArray::RemoveAll`

Odebere všechny prvky z tohoto pole.

void RemoveAll();

Poznámky

Pokud je pole již prázdné, funkce stále funguje.

Příklad

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`

Odebere jeden nebo více prvků počínaje zadaným indexem v poli.

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

Parametry

nIndex
Celočíselná hodnota, která je větší nebo rovna 0 a menší nebo rovna hodnotě GetUpperBoundvrácené hodnotou .

nCount
Počet prvků, které chcete odebrat.

Poznámky

V procesu se posune dolů všechny prvky nad odebranými elementy. Dekrementuje horní mez pole, ale nezvolní paměť.

Pokud se pokusíte odebrat více prvků, než je obsaženo v poli nad bodem odebrání, pak ladicí verze knihovny asserts.

Příklad

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`

Nastaví prvek pole v zadaném indexu.

void SetAt(INT_PTR nIndex, ARG_TYPE newElement);

Parametry

nIndex
Celočíselná hodnota, která je větší nebo rovna 0 a menší nebo rovna hodnotě GetUpperBoundvrácené hodnotou .

ARG_TYPE
Parametr šablony určující typ argumentů použitých pro odkazování na prvky pole.

newElement
Nová hodnota prvku, která má být uložena na zadané pozici.

Poznámky

SetAt nezpůsobí zvětšení pole. Použijte SetAtGrow , pokud chcete, aby se pole automaticky zvětšovat.

Je nutné zajistit, aby hodnota indexu představovala platnou pozici v poli. Pokud je mimo hranice, pak ladicí verze knihovny asserts.

Příklad

Podívejte se na příklad pro GetAt.

`CArray::SetAtGrow`

Nastaví prvek pole v zadaném indexu.

void SetAtGrow(INT_PTR nIndex, ARG_TYPE newElement);

Parametry

nIndex
Celočíselná hodnota, která je větší nebo rovna 0.

ARG_TYPE
Parametr šablony určující typ prvků v poli.

newElement
Prvek, který má být přidán do tohoto pole. Je povolená NULL hodnota.

Poznámky

Pole se v případě potřeby automaticky rozrůstá (to znamená, že horní mez se upraví tak, aby vyhovovala novému prvku).

Příklad

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

Vytvoří velikost prázdného nebo existujícího pole; v případě potřeby přidělí paměť.

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

Parametry

nNewSize
Nová velikost pole (počet prvků) Musí být větší než nebo rovno 0.

nGrowBy
Minimální počet slotů prvků, které se mají přidělit, pokud je potřeba zvětšit velikost.

Poznámky

Pokud je nová velikost menší než stará velikost, pole se zkrátí a uvolní se všechna nevyužitá paměť.

Tato funkce slouží k nastavení velikosti pole před tím, než začnete pole používat. Pokud nepoužíváte SetSize, přidání prvků do pole způsobí, že se často relokuje a kopíruje. Časté relokace a kopírování jsou neefektivní a můžou fragmentovat paměť.

Parametr nGrowBy má vliv na přidělení interní paměti, zatímco pole roste. Jeho použití nikdy neovlivní velikost pole, jak GetSize je hlášeno a GetUpperBound. Pokud se použije výchozí hodnota, knihovna MFC přidělí paměť způsobem vypočítaným způsobem, aby se zabránilo fragmentaci paměti a optimalizovala efektivitu ve většině případů.

Příklad

Podívejte se na příklad pro GetData.

Viz také

Mfc – ukázka COLLECT
CObject Třída
Graf hierarchie
CObArray Třída
Pomocné rutiny třídy kolekce

Sdílet prostřednictvím

CArray Třída

Syntaxe

Parametry

Členové

Veřejné konstruktory

Veřejné metody

Veřejné operátory

Poznámky

Hierarchie dědičnosti

Požadavky

CArray::Add

Parametry

Návratová hodnota

Poznámky

Příklad

CArray::Append

Parametry

Návratová hodnota

Poznámky

Příklad

CArray::CArray

Poznámky

Příklad

CArray::Copy

Parametry

Poznámky

Příklad

CArray::ElementAt

Parametry

Návratová hodnota

Poznámky

Příklad

CArray::FreeExtra

Poznámky

Příklad

CArray::GetAt

Parametry

Návratová hodnota

Poznámky

Příklad

CArray::GetCount

Návratová hodnota

Poznámky

Příklad

CArray::GetData

Parametry

Návratová hodnota

Poznámky

Příklad

CArray::GetSize

Poznámky

Příklad

CArray::GetUpperBound

Poznámky

Příklad

CArray::InsertAt

Parametry

Poznámky

Příklad

CArray::IsEmpty

Návratová hodnota

CArray::operator []

Parametry

Poznámky

Příklad

CArray::RelocateElements

Parametry

Poznámky

CArray::RemoveAll

Poznámky

Příklad

CArray::RemoveAt

Parametry

Poznámky

Příklad

CArray::SetAt

Parametry

Poznámky

Příklad

`CArray` Třída

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