`CArray` 類別

發行項
10/12/2023

支援類似 C 陣列的陣列，但可以視需要動態減少和成長。

語法

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

參數

TYPE
樣板參數，指定儲存在陣列中的物件類型。 TYPE 是由傳 CArray 回的參數。

ARG_TYPE
樣板參數，指定用來存取陣列中儲存之物件的引數類型。通常為的 TYPE 參考。 ARG_TYPE 是傳遞至 CArray 的參數。

成員

公用建構函式

名稱	描述
`CArray::CArray`	建構空陣列。

公用方法

名稱	描述
`CArray::Add`	將項目加入至陣列結尾；必要時讓陣列增長。
`CArray::Append`	將另一個陣列附加至陣列;視需要增加陣列
`CArray::Copy`	將其他陣列複製到該陣列；必要時讓陣列成長。
`CArray::ElementAt`	傳回陣列中項目指標的臨時參考。
`CArray::FreeExtra`	釋放超過目前上限的所有未使用記憶體。
`CArray::GetAt`	傳回給定索引的值。
`CArray::GetCount`	取得此陣列中項目的數目。
`CArray::GetData`	容許存取陣列中的項目。可以是 `NULL`。
`CArray::GetSize`	取得此陣列中項目的數目。
`CArray::GetUpperBound`	傳回最大的有效索引。
`CArray::InsertAt`	在指定索引處插入項目 (或其他陣列中的所有項目)。
`CArray::IsEmpty`	判斷陣列是否為空白。
`CArray::RemoveAll`	從此陣列移除所有項目。
`CArray::RemoveAt`	移除特定索引處的項目。
`CArray::SetAt`	設定給定索引的值；不容許陣列成長。
`CArray::SetAtGrow`	設定給定索引的值；必要時讓陣列成長。
`CArray::SetSize`	設定此陣列中要包含的項目數目。

公用運算子

名稱	描述
`operator[]`	設定或取得指定索引處的項目。

備註

陣列索引一律從位置 0 開始。您可以決定是否要修正上限，或在新增超過目前系結的專案時，啟用陣列展開。即使某些元素為 Null，記憶體仍會連續配置至上限。

注意

調整物件大小 CArray 或將元素加入至物件的大部分方法，都會用來 memcpy_s 移動專案。這是個問題，因為 memcpy_s 與需要呼叫建構函式的任何物件不相容。如果中的 CArray 專案與不相容 memcpy_s ，您必須建立適當大小的新 CArray 專案。您接著 CArray::Copy 必須使用和 CArray::SetAt 來填入新的陣列，因為這些方法會使用指派運算子，而不是 memcpy_s 。

如同 C 陣列，索引元素的 CArray 存取時間是常數，而且與陣列大小無關。

提示

使用陣列之前，請先使用 SetSize 建立其大小，並為其配置記憶體。如果您未使用 SetSize，則將項目加入至陣列會導致其被頻繁地重新配置及複製。頻繁的重新配置及複製效率不高，且可能會讓記憶體分段。

如果您需要陣列中個別專案的傾印，則必須將物件的深度 CDumpContext 設定為 1 或更大。

這個類別的某些成員函式會呼叫全域協助程式函式，這些函式必須針對類別的大部分 CArray 用途進行自訂。請參閱 MFC 宏和全域一節中的集合類別協助程式主題。

陣列類別衍生就像清單衍生。

如需如何使用 CArray 的詳細資訊，請參閱集合一文。

繼承階層架構

CObject

CArray

需求

標頭：afxtempl.h

`CArray::Add`

將新元素新增至陣列結尾，將陣列成長為 1。

INT_PTR Add(ARG_TYPE newElement);

參數

ARG_TYPE
樣板參數，指定參考這個陣列中元素的引數類型。

newElement
要加入至這個陣列的專案。

傳回值

加入之專案的索引。

備註

如果 SetSize 已搭配 nGrowBy 大於 1 的值使用，則可以配置額外的記憶體。不過，上限只會增加 1。

範例

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

呼叫這個成員函式，將一個陣列的內容新增至另一個陣列的結尾。

INT_PTR Append(const CArray& src);

參數

src
要附加至陣列的專案來源。

傳回值

第一個附加專案的索引。

備註

陣列的類型必須相同。

如有必要， Append 可以配置額外的記憶體，以容納附加至陣列的專案。

範例

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`

建構空陣列。

CArray();

備註

陣列會一次成長一個專案。

範例

CArray<CPoint, CPoint> ptArray;

`CArray::Copy`

使用此成員函式，將一個陣列的專案複製到另一個陣列。

void Copy(const CArray& src);

參數

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

備註

呼叫這個成員函式，以使用另一個陣列的元素覆寫一個陣列的專案。

Copy 不會釋放記憶體;不過，如有必要， Copy 可能會配置額外的記憶體，以容納複製到陣列的專案。

範例

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`

傳回陣列中指定專案的暫存參考。

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

參數

nIndex
大於或等於 0 且小於或等於所 GetUpperBound 傳回值的整數索引。

傳回值

陣列專案的參考。

備註

它可用來實作陣列的左側指派運算子。

範例

請參閱的 GetSize 範例。

`CArray::FreeExtra`

釋放在陣列成長時所配置的任何額外記憶體。

void FreeExtra();

備註

此函式不會影響陣列的大小或上限。

範例

請參閱的 GetData 範例。

`CArray::GetAt`

傳回位於指定索引處的陣列專案。

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

參數

TYPE
指定陣列元素類型的樣板參數。

nIndex
大於或等於 0 且小於或等於所 GetUpperBound 傳回值的整數索引。

傳回值

目前在此索引處的陣列專案。

備註

傳遞負值或大於傳回 GetUpperBound 的值會導致判斷提示失敗。

範例

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`

傳回陣列專案的數目。

INT_PTR GetCount() const;

傳回值

陣列中的項目數目。

備註

呼叫此方法以擷取陣列中的專案數目。因為索引是以零起始，因此大小大於最大索引 1。呼叫此方法會產生與 CArray::GetSize 方法相同的結果。

範例

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`

使用此成員函式可直接存取陣列中的專案。

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

參數

TYPE
指定陣列元素類型的樣板參數。

傳回值

陣列專案的指標。

備註

如果沒有可用的專案， GetData 則傳回 Null 值。

雖然直接存取陣列的專案可協助您更快速地工作，但呼叫 GetData 時請小心;您所做的任何錯誤都會直接影響陣列的元素。

範例

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`

傳回陣列的大小。

INT_PTR GetSize() const;

備註

因為索引是以零起始，因此大小大於最大索引 1。呼叫此方法會產生與 CArray::GetCount 方法相同的結果。

範例

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`

傳回這個陣列目前的上限。

INT_PTR GetUpperBound() const;

備註

因為陣列索引是以零起始，因此此函式會傳回小於 GetSize 的值 1。

條件 GetUpperBound( ) = -1 表示陣列不包含任何元素。

範例

請參閱的 CArray::GetAt 範例。

`CArray::InsertAt`

的第一個版本 InsertAt 會在陣列中指定的索引處插入一個元素（或元素的多個複本）。

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

void InsertAt(
    INT_PTR nStartIndex,
    CArray* pNewArray);

參數

nIndex
整數索引，可能大於所 GetUpperBound 傳回的值。

ARG_TYPE
指定這個陣列中專案類型的樣板參數。

newElement
要置於這個陣列中的專案。

nCount
應該插入這個專案的次數（預設值為 1）。

nStartIndex
整數索引，可能大於所 GetUpperBound 傳回的值。

pNewArray
另一個陣列，其中包含要加入至這個陣列的專案。

備註

在此程式中，它會向上移位（藉由遞增索引）此索引的現有專案，並將它上方的所有元素向上移位。

第二個版本會從位置開始 nStartIndex ，插入另一個 CArray 集合中的所有專案。

相反地，函 SetAt 式會取代一個指定的陣列元素，而且不會移動任何元素。

範例

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

判斷陣列是否為空白。

BOOL IsEmpty() const;

傳回值

如果陣列不包含任何元素，則為非零;否則為 0。

`CArray::operator []`

這些下標運算子是和 GetAt 函 SetAt 式的便利替代專案。

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

參數

TYPE
指定這個陣列中專案類型的樣板參數。

nIndex
要存取之專案的索引。

備註

針對不是 const 的陣列呼叫的第一個運算子，可以在指派語句的右邊（r-value）或左（l-value）上使用。第二個針對陣列呼叫 const ，只能用於右側。

程式庫的 [偵錯] 版本會判斷提示下標（在指派語句的左邊或右側）超出界限。

範例

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`

當陣列應該成長或縮小時，將資料重新放置至新的緩衝區。

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

參數

pNewData
專案陣列的新緩衝區。

pData
專案的舊陣列。

nCount
舊陣列中的專案數目。

備註

pNewData 永遠夠大，足以保存所有 pData 元素。

實作會 CArray 使用這個方法，將舊資料複製到新的緩衝區，當陣列應該成長或縮小時（呼叫或 FreeExtra 時 SetSize ）。預設實作只會複製資料。

對於元素包含其其中一個成員指標的陣列，或另一個結構包含其中一個陣列元素的指標，則指標不會以純本更新。在此情況下，您可以實作具有相關類型的特製化 RelocateElements 來更正指標。您也必須負責資料複製。

`CArray::RemoveAll`

從此陣列移除所有項目。

void RemoveAll();

備註

如果陣列已經空白，函式仍可運作。

範例

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`

從陣列中指定的索引處開始移除一或多個元素。

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

參數

nIndex
大於或等於 0 且小於或等於所 GetUpperBound 傳回值的整數索引。

nCount
要移除的項目數目。

備註

在此程式中，它會向下移位移除專案上方的所有元素。它會遞減陣列的上限，但不會釋放記憶體。

如果您嘗試移除超過移除點上方陣列所包含的元素，則程式庫的偵錯版本會判斷提示。

範例

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`

設定位於指定索引處的陣列專案。

void SetAt(INT_PTR nIndex, ARG_TYPE newElement);

參數

nIndex
大於或等於 0 且小於或等於所 GetUpperBound 傳回值的整數索引。

ARG_TYPE
樣板參數，指定用於參考陣列元素的引數類型。

newElement
要儲存在指定位置的新專案值。

備註

SetAt 不會造成陣列成長。如果您想要讓陣列自動成長，請使用 SetAtGrow 。

您必須確定索引值代表陣列中的有效位置。如果超出界限，則程式庫的偵錯版本會判斷提示。

範例

請參閱的 GetAt 範例。

`CArray::SetAtGrow`

設定位於指定索引處的陣列專案。

void SetAtGrow(INT_PTR nIndex, ARG_TYPE newElement);

參數

nIndex
大於或等於 0 的整數索引。

ARG_TYPE
指定陣列中專案類型的樣板參數。

newElement
要加入至這個陣列的專案。 NULL允許值。

備註

陣列會在必要時自動成長（也就是調整上限以容納新元素）。

範例

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

建立空陣列或現有陣列的大小;視需要配置記憶體。

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

參數

nNewSize
新的陣列大小（元素數目）。必須大於或等於 0。

nGrowBy
如果需要增加大小，要配置的元素位置數目下限。

備註

如果新大小小於舊大小，則會截斷陣列，並釋放所有未使用的記憶體。

使用此函式來設定陣列的大小，再開始使用陣列。如果您未使用 SetSize，則將項目加入至陣列會導致其被頻繁地重新配置及複製。頻繁的重新配置及複製效率不高，且可能會讓記憶體分段。

參數 nGrowBy 會影響陣列成長時的內部記憶體配置。其使用永遠不會影響和 GetUpperBound 所 GetSize 報告的陣列大小。如果使用預設值，MFC 會以計算方式配置記憶體，以避免記憶體片段，並將大部分案例的效率優化。

範例

請參閱的 GetData 範例。

另請參閱

MFC 範例 COLLECT
CObject 類
 階層架構圖表
 CObArray 類
 集合類別協助程式

共用方式為

CArray 類別

語法

參數

成員

公用建構函式

公用方法

公用運算子

備註

繼承階層架構

需求

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

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