CAtlArray 類別

發行項
10/12/2023

這個類別會實作陣列物件。

語法

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

參數

E
陣列中儲存之資料的類型。

ETraits
用來複製或移動元素的程式碼。

成員

方法

函式	描述
加入	呼叫這個方法，將專案加入至陣列物件。
附加	呼叫這個方法，將某個陣列的內容新增至另一個陣列的結尾。
AssertValid	呼叫此方法以確認陣列物件有效。
CAtlArray	建構函式。
~CAtlArray	解構函式。
複製	呼叫這個方法，將一個陣列的專案複製到另一個陣列。
FreeExtra	呼叫這個方法，以從陣列中移除任何空白元素。
GetAt	呼叫這個方法，從陣列物件擷取單一專案。
GetCount	呼叫這個方法可傳回儲存在陣列中的元素數目。
GetData	呼叫這個方法，以傳回陣列中第一個專案的指標。
InsertArrayAt	呼叫這個方法，將一個陣列插入另一個陣列。
InsertAt	呼叫這個方法，將新專案（或元素的多個複本）插入陣列物件。
IsEmpty	呼叫此方法以測試陣列是否為空白。
RemoveAll	呼叫這個方法，以從陣列物件中移除所有元素。
RemoveAt	呼叫這個方法，以從陣列中移除一或多個元素。
SetAt	呼叫這個方法，以設定陣列物件中的專案值。
SetAtGrow	呼叫這個方法以設定陣列物件中的專案值，並視需要擴充陣列。
SetCount	呼叫此方法以設定陣列物件的大小。

操作員

運算子	描述
`operator []`	呼叫這個運算子，以傳回陣列中專案的參考。

Typedefs

Typedef	描述
INARGTYPE	要用於將專案加入陣列的資料類型。
OUTARGTYPE	要用於從陣列擷取專案的資料類型。

備註

CAtlArray 提供建立和管理使用者定義型別元素陣列的方法。雖然類似于標準 C 陣列， CAtlArray 但物件可以視需要動態壓縮和成長。陣列索引一律從位置 0 開始，而且上限可以固定，或允許在加入新元素時展開。

對於具有少量元素的陣列，可以使用 ATL 類別 CSimpleArray 。

CAtlArray 與 MFC 的 CArray 類別密切相關，而且會在 MFC 專案中運作，儘管沒有序列化支援。

如需詳細資訊，請參閱 ATL 集合類別。

需求

標頭： atlcoll.h

CAtlArray：：Add

呼叫這個方法，將專案加入至陣列物件。

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

參數

元素
要加入至陣列的專案。

傳回值

傳回已加入專案的索引。

備註

新的元素會加入至陣列的結尾。如果未提供任何專案，則會加入空的專案;也就是說，陣列的大小會隨著實際元素的加入而增加。如果作業失敗，則會使用引數呼叫 AtlThrow E_OUTOFMEMORY。

範例

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

呼叫這個方法，將某個陣列的內容新增至另一個陣列的結尾。

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

參數

aSrc
要附加的陣列。

傳回值

傳回第一個附加專案的索引。

備註

提供陣列中的元素會新增至現有陣列的結尾。如有必要，將會配置記憶體以容納新的元素。

陣列的類型必須相同，而且無法將陣列附加至本身。

在偵錯組建中，如果 CAtlArray 引數不是有效的陣列，或是 aSrc 參考相同的物件，則會引發 ATLASSERT。在發行組建中，不正確引數可能會導致無法預期的行為。

範例

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

呼叫此方法以確認陣列物件有效。

void AssertValid() const;

備註

如果陣列物件無效，ATLASSERT 會擲回判斷提示。只有在定義_DEBUG時，才能使用這個方法。

範例

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

CAtlArray：：CAtlArray

建構函式。

CAtlArray() throw();

備註

初始化陣列物件。

範例

CAtlArray<int> iArray;

CAtlArray：：~CAtlArray

解構函式。

~CAtlArray() throw();

備註

釋放陣列物件使用的任何資源。

CAtlArray：：Copy

呼叫這個方法，將一個陣列的專案複製到另一個陣列。

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

參數

aSrc
要複製到陣列的專案來源。

備註

呼叫這個方法，以使用另一個陣列的元素覆寫一個陣列的專案。如有必要，將會配置記憶體以容納新的元素。無法將陣列的專案複製到本身。

如果要保留陣列的現有內容，請改用 CAtlArray：：Append 。

在偵錯組建中，如果現有 CAtlArray 物件無效，或 aSrc 參考相同的物件，則會引發 ATLASSERT。在發行組建中，不正確引數可能會導致無法預期的行為。

注意

CAtlArray::Copy 不支援由以 CAutoPtr 類別建立的元素所組成的陣列。

範例

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

呼叫這個方法，以從陣列中移除任何空白元素。

void FreeExtra() throw();

備註

移除任何空白元素，但陣列的大小和上限保持不變。

在偵錯組建中，如果 CAtlArray 物件無效，或陣列超過其大小上限，則會引發 ATLASSERT。

CAtlArray：：GetAt

呼叫這個方法，從陣列物件擷取單一專案。

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

參數

iElement
要傳回之陣列專案的索引值。

傳回值

傳回必要陣列專案的參考。

備註

在偵錯組建中，如果 iElement 超過陣列中的元素數目，則會引發 ATLASSERT。在發行組建中，不正確引數可能會導致無法預期的行為。

範例

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

呼叫這個方法可傳回儲存在陣列中的元素數目。

size_t GetCount() const throw();

傳回值

傳回儲存在陣列中的專案數目。

備註

當陣列中的第一個專案位於位置 0 時，所 GetCount 傳回的值一律大於最大索引。

範例

請參閱 CAtlArray：：GetAt 的範例。

CAtlArray：：GetData

呼叫這個方法，以傳回陣列中第一個專案的指標。

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

傳回值

傳回儲存陣列中第一個專案的記憶體位置指標。如果沒有可用的專案，則會傳回 Null。

範例

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

要用於將專案加入陣列的資料類型。

typedef ETraits::INARGTYPE INARGTYPE;

CAtlArray：：InsertArrayAt

呼叫這個方法，將一個陣列插入另一個陣列。

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

參數

iStart
要插入陣列的索引。

paNew
要插入的陣列。

備註

陣列 paNew 中的元素會複製到陣列物件，從元素 iStart 開始。會移動現有的陣列元素，以避免被覆寫。

在偵錯組建中，如果 CAtlArray 物件無效，或 paNew 指標為 Null 或無效， 則會引發 ATLASSERT。

注意

CAtlArray::InsertArrayAt 不支援由以 CAutoPtr 類別建立的元素所組成的陣列。

範例

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

呼叫這個方法，將新專案（或元素的多個複本）插入陣列物件。

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

參數

iElement
要插入專案或專案的索引。

元素
要插入之專案或專案的值。

nCount
要加入的專案數目。

備註

從索引 iElement 開始，將一或多個元素插入陣列中。現有的元素會移動以避免被覆寫。

在偵錯組建中，如果 CAtlArray 物件無效、要加入的元素數目為零，或結合的專案數目太大，陣列無法包含，則會引發 ATLASSERT。在零售組建中，傳遞不正確參數可能會導致無法預期的結果。

範例

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

呼叫此方法以測試陣列是否為空白。

bool IsEmpty() const throw();

傳回值

如果陣列是空的，則傳回 true，否則傳回 false。

備註

如果陣列不包含任何元素，則陣列會是空的。因此，即使陣列包含空白元素，它也不是空的。

範例

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

呼叫這個運算子，以傳回陣列中專案的參考。

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

參數

iElement
要傳回之陣列專案的索引值。

傳回值

傳回必要陣列專案的參考。

備註

執行與 CAtlArray：：GetAt 類似的函式。不同于 MFC 類別 CArray ，此運算子無法做為 CAtlArray：：SetAt 的替代專案。

在偵錯組建中，如果 iElement 超過陣列中的元素總數，則會引發 ATLASSERT。在零售組建中，不正確參數可能會導致無法預期的結果。

CAtlArray：：OUTARGTYPE

要用於從陣列擷取專案的資料類型。

typedef ETraits::OUTARGTYPE OUTARGTYPE;

CAtlArray：：RemoveAll

呼叫這個方法，以從陣列物件中移除所有元素。

void RemoveAll() throw();

備註

從陣列物件中移除所有專案。

這個方法會呼叫 CAtlArray：：SetCount 來調整陣列的大小，然後釋放任何配置的記憶體。

範例

請參閱 CAtlArray：：IsEmpty 的範例。

CAtlArray：：RemoveAt

呼叫這個方法，以從陣列中移除一或多個元素。

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

參數

iElement
要移除之第一個專案的索引。

nCount
要移除的項目數目。

備註

從陣列中移除一或多個元素。任何剩餘的元素會向下移位。上限會遞減，但在呼叫 CAtlArray：：FreeExtra 之前，不會釋放記憶體。

在偵錯組建中，如果 CAtlArray 物件無效，或是合併的 iElement 和 nCount 總計超過陣列中的元素總數，則會引發 ATLASSERT。在零售組建中，不正確參數可能會導致無法預期的結果。

範例

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

呼叫這個方法，以設定陣列物件中的專案值。

void SetAt(size_t iElement, INARGTYPE element);

參數

iElement
指向要設定之陣列專案的索引。

元素
指定專案的新值。

備註

在偵錯組建中，如果 iElement 超過陣列中的元素數目，則會引發 ATLASSERT。在零售組建中，不正確參數可能會導致無法預期的結果。

範例

請參閱 CAtlArray：：GetAt 的範例。

CAtlArray：：SetCount

呼叫此方法以設定陣列物件的大小。

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

參數

nNewSize
陣列的必要大小。

nGrowBy
值，用來判斷緩衝區的大小。值 -1 會導致使用內部計算值。

傳回值

如果陣列成功調整大小，則傳回 true，否則傳回 false。

備註

陣列的大小可以增加或減少。如果增加，則會將額外的空白元素新增至陣列。如果減少，則會刪除具有最大索引的專案，並釋放記憶體。

使用這個方法來設定陣列的大小，再使用它。如果未 SetCount 使用，則新增元素的程式以及執行的後續記憶體配置將會降低效能和片段記憶體。

範例

請參閱 CAtlArray：：GetData 的範例。

CAtlArray：：SetAtGrow

呼叫這個方法以設定陣列物件中的專案值，並視需要擴充陣列。

void SetAtGrow(size_t iElement, INARGTYPE element);

參數