Klasa CAtlArray

Ta klasa implementuje obiekt tablicy.

Składnia

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

Parametry

E
Typ danych, które mają być przechowywane w tablicy.

ETraits
Kod używany do kopiowania lub przenoszenia elementów.

Elementy członkowskie

Metody

Function	opis
Dodaj	Wywołaj tę metodę, aby dodać element do obiektu tablicy.
Dołączanie	Wywołaj tę metodę, aby dodać zawartość jednej tablicy na końcu innej.
AssertValid	Wywołaj tę metodę, aby potwierdzić, że obiekt tablicy jest prawidłowy.
CAtlArray	Konstruktor.
~CAtlArray	Destruktora.
kopia	Wywołaj tę metodę, aby skopiować elementy jednej tablicy do innej.
FreeExtra	Wywołaj tę metodę, aby usunąć wszystkie puste elementy z tablicy.
GetAt	Wywołaj tę metodę, aby pobrać pojedynczy element z obiektu tablicy.
GetCount	Wywołaj tę metodę, aby zwrócić liczbę elementów przechowywanych w tablicy.
GetData	Wywołaj tę metodę, aby zwrócić wskaźnik do pierwszego elementu w tablicy.
InsertArrayAt	Wywołaj tę metodę, aby wstawić jedną tablicę do innej.
Wstawat	Wywołaj tę metodę, aby wstawić nowy element (lub wiele kopii elementu) do obiektu tablicy.
IsEmpty	Wywołaj tę metodę, aby sprawdzić, czy tablica jest pusta.
Usuńwszystkie	Wywołaj tę metodę, aby usunąć wszystkie elementy z obiektu tablicy.
RemoveAt	Wywołaj tę metodę, aby usunąć jeden lub więcej elementów z tablicy.
SetAt	Wywołaj tę metodę, aby ustawić wartość elementu w obiekcie tablicy.
SetAtGrow	Wywołaj tę metodę, aby ustawić wartość elementu w obiekcie tablicy, rozwijając tablicę zgodnie z potrzebami.
SetCount	Wywołaj tę metodę, aby ustawić rozmiar obiektu tablicy.

Operatory

Operator	opis
operator []	Wywołaj ten operator, aby zwrócić odwołanie do elementu w tablicy.

Typedefs

Definicja typu	opis
INARGTYPE	Typ danych używany do dodawania elementów do tablicy.
OUTARGTYPE	Typ danych używany do pobierania elementów z tablicy.

Uwagi

CAtlArray Udostępnia metody tworzenia tablicy elementów typu zdefiniowanego przez użytkownika i zarządzania nimi. Mimo że jest to podobne do standardowych tablic języka C, CAtlArray obiekt może dynamicznie zmniejszać i rosnąć w razie potrzeby. Indeks tablicy zawsze zaczyna się od pozycji 0, a górna granica może być stała lub może być rozszerzana w miarę dodawania nowych elementów.

W przypadku tablic z niewielką liczbą elementów można użyć klasy ATL CSimpleArray .

CAtlArray jest ściśle związana CArray z klasą MFC i będzie działać w projekcie MFC, choć bez obsługi serializacji.

Aby uzyskać więcej informacji, zobacz Klasy kolekcji ATL.

Wymagania

Nagłówek: atlcoll.h

CAtlArray::Add

Wywołaj tę metodę, aby dodać element do obiektu tablicy.

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

Parametry

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

Wartość zwracana

Zwraca indeks dodanego elementu.

Uwagi

Nowy element jest dodawany na końcu tablicy. Jeśli nie podano żadnego elementu, zostanie dodany pusty element; oznacza to, że tablica jest zwiększana w rozmiarze, tak jakby został dodany rzeczywisty element. Jeśli operacja zakończy się niepowodzeniem, funkcja AtlThrow jest wywoływana z argumentem E_OUTOFMEMORY.

Przykład

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

Wywołaj tę metodę, aby dodać zawartość jednej tablicy na końcu innej.

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

Parametry

aSrc
Tablica do dołączenia.

Wartość zwracana

Zwraca indeks pierwszego dołączonego elementu.

Uwagi

Elementy w dostarczonej tablicy są dodawane na końcu istniejącej tablicy. W razie potrzeby pamięć zostanie przydzielona, aby pomieścić nowe elementy.

Tablice muszą być tego samego typu i nie można dołączyć tablicy do siebie.

W kompilacjach debugowania element ATLASSERT zostanie zgłoszony, jeśli CAtlArray argument nie jest prawidłową tablicą lub jeśli aSrc odwołuje się do tego samego obiektu. W kompilacjach wydania nieprawidłowe argumenty mogą prowadzić do nieprzewidywalnego zachowania.

Przykład

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

Wywołaj tę metodę, aby potwierdzić, że obiekt tablicy jest prawidłowy.

void AssertValid() const;

Uwagi

Jeśli obiekt tablicy jest nieprawidłowy, usługa ATLASSERT zgłosi asercja. Ta metoda jest dostępna tylko wtedy, gdy _DEBUG jest zdefiniowana.

Przykład

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

CAtlArray::CAtlArray

Konstruktor.

CAtlArray() throw();

Uwagi

Inicjuje obiekt tablicy.

Przykład

CAtlArray<int> iArray;   

CAtlArray::~CAtlArray

Destruktora.

~CAtlArray() throw();

Uwagi

Zwalnia wszystkie zasoby używane przez obiekt tablicy.

CAtlArray::Copy

Wywołaj tę metodę, aby skopiować elementy jednej tablicy do innej.

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

Parametry

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

Uwagi

Wywołaj tę metodę, aby zastąpić elementy jednej tablicy elementami innej tablicy. W razie potrzeby pamięć zostanie przydzielona, aby pomieścić nowe elementy. Nie można skopiować elementów tablicy do siebie.

Jeśli istniejąca zawartość tablicy ma zostać zachowana, zamiast tego użyj CAtlArray ::Append .

W kompilacjach debugowania obiekt ATLASSERT zostanie zgłoszony, jeśli istniejący CAtlArray obiekt jest nieprawidłowy lub jeśli obiekt aSrc odwołuje się do tego samego obiektu. W kompilacjach wydania nieprawidłowe argumenty mogą prowadzić do nieprzewidywalnego zachowania.

Uwaga

CAtlArray::Copy nie obsługuje tablic składających się z elementów utworzonych za pomocą klasy CAutoPtr .

Przykład

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

Wywołaj tę metodę, aby usunąć wszystkie puste elementy z tablicy.

void FreeExtra() throw();

Uwagi

Wszystkie puste elementy są usuwane, ale rozmiar i górna granica tablicy pozostają niezmienione.

W kompilacjach debugowania obiekt ATLASSERT zostanie zgłoszony, jeśli obiekt CAtlArray jest nieprawidłowy lub jeśli tablica przekroczy maksymalny rozmiar.

CAtlArray::GetAt

Wywołaj tę metodę, aby pobrać pojedynczy element z obiektu tablicy.

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

Parametry

Element i
Wartość indeksu elementu tablicy do zwrócenia.

Wartość zwracana

Zwraca odwołanie do wymaganego elementu tablicy.

Uwagi

W kompilacjach debugowania obiekt ATLASSERT zostanie zgłoszony, jeśli element iElement przekroczy liczbę elementów w tablicy. W kompilacjach wydania nieprawidłowy argument może prowadzić do nieprzewidywalnego zachowania.

Przykład

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

Wywołaj tę metodę, aby zwrócić liczbę elementów przechowywanych w tablicy.

size_t GetCount() const throw();

Wartość zwracana

Zwraca liczbę elementów przechowywanych w tablicy.

Uwagi

Ponieważ pierwszy element w tablicy znajduje się na pozycji 0, wartość zwracana przez GetCount wartość jest zawsze 1 większa niż największy indeks.

Przykład

Zobacz przykład CAtlArray ::GetAt.

CAtlArray::GetData

Wywołaj tę metodę, aby zwrócić wskaźnik do pierwszego elementu w tablicy.

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

Wartość zwracana

Zwraca wskaźnik do lokalizacji pamięci przechowującej pierwszy element w tablicy. Jeśli żadne elementy nie są dostępne, zwracana jest wartość NULL.

Przykład

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

Typ danych używany do dodawania elementów do tablicy.

typedef ETraits::INARGTYPE INARGTYPE;

CAtlArray::InsertArrayAt

Wywołaj tę metodę, aby wstawić jedną tablicę do innej.

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

Parametry

iStart
Indeks, w którym ma zostać wstawiona tablica.

paNew
Tablica do wstawienia.

Uwagi

Elementy z tablicy paNew są kopiowane do obiektu tablicy, począwszy od elementu iStart. Istniejące elementy tablicy są przenoszone, aby uniknąć zastępowania.

W kompilacjach debugowania obiekt ATLASSERT zostanie zgłoszony, jeśli CAtlArray obiekt jest nieprawidłowy lub jeśli wskaźnik paNew ma wartość NULL lub jest nieprawidłowy.

Uwaga

CAtlArray::InsertArrayAt nie obsługuje tablic składających się z elementów utworzonych za pomocą klasy CAutoPtr .

Przykład

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

Wywołaj tę metodę, aby wstawić nowy element (lub wiele kopii elementu) do obiektu tablicy.

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

Parametry

Element i
Indeks, w którym ma zostać wstawiony element lub elementy.

pierwiastek
Wartość elementu lub elementów do wstawienia.

nCount
Liczba elementów do dodania.

Uwagi

Wstawia jeden lub więcej elementów do tablicy, zaczynając od indeksu iElement. Istniejące elementy są przenoszone, aby uniknąć zastępowania.

W kompilacjach debugowania obiekt ATLASSERT zostanie zgłoszony, jeśli CAtlArray obiekt jest nieprawidłowy, liczba elementów do dodania wynosi zero lub łączna liczba elementów jest zbyt duża, aby tablica zawierała. W kompilacjach detalicznych przekazywanie nieprawidłowych parametrów może spowodować nieprzewidywalne wyniki.

Przykład

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

Wywołaj tę metodę, aby sprawdzić, czy tablica jest pusta.

bool IsEmpty() const throw();

Wartość zwracana

Zwraca wartość true, jeśli tablica jest pusta, w przeciwnym razie wartość false.

Uwagi

Tablica jest pusta, jeśli nie zawiera żadnych elementów. Dlatego nawet jeśli tablica zawiera puste elementy, nie jest pusta.

Przykład

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

Wywołaj ten operator, aby zwrócić odwołanie do elementu w tablicy.

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

Parametry

Element i
Wartość indeksu elementu tablicy do zwrócenia.

Wartość zwracana

Zwraca odwołanie do wymaganego elementu tablicy.

Uwagi

Wykonuje podobną funkcję do CAtlArray::GetAt. W przeciwieństwie do klasy MFC CArray, ten operator nie może być używany jako zamiennik CAtlArray::SetAt.

W kompilacjach debugowania obiekt ATLASSERT zostanie zgłoszony, jeśli element iElement przekroczy całkowitą liczbę elementów w tablicy. W kompilacjach detalicznych nieprawidłowy parametr może powodować nieprzewidywalne wyniki.

CAtlArray::OUTARGTYPE

Typ danych używany do pobierania elementów z tablicy.

typedef ETraits::OUTARGTYPE OUTARGTYPE;

CAtlArray::RemoveAll

Wywołaj tę metodę, aby usunąć wszystkie elementy z obiektu tablicy.

void RemoveAll() throw();

Uwagi

Usuwa wszystkie elementy z obiektu tablicy.

Ta metoda wywołuje metodę CAtlArray::SetCount , aby zmienić rozmiar tablicy, a następnie zwolni wszelkie przydzielone pamięci.

Przykład

Zobacz przykład CAtlArray ::IsEmpty.

CAtlArray::RemoveAt

Wywołaj tę metodę, aby usunąć jeden lub więcej elementów z tablicy.

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

Parametry

Element i
Indeks pierwszego elementu do usunięcia.

nCount
Liczba elementów do usunięcia.

Uwagi

Usuwa jeden lub więcej elementów z tablicy. Wszystkie pozostałe elementy są przesunięte w dół. Górna granica jest dekrementowana, ale pamięć nie zostanie zwolniona, dopóki nie zostanie wykonane wywołanie metody CAtlArray::FreeExtra .

W kompilacjach debugowania obiekt ATLASSERT zostanie zgłoszony, jeśli CAtlArray obiekt jest nieprawidłowy lub łączna suma elementów iElement i nCount przekracza łączną liczbę elementów w tablicy. W kompilacjach detalicznych nieprawidłowe parametry mogą powodować nieprzewidywalne wyniki.

Przykład

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

Wywołaj tę metodę, aby ustawić wartość elementu w obiekcie tablicy.

void SetAt(size_t iElement, INARGTYPE element);

Parametry

Element i
Indeks wskazujący element tablicy do ustawienia.

pierwiastek
Nowa wartość określonego elementu.

Uwagi

W kompilacjach debugowania obiekt ATLASSERT zostanie zgłoszony, jeśli element iElement przekroczy liczbę elementów w tablicy. W kompilacjach detalicznych nieprawidłowy parametr może spowodować nieprzewidywalne wyniki.

Przykład

Zobacz przykład CAtlArray ::GetAt.

CAtlArray::SetCount

Wywołaj tę metodę, aby ustawić rozmiar obiektu tablicy.

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

Parametry

nNewSize
Wymagany rozmiar tablicy.

nGrowBy
Wartość używana do określenia, jak duży ma być bufor. Wartość -1 powoduje, że używana jest wewnętrzna wartość obliczeniowa.

Wartość zwracana

Zwraca wartość true, jeśli rozmiar tablicy został pomyślnie zmieniony, w przeciwnym razie wartość false.

Uwagi

Tablicę można zwiększyć lub zmniejszyć. W przypadku zwiększenia dodatkowe puste elementy są dodawane do tablicy. Jeśli zostanie zmniejszona, elementy o największych indeksach zostaną usunięte, a pamięć zostanie zwolniona.

Użyj tej metody, aby ustawić rozmiar tablicy przed jej użyciem. Jeśli SetCount nie jest używany, proces dodawania elementów — i kolejnej alokacji pamięci — zmniejszy wydajność i pamięć fragmentu.

Przykład

Zobacz przykład CAtlArray ::GetData.

CAtlArray::SetAtGrow

Wywołaj tę metodę, aby ustawić wartość elementu w obiekcie tablicy, rozwijając tablicę zgodnie z potrzebami.

void SetAtGrow(size_t iElement, INARGTYPE element);

Parametry

Element i
Indeks wskazujący element tablicy do ustawienia.

pierwiastek
Nowa wartość określonego elementu.

Uwagi

Zamienia wartość elementu wskazywanego przez indeks. Jeśli parametr iElement jest większy niż bieżący rozmiar tablicy, tablica zostanie automatycznie zwiększona przy użyciu wywołania metody CAtlArray::SetCount. W kompilacjach debugowania obiekt ATLASSERT zostanie zgłoszony, jeśli CAtlArray obiekt jest nieprawidłowy. W kompilacjach detalicznych nieprawidłowe parametry mogą powodować nieprzewidywalne wyniki.

Przykład

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

Zobacz też

Przykład MMXSwarm
Przykład DynamicConsumer
Przykład updatePV
Przykład markizy
Klasa CArray
Omówienie klasy