CAtlArray 类

项目
10/13/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 []`	调用此运算符可返回对数组中元素的引用。

Typedef

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();

参数

element
要添加到数组的元素。

返回值

返回添加的元素的索引。

备注

新元素将添加到数组的末尾。如果未提供元素，则会添加一个空元素；也就是说，数组的大小会增大，就如同添加了真实元素一样。如果操作失败，则使用参数 E_OUTOFMEMORY 调用 AtlThrow。

示例

// 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 返回的值始终比最大索引大 1。

示例

请参阅 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
要插入的一个或多个元素的索引。

element
要插入的一个或多个元素的值。

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
指向要设置的数组元素的索引。

element
指定元素的新值。

注解

在调试版本中，如果 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);

参数