`CObArray` 類別

發行項
10/12/2023

支援 CObject 指標的陣列。

語法

class CObArray : public CObject

成員

公用建構函式

名稱	描述
`CObArray::CObArray`	建構指標的 `CObject` 空陣列。

公用方法

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

公用運算子

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

備註

這些物件陣列類似于 C 陣列，但可以視需要動態壓縮和成長。

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

在 Win32 下 CObArray ，物件的大小僅限於可用的記憶體。

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

CObArray 引入 IMPLEMENT_SERIAL 巨集，以支援其項目的序列化和傾印。如果指標陣列 CObject 儲存至封存，使用多載插入運算子或成員 Serialize 函式，則每個 CObject 元素會隨著其陣列索引一起序列化。

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

CObArray刪除物件時，或移除其專案時，只會 CObject 移除指標，而不是它們參考的物件。

注意

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

陣列類別衍生類似于清單衍生。如需衍生特殊用途清單類別的詳細資料，請參閱集合一文。

注意

如果您想要序列化陣列，則必須在衍生類別的實作中使用 IMPLEMENT_SERIAL 宏。

繼承階層架構

CObject

CObArray

需求

標頭：afxcoll.h

`CObArray::Add`

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

INT_PTR Add(CObject* newElement);

參數

newElement
要 CObject 加入至這個陣列的指標。

傳回值

加入之專案的索引。

備註

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

下表顯示類似 CObArray::Add 的其他成員函式。

類別	成員函式
`CByteArray`	`INT_PTR Add(BYTE newElement);` `throw(CMemoryException*);`
`CDWordArray`	`INT_PTR Add(DWORD newElement);` `throw(CMemoryException*);`
`CPtrArray`	`INT_PTR Add(void* newElement);` `throw(CMemoryException*);`
`CStringArray`	`INT_PTR Add(LPCTSTR newElement); throw(CMemoryException*);` `INT_PTR Add(const CString& newElement);`
`CUIntArray`	`INT_PTR Add(UINT newElement);` `throw(CMemoryException*);`
`CWordArray`	`INT_PTR Add(WORD newElement);` `throw(CMemoryException*);`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray arr;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
#ifdef _DEBUG
   afxDump.SetDepth(1);
   afxDump << _T("Add example: ") << &arr << _T("\n");
#endif

此程式的結果如下所示：

Add example: A CObArray with 2 elements
[0] = a CAge at $442A 21
[1] = a CAge at $4468 40

`CObArray::Append`

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

INT_PTR Append(const CObArray& src);

參數

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

傳回值

第一個附加專案的索引。

備註

陣列的類型必須相同。

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

下表顯示類似 CObArray::Append 的其他成員函式。

類別	成員函式
`CByteArray`	`INT_PTR Append(const CByteArray& src);`
`CDWordArray`	`INT_PTR Append(const CDWordArray& src);`
`CPtrArray`	`INT_PTR Append(const CPtrArray& src);`
`CStringArray`	`INT_PTR Append(const CStringArray& src);`
`CUIntArray`	`INT_PTR Append(const CUIntArray& src);`
`CWordArray`	`INT_PTR Append(const CWordArray& src);`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray myArray1, myArray2;

// Add elements to the second array.
myArray2.Add(new CAge(21));
myArray2.Add(new CAge(42));

// Add elements to the first array and also append the second array.
myArray1.Add(new CAge(3));
myArray1.Append(myArray2);

#ifdef _DEBUG
   afxDump.SetDepth(1);
   afxDump << _T("myArray1: ") << &myArray1 << _T("\n");
   afxDump << _T("myArray2: ") << &myArray2 << _T("\n");
#endif

`CObArray::Copy`

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

void Copy(const CObArray& src);

參數

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

備註

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

下表顯示類似 CObArray::Copy 的其他成員函式。

類別	成員函式
`CByteArray`	`void Copy(const CByteArray& src);`
`CDWordArray`	`void Copy(const CDWordArray& src);`
`CPtrArray`	`void Copy(const CPtrArray& src);`
`CStringArray`	`void Copy(const CStringArray& src);`
`CUIntArray`	`void Copy(const CUIntArray& src);`
`CWordArray`	`void Copy(const CWordArray& src);`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray myArray1, myArray2;

// Add elements to the second array.
myArray2.Add(new CAge(21));
myArray2.Add(new CAge(42));

// Copy the elements from the second array to the first.
myArray1.Copy(myArray2);

#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << "myArray1: " << &myArray1 << "\n";
afxDump << "myArray2: " << &myArray2 << "\n";
#endif

`CObArray::CObArray`

建構空 CObject 的指標陣列。

CObArray();

備註

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

下表顯示其他類似 CObArray::CObArray 的建構函式。

類別	建構函式
`CByteArray`	`CByteArray();`
`CDWordArray`	`CDWordArray();`
`CPtrArray`	`CPtrArray();`
`CStringArray`	`CStringArray();`
`CUIntArray`	`CUIntArray();`
`CWordArray`	`CWordArray();`

範例

CObArray arr; //Array with default blocksize
CObArray* pArray = new CObArray; //Array on the heap with default blocksize

`CObArray::ElementAt`

傳回陣列中項目指標的臨時參考。

CObject*& ElementAt(INT_PTR nIndex);

參數

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

傳回值

指標的 CObject 參考。

備註

它用來實作陣列的左側指派運算子。這是進階函式，應該只用來實作特殊的陣列運算子。

下表顯示類似 CObArray::ElementAt 的其他成員函式。

類別	成員函式
`CByteArray`	`BYTE& ElementAt(INT_PTR nIndex);`
`CDWordArray`	`DWORD& ElementAt(INT_PTR nIndex);`
`CPtrArray`	`void*& ElementAt(INT_PTR nIndex);`
`CStringArray`	`CString& ElementAt(INT_PTR nIndex);`
`CUIntArray`	`UINT& ElementAt(INT_PTR nIndex);`
`CWordArray`	`WORD& ElementAt(INT_PTR nIndex);`

範例

請參閱的 CObArray::GetSize 範例。

`CObArray::FreeExtra`

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

void FreeExtra();

備註

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

下表顯示類似 CObArray::FreeExtra 的其他成員函式。

類別	成員函式
`CByteArray`	`void FreeExtra();`
`CDWordArray`	`void FreeExtra();`
`CPtrArray`	`void FreeExtra();`
`CStringArray`	`void FreeExtra();`
`CUIntArray`	`void FreeExtra();`
`CWordArray`	`void FreeExtra();`

範例

請參閱的 CObArray::GetData 範例。

`CObArray::GetAt`

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

CObject* GetAt(INT_PTR nIndex) const;

參數

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

傳回值

目前在此索引處的 CObject 指標專案。

備註

注意

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

下表顯示類似 CObArray::GetAt 的其他成員函式。

類別	成員函式
`CByteArray`	`BYTE GetAt(INT_PTR nIndex) const;`
`CDWordArray`	`DWORD GetAt(INT_PTR nIndex) const;`
`CPtrArray`	`void* GetAt(INT_PTR nIndex) const;`
`CStringArray`	`const CString& GetAt(INT_PTR nIndex) const;`
`CUIntArray`	`UINT GetAt(INT_PTR nIndex) const;`
`CWordArray`	`WORD GetAt(INT_PTR nIndex) const;`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray arr;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
ASSERT(*(CAge*) arr.GetAt(0) == CAge(21));

`CObArray::GetCount`

傳回陣列專案的數目。

INT_PTR GetCount() const;

傳回值

陣列中的項目數目。

備註

呼叫此方法以擷取陣列中的專案數目。因為索引是以零起始，因此大小大於最大索引 1。

下表顯示類似 CObArray::GetCount 的其他成員函式。

類別	成員函式
`CByteArray`	`INT_PTR GetCount() const;`
`CDWordArray`	`INT_PTR GetCount() const;`
`CPtrArray`	`INT_PTR GetCount() const;`
`CStringArray`	`INT_PTR GetCount() const;`
`CUIntArray`	`INT_PTR GetCount() const;`
`CWordArray`	`INT_PTR GetCount() const;`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
   myArray.Add(new CAge(i));

// Add 100 to all the elements of the array.
for (int i = 0; i < myArray.GetCount(); i++)
{
   CAge*& pAge = (CAge*&) myArray.ElementAt(i);
   delete pAge;
   pAge = new CAge(100 + i);
}

`CObArray::GetData`

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

const CObject** GetData() const;

CObject** GetData();

傳回值

指標陣列的 CObject 指標。

備註

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

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

下表顯示類似 CObArray::GetData 的其他成員函式。

類別	成員函式
CByteArray	`const BYTE* GetData() const; BYTE* GetData();`
CDWordArray	`const DWORD* GetData() const; DWORD* GetData();`
CPtrArray	`const void GetData() const; void GetData();`
CStringArray	`const CString* GetData() const; CString* GetData();`
CUIntArray	`const UINT* GetData() const; UINT* GetData();`
CWordArray	`const WORD* GetData() const; WORD* GetData();`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray myArray;

// Allocate memory for at least 32 elements.
myArray.SetSize(32, 128);

// Add elements to the array.
CAge** ppAge = (CAge * *)myArray.GetData();
for (int i = 0; i < 32; i++, ppAge++)
   * ppAge = new CAge(i);

// Only keep first 5 elements and free extra (unused) bytes.
for (int i = 5; i < myArray.GetCount(); i++)
{
   delete myArray[i]; // free objects before resetting array size.         
}
myArray.SetSize(5, 128);
myArray.FreeExtra(); // only frees pointers.

#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("myArray: ") << &myArray << _T("\n");
#endif

`CObArray::GetSize`

傳回陣列的大小。

INT_PTR GetSize() const;

備註

由於索引是以零起始，因此大小大於最大索引 1。

下表顯示類似 CObArray::GetSize 的其他成員函式。

類別	成員函式
`CByteArray`	`INT_PTR GetSize() const;`
`CDWordArray`	`INT_PTR GetSize() const;`
`CPtrArray`	`INT_PTR GetSize() const;`
`CStringArray`	`INT_PTR GetSize() const;`
`CUIntArray`	`INT_PTR GetSize() const;`
`CWordArray`	`INT_PTR GetSize() const;`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
   myArray.Add(new CAge(i));

// Add 100 to all the elements of the array.
for (int i = 0; i < myArray.GetSize(); i++)
{
   CAge*& pAge = (CAge * &)myArray.ElementAt(i);
   delete pAge;
   pAge = new CAge(100 + i);
}

#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("myArray: ") << &myArray << _T("\n");
#endif

`CObArray::GetUpperBound`

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

INT_PTR GetUpperBound() const;

傳回值

上限的索引（以零起始）。

備註

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

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

下表顯示類似 CObArray::GetUpperBound 的其他成員函式。

類別	成員函式
`CByteArray`	`INT_PTR GetUpperBound() const;`
`CDWordArray`	`INT_PTR GetUpperBound() const;`
`CPtrArray`	`INT_PTR GetUpperBound() const;`
`CStringArray`	`INT_PTR GetUpperBound() const;`
`CUIntArray`	`INT_PTR GetUpperBound() const;`
`CWordArray`	`INT_PTR GetUpperBound() const;`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray arr;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
ASSERT(arr.GetUpperBound() == 1); // Largest index

`CObArray::InsertAt`

在指定索引處插入項目 (或其他陣列中的所有項目)。

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

void InsertAt(
    INT_PTR nStartIndex,
    CObArray* pNewArray);

參數

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

newElement
要 CObject 放置在這個陣列中的指標。 newElement允許值為 NULL 的。

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

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

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

備註

的第一個版本 InsertAt 會在陣列中指定的索引處插入一個元素（或元素的多個複本）。在此程式中，它會向上移位（藉由遞增索引）此索引的現有專案，並將它上方的所有元素向上移位。

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

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

下表顯示類似 CObArray::InsertAt 的其他成員函式。

類別	成員函式
`CByteArray`	`void InsertAt(INT_PTR nIndex, BYTE newElement, int nCount = 1);` `throw(CMemoryException);` `void InsertAt(INT_PTR nStartIndex, CByteArray pNewArray);` `throw(CMemoryException*);`
`CDWordArray`	`void InsertAt(INT_PTR nIndex, DWORD newElement, int nCount = 1);` `throw(CMemoryException);` `void InsertAt(INT_PTR nStartIndex, CDWordArray pNewArray);` `throw(CMemoryException*);`
`CPtrArray`	`void InsertAt(INT_PTR nIndex, void* newElement, int nCount = 1);` `throw(CMemoryException);` `void InsertAt(INT_PTR nStartIndex, CPtrArray pNewArray);` `throw(CMemoryException*);`
`CStringArray`	`void InsertAt(INT_PTR nIndex, LPCTSTR newElement, int nCount = 1);` `throw(CMemoryException);` `void InsertAt(INT_PTR nStartIndex, CStringArray pNewArray);` `throw(CMemoryException*);`
`CUIntArray`	`void InsertAt(INT_PTR nIndex, UINT newElement, int nCount = 1);` `throw(CMemoryException);` `void InsertAt(INT_PTR nStartIndex, CUIntArray pNewArray);` `throw(CMemoryException*);`
`CWordArray`	`void InsertAt(INT_PTR nIndex, WORD newElement, int nCount = 1);` `throw(CMemoryException);` `void InsertAt(INT_PTR nStartIndex, CWordArray pNewArray);` `throw(CMemoryException*);`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray arr;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1 (will become 2).
arr.InsertAt(1, new CAge(30));  // New element 1
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("InsertAt example: ") << &arr << _T("\n");
#endif

此程式的結果如下所示：

InsertAt example: A CObArray with 3 elements
[0] = a CAge at $45C8 21
[1] = a CAge at $4646 30
[2] = a CAge at $4606 40

`CObArray::IsEmpty`

判定陣列是否是空的。

BOOL IsEmpty() const;

傳回值

如果陣列是空的，則為非零;否則為 0。

`CObArray::operator [ ]`

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

CObject*& operator[](int_ptr nindex);
CObject* operator[](int_ptr nindex) const;

備註

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

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

下表顯示其他類似 CObArray::operator [] 的運算子。

類別	運算子
`CByteArray`	`BYTE& operator [](INT_PTR nindex);` `BYTE operator [](INT_PTR nindex) const;`
`CDWordArray`	`DWORD& operator [](INT_PTR nindex);` `DWORD operator [](INT_PTR nindex) const;`
`CPtrArray`	`void& operator [](INT_PTR nindex);` `void operator [](INT_PTR nindex) const;`
`CStringArray`	`CString& operator [](INT_PTR nindex);` `CString operator [](INT_PTR nindex) const;`
`CUIntArray`	`UINT& operator [](INT_PTR nindex);` `UINT operator [](INT_PTR nindex) const;`
`CWordArray`	`WORD& operator [](INT_PTR nindex);` `WORD operator [](INT_PTR nindex) const;`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray arr;
CAge* pa;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
pa = (CAge*)arr[0]; // Get element 0
ASSERT(*pa == CAge(21)); // Get element 0
arr[0] = new CAge(30); // Replace element 0
delete pa;
ASSERT(*(CAge*)arr[0] == CAge(30)); // Get new element 0

`CObArray::RemoveAll`

從這個陣列移除所有指標，但實際上不會刪除 CObject 物件。

void RemoveAll();

備註

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

函 RemoveAll 式會釋放用於指標儲存體的所有記憶體。

下表顯示類似 CObArray::RemoveAll 的其他成員函式。

類別	成員函式
`CByteArray`	`void RemoveAll();`
`CDWordArray`	`void RemoveAll();`
`CPtrArray`	`void RemoveAll();`
`CStringArray`	`void RemoveAll();`
`CUIntArray`	`void RemoveAll();`
`CWordArray`	`void RemoveAll();`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray arr;
CAge* pa1;
CAge* pa2;

arr.Add(pa1 = new CAge(21)); // Element 0
arr.Add(pa2 = new CAge(40)); // Element 1
ASSERT(arr.GetSize() == 2);
arr.RemoveAll(); // Pointers removed but objects not deleted.
ASSERT(arr.GetSize() == 0);
delete pa1;
delete pa2;  // Cleans up memory.

`CObArray::RemoveAt`

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

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

參數

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

nCount
要移除的項目數目。

備註

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

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

函 RemoveAt 式會 CObject 從陣列中移除指標，但不會刪除物件本身。

下表顯示類似 CObArray::RemoveAt 的其他成員函式。

類別	成員函式
`CByteArray`	`void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);`
`CDWordArray`	`void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);`
CPtrArray	`void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);`
`CStringArray`	`void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);`
`CUIntArray`	`void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);`
`CWordArray`	`void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray arr;
CObject* pa;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
if ((pa = arr.GetAt(0)) != NULL)
{
   arr.RemoveAt(0);  // Element 1 moves to 0.
   delete pa; // Delete the original element at 0.
}
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("RemoveAt example: ") << &arr << _T("\n");
#endif

此程式的結果如下所示：

RemoveAt example: A CObArray with 1 elements
[0] = a CAge at $4606 40

`CObArray::SetAt`

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

void SetAt(
    INT_PTR nIndex,
    CObject* newElement);

參數

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

newElement
要在此陣列中插入的物件指標。 NULL允許值。

備註

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

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

下表顯示類似 CObArray::SetAt 的其他成員函式。

類別	成員函式
`CByteArray`	`void SetAt(INT_PTR nIndex, BYTE newElement);`
`CDWordArray`	`void SetAt(INT_PTR nIndex, DWORD newElement);`
`CPtrArray`	`void SetAt(INT_PTR nIndex, void* newElement);`
`CStringArray`	`void SetAt(INT_PTR nIndex, LPCTSTR newElement);`
`CUIntArray`	`void SetAt(INT_PTR nIndex, UINT newElement);`
`CWordArray`	`void SetAt(INT_PTR nIndex, WORD newElement);`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray arr;
CObject* pa;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
if ((pa = arr.GetAt(0)) != NULL)
{
   arr.SetAt(0, new CAge(30));  // Replace element 0.
   delete pa; // Delete the original element at 0.
}
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("SetAt example: ") << &arr << _T("\n");
#endif

此程式的結果如下所示：

SetAt example: A CObArray with 2 elements
[0] = a CAge at $47E0 30
[1] = a CAge at $47A0 40

`CObArray::SetAtGrow`

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

void SetAtGrow(
    INT_PTR nIndex,
    CObject* newElement);

參數

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

newElement
要加入至這個陣列的物件指標。 NULL允許值。

備註

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

下表顯示類似 CObArray::SetAtGrow 的其他成員函式。

類別	成員函式
`CByteArray`	`void SetAtGrow(INT_PTR nIndex, BYTE newElement);` `throw(CMemoryException*);`
`CDWordArray`	`void SetAtGrow(INT_PTR nIndex, DWORD newElement);` `throw(CMemoryException*);`
`CPtrArray`	`void SetAtGrow(INT_PTR nIndex, void* newElement);` `throw( CMemoryException*);`
`CStringArray`	`void SetAtGrow(INT_PTR nIndex, LPCTSTR newElement);` `throw(CMemoryException*);`
`CUIntArray`	`void SetAtGrow(INT_PTR nIndex, UINT newElement);` `throw(CMemoryException*);`
`CWordArray`	`void SetAtGrow(INT_PTR nIndex, WORD newElement);` `throw(CMemoryException*);`

範例

如需所有集合範例中使用的類別清單 CAge ，請參閱 CObList::CObList 。

CObArray arr;

arr.Add(new CAge(21)); // Element 0
arr.Add(new CAge(40)); // Element 1
arr.SetAtGrow(3, new CAge(65)); // Element 2 deliberately
                                      // skipped.
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("SetAtGrow example: ") << &arr << _T("\n");
#endif

此程式的結果如下所示：

SetAtGrow example: A CObArray with 4 elements
[0] = a CAge at $47C0 21
[1] = a CAge at $4800 40
[2] = NULL
[3] = a CAge at $4840 65

`CObArray::SetSize`

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

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

參數

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

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

備註

如果新大小小於舊大小，則會截斷陣列，並釋放所有未使用的記憶體。為了提高效率，請先呼叫 SetSize 以設定陣列的大小，再使用它。這樣可防止每次新增專案時重新配置和複製陣列。

參數 nGrowBy 會影響陣列成長時的內部記憶體配置。其使用永遠不會影響和 GetUpperBound 所 GetSize 報告的陣列大小。

如果陣列的大小已成長，所有新配置的 CObject * 指標都會設定為 NULL 。

下表顯示類似 CObArray::SetSize 的其他成員函式。

類別	成員函式
`CByteArray`	`void SetSize(INT_PTR nNewSize, int nGrowBy = -1);` `throw(CMemoryException*);`
`CDWordArray`	`void SetSize(INT_PTR nNewSize, int nGrowBy = -1);` `throw(CMemoryException*);`
`CPtrArray`	`void SetSize(INT_PTR nNewSize, int nGrowBy = -1);` `throw(CMemoryException*);`
`CStringArray`	`void SetSize(INT_PTR nNewSize, int nGrowBy = -1);` `throw(CMemoryException*);`
`CUIntArray`	`void SetSize(INT_PTR nNewSize, int nGrowBy = -1);` `throw(CMemoryException*);`
`CWordArray`	`void SetSize(INT_PTR nNewSize, int nGrowBy = -1);` `throw(CMemoryException*);`

範例

請參閱的 CObArray::GetData 範例。

另請參閱

CObject 類
 階層架構圖表
 CStringArray 類
 CPtrArray 類
 CByteArray 類
 CWordArray 類
 CDWordArray 類

共用方式為

CObArray 類別

語法

成員

公用建構函式

公用方法

公用運算子

備註

繼承階層架構

需求

CObArray::Add

參數

傳回值

備註

範例

CObArray::Append

參數

傳回值

備註

範例

CObArray::Copy

參數

備註

範例

CObArray::CObArray

備註

範例

CObArray::ElementAt

參數

傳回值

備註

範例

CObArray::FreeExtra

備註

範例

CObArray::GetAt

參數

傳回值

備註

範例

CObArray::GetCount

傳回值

備註

範例

CObArray::GetData

傳回值

備註

範例

CObArray::GetSize

備註

範例

CObArray::GetUpperBound

傳回值

備註

範例

CObArray::InsertAt

參數

備註

範例

CObArray::IsEmpty

傳回值

CObArray::operator [ ]

備註

範例

CObArray::RemoveAll

備註

範例

CObArray::RemoveAt

參數

備註

範例

CObArray::SetAt

參數

備註

範例

CObArray::SetAtGrow

參數

備註

範例

CObArray::SetSize

`CObArray` 類別

`CObArray::Add`

`CObArray::Append`

`CObArray::Copy`

`CObArray::CObArray`

`CObArray::ElementAt`

`CObArray::FreeExtra`

`CObArray::GetAt`

`CObArray::GetCount`

`CObArray::GetData`

`CObArray::GetSize`

`CObArray::GetUpperBound`

`CObArray::InsertAt`

`CObArray::IsEmpty`

`CObArray::operator [ ]`

`CObArray::RemoveAll`

`CObArray::RemoveAt`

`CObArray::SetAt`

`CObArray::SetAtGrow`

`CObArray::SetSize`