CAtlArray – třída

Tato třída implementuje objekt pole.

Syntaxe

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

Parametry

E
Typ dat, která mají být uložena v poli.

ETraits
Kód použitý ke kopírování nebo přesouvání prvků.

Členové

Metody

Function	Popis
Přidat	Voláním této metody přidáte prvek do objektu pole.
Připojit	Voláním této metody přidáte obsah jednoho pole na konec druhé.
AssertValid	Voláním této metody potvrďte platnost objektu pole.
CAtlArray	Konstruktor
~CAtlArray	Destruktor.
Kopírování	Voláním této metody zkopírujete prvky jednoho pole do druhého.
FreeExtra	Voláním této metody odeberete všechny prázdné prvky z pole.
GetAt	Voláním této metody načtěte jeden prvek z objektu pole.
GetCount	Voláním této metody vrátíte počet prvků uložených v poli.
GetData	Voláním této metody vrátíte ukazatel na první prvek v poli.
InsertArrayAt	Voláním této metody vložíte jedno pole do druhého.
InsertAt	Voláním této metody vložíte do objektu pole nový prvek (nebo více kopií elementu).
IsEmpty	Voláním této metody otestujete, zda je pole prázdné.
RemoveAll	Voláním této metody odeberete všechny prvky z objektu pole.
RemoveAt	Voláním této metody odeberete jeden nebo více prvků z pole.
Nastavit	Voláním této metody nastavíte hodnotu prvku v maticovém objektu.
SetAtGrow	Voláním této metody nastavíte hodnotu prvku v objektu pole a rozbalíte pole podle potřeby.
SetCount	Voláním této metody nastavíte velikost objektu pole.

Operátory

Operátor	Popis
operator []	Voláním tohoto operátoru vrátíte odkaz na prvek v poli.

Typedefs

Typedef	Popis
INARGTYPE	Datový typ, který se má použít pro přidání prvků do pole.
OUTARGTYPE	Datový typ, který se má použít pro načtení prvků z pole.

Poznámky

CAtlArray poskytuje metody pro vytváření a správu pole prvků uživatelem definovaného typu. I když se podobá standardním polím jazyka C, CAtlArray objekt se může dynamicky zmenšovat a podle potřeby zvětšit. Index pole vždy začíná na pozici 0 a horní mez lze opravit nebo povolit rozbalení při přidání nových prvků.

Pro pole s malým počtem prvků lze použít ATL třídy CSimpleArray .

CAtlArray úzce souvisí s třídou MFC CArray a bude pracovat v projektu MFC, i když bez podpory serializace.

Další informace naleznete v tématu ATL Collection Classes.

Požadavky

Hlavička: atlcoll.h

CAtlArray::Add

Voláním této metody přidáte prvek do objektu pole.

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

Parametry

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

Návratová hodnota

Vrátí index přidaného prvku.

Poznámky

Nový prvek se přidá na konec pole. Pokud není k dispozici žádný prvek, přidá se prázdný prvek; to znamená, že pole se zvětší, jako by byl přidán skutečný prvek. Pokud operace selže, atlThrow je volána s argumentem E_OUTOFMEMORY.

Příklad

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

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

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

Parametry

aSrc
Pole, které se má připojit.

Návratová hodnota

Vrátí index prvního připojeného prvku.

Poznámky

Prvky v zadaném poli se přidají na konec existujícího pole. V případě potřeby bude paměť přidělena tak, aby vyhovovala novým prvkům.

Matice musí být stejného typu a není možné k sobě připojit matici.

V buildech ladění bude vyvolán atlasSERT, pokud CAtlArray argument není platným polem nebo pokud aSrc odkazuje na stejný objekt. V buildech vydaných verzí můžou neplatné argumenty vést k nepředvídatelným chováním.

Příklad

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

Voláním této metody potvrďte platnost objektu pole.

void AssertValid() const;

Poznámky

Pokud objekt pole není platný, vyvolá ATLASSERT kontrolní výraz. Tato metoda je k dispozici pouze v případě, že je definována _DEBUG.

Příklad

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

CAtlArray::CAtlArray

Konstruktor

CAtlArray() throw();

Poznámky

Inicializuje objekt pole.

Příklad

CAtlArray<int> iArray;   

CAtlArray::~CAtlArray

Destruktor.

~CAtlArray() throw();

Poznámky

Uvolní všechny prostředky používané objektem pole.

CAtlArray::Copy

Voláním této metody zkopírujete prvky jednoho pole do druhého.

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

Parametry

aSrc
Zdroj elementů, které se mají zkopírovat do pole.

Poznámky

Voláním této metody přepíšete prvky jednoho pole prvky jiného pole. V případě potřeby bude paměť přidělena tak, aby vyhovovala novým prvkům. Prvky pole není možné kopírovat do sebe.

Pokud chcete zachovat existující obsah pole, použijte místo toho CAtlArray::Append .

V sestaveních ladění bude vyvolán ATLASSERT, pokud existující CAtlArray objekt není platný nebo pokud aSrc odkazuje na stejný objekt. V buildech vydaných verzí můžou neplatné argumenty vést k nepředvídatelným chováním.

Poznámka:

CAtlArray::Copy nepodporuje pole skládající se z elementů vytvořených pomocí CAutoPtr třídy.

Příklad

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

Voláním této metody odeberete všechny prázdné prvky z pole.

void FreeExtra() throw();

Poznámky

Všechny prázdné prvky se odeberou, ale velikost a horní mez pole zůstanou beze změny.

V ladicích buildech se vyvolá atlasSERT, pokud objekt CAtlArray není platný nebo pokud pole překročí jeho maximální velikost.

CAtlArray::GetAt

Voláním této metody načte jeden prvek z objektu pole.

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

Parametry

iElement
Hodnota indexu prvku pole, který se má vrátit.

Návratová hodnota

Vrátí odkaz na požadovaný prvek pole.

Poznámky

V ladicích buildech se vyvolá atlasSERT, pokud iElement překročí počet prvků v poli. V buildech vydaných verzí může neplatný argument vést k nepředvídatelným chováním.

Příklad

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

Voláním této metody vrátíte počet prvků uložených v poli.

size_t GetCount() const throw();

Návratová hodnota

Vrátí počet prvků uložených v poli.

Poznámky

Protože první prvek v poli je na pozici 0, hodnota vrácená GetCount vždy je 1 větší než největší index.

Příklad

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

CAtlArray::GetData

Voláním této metody vrátíte ukazatel na první prvek v poli.

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

Návratová hodnota

Vrátí ukazatel na umístění paměti, do které je uložen první prvek v poli. Pokud nejsou k dispozici žádné prvky, vrátí se hodnota NULL.

Příklad

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

Datový typ, který se má použít pro přidání prvků do pole.

typedef ETraits::INARGTYPE INARGTYPE;

CAtlArray::InsertArrayAt

Voláním této metody vložíte jedno pole do druhého.

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

Parametry

iStart
Index, na který má být pole vloženo.

paNew
Pole, které se má vložit.

Poznámky

Elementy z pole paNew se zkopírují do objektu pole počínaje elementem iStart. Existující prvky pole se přesunou, aby se nepřepsaly.

V sestaveních ladění bude vyvolán ATLASSERT, pokud CAtlArray objekt není platný nebo pokud je ukazatel paNew null nebo neplatný.

Poznámka:

CAtlArray::InsertArrayAt nepodporuje pole skládající se z elementů vytvořených pomocí CAutoPtr třídy.

Příklad

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

Voláním této metody vložíte do objektu pole nový prvek (nebo více kopií elementu).

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

Parametry

iElement
Index, do kterého se má prvek nebo prvky vložit.

element
Hodnota prvku nebo prvků, které se mají vložit.

nCount
Počet prvků, které chcete přidat.

Poznámky

Vloží jeden nebo více prvků do pole počínaje indexem iElement. Existující prvky se přesunou, aby se nepřepsaly.

V ladicím sestavení bude vyvolán ATLASSERT, pokud CAtlArray je objekt neplatný, počet prvků, které se mají přidat, je nula nebo kombinovaný počet prvků je příliš velký, aby pole obsahovalo. V maloobchodních buildech může předání neplatných parametrů způsobit nepředvídatelné výsledky.

Příklad

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

Voláním této metody otestujete, zda je pole prázdné.

bool IsEmpty() const throw();

Návratová hodnota

Vrátí hodnotu true, pokud je pole prázdné, jinak nepravda.

Poznámky

Pole je řečeno, že je prázdné, pokud neobsahuje žádné prvky. Proto i když pole obsahuje prázdné prvky, není prázdné.

Příklad

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

Voláním tohoto operátoru vrátíte odkaz na prvek v poli.

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

Parametry

iElement
Hodnota indexu prvku pole, který se má vrátit.

Návratová hodnota

Vrátí odkaz na požadovaný prvek pole.

Poznámky

Provede podobnou funkci jako CAtlArray::GetAt. Na rozdíl od třídy MFC CArray nelze tento operátor použít jako náhradu za CAtlArray::SetAt.

V sestaveních ladění bude vyvolána funkce ATLASSERT, pokud iElement překročí celkový počet prvků v poli. V maloobchodních buildech může neplatný parametr způsobit nepředvídatelné výsledky.

CAtlArray::OUTARGTYPE

Datový typ, který se má použít pro načtení prvků z pole.

typedef ETraits::OUTARGTYPE OUTARGTYPE;

CAtlArray::RemoveAll

Voláním této metody odeberete všechny prvky z objektu pole.

void RemoveAll() throw();

Poznámky

Odebere všechny prvky z objektu pole.

Tato metoda volá CAtlArray::SetCount změnit velikost pole a následně uvolní všechny přidělené paměti.

Příklad

Podívejte se na příklad pro CAtlArray::IsEmpty.

CAtlArray::RemoveAt

Voláním této metody odeberete jeden nebo více prvků z pole.

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

Parametry

iElement
Index prvního prvku, který chcete odebrat.

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

Poznámky

Odebere z pole jeden nebo více prvků. Všechny zbývající prvky jsou posunuty dolů. Horní mez je dekrementována, ale paměť není uvolněna, dokud se nevyvolá volání CAtlArray::FreeExtra .

V sestaveních ladění bude vyvolán ATLASSERT, pokud CAtlArray objekt není platný, nebo pokud kombinovaný součet iElement a nCount překročí celkový počet prvků v poli. V maloobchodních buildech můžou neplatné parametry způsobit nepředvídatelné výsledky.

Příklad

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

Voláním této metody nastavíte hodnotu prvku v maticovém objektu.

void SetAt(size_t iElement, INARGTYPE element);

Parametry

iElement
Index odkazující na prvek pole, který se má nastavit.

element
Nová hodnota zadaného prvku.

Poznámky

V ladicích buildech se vyvolá atlasSERT, pokud iElement překročí počet prvků v poli. V maloobchodních buildech může neplatný parametr vést k nepředvídatelným výsledkům.

Příklad

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

CAtlArray::SetCount

Voláním této metody nastavíte velikost objektu pole.

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

Parametry

nNewSize
Požadovaná velikost pole.

nGrowBy
Hodnota použitá k určení velikosti vyrovnávací paměti. Hodnota -1 způsobí, že se použije interně vypočítaná hodnota.

Návratová hodnota

Vrátí hodnotu true, pokud je pole úspěšně změněno, jinak nepravda.

Poznámky

Pole lze zvětšit nebo zmenšit. Při zvýšení se do pole přidají nadbytečné prázdné prvky. Pokud dojde ke snížení, odstraní se prvky s největšími indexy a uvolní paměť.

Tuto metodu použijte k nastavení velikosti pole před použitím. Pokud SetCount se nepoužije, proces přidání prvků a následné přidělení paměti sníží výkon a paměť fragmentů.

Příklad

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

CAtlArray::SetAtGrow

Voláním této metody nastavíte hodnotu prvku v objektu pole a rozbalíte pole podle potřeby.

void SetAtGrow(size_t iElement, INARGTYPE element);

Parametry

iElement
Index odkazující na prvek pole, který se má nastavit.

element
Nová hodnota zadaného prvku.

Poznámky

Nahradí hodnotu prvku, na který odkazuje index. Pokud je iElement větší než aktuální velikost pole, pole se automaticky zvýší pomocí volání CAtlArray::SetCount. V sestaveních ladění bude vyvolán ATLASSERT, pokud CAtlArray objekt není platný. V maloobchodních buildech můžou neplatné parametry způsobit nepředvídatelné výsledky.

Příklad

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

Viz také

Ukázka MMXSwarm
Ukázka DynamicConsumer
Ukázka updatePV
Ukázka výběru
CArray – třída
Přehled třídy