Класс CAtlArray

Этот класс реализует объект массива.

Синтаксис

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

Параметры

E
Тип данных для сохранения в массиве.

ETraits
Код, используемый для копирования или перемещения элементов.

Участники

Методы

Function	Description
Прибавить	Вызовите этот метод, чтобы добавить элемент в объект массива.
Добавить	Вызовите этот метод, чтобы добавить содержимое одного массива в конец другого.
AssertValid	Вызовите этот метод, чтобы убедиться, что объект массива действителен.
CAtlArray	Конструктор.
~CAtlArray	Деструктор
Копировать	Вызовите этот метод, чтобы скопировать элементы одного массива в другой.
FreeExtra	Вызовите этот метод, чтобы удалить все пустые элементы из массива.
GetAt	Вызовите этот метод, чтобы получить один элемент из объекта массива.
GetCount	Вызовите этот метод, чтобы вернуть количество элементов, хранящихся в массиве.
GetData	Вызовите этот метод, чтобы вернуть указатель на первый элемент в массиве.
InsertArrayAt	Вызовите этот метод, чтобы вставить один массив в другой.
InsertAt	Вызовите этот метод, чтобы вставить новый элемент (или несколько копий элемента) в объект массива.
IsEmpty	Вызовите этот метод, чтобы проверить, является ли массив пустым.
RemoveAll	Вызовите этот метод, чтобы удалить все элементы из объекта массива.
RemoveAt	Вызовите этот метод, чтобы удалить один или несколько элементов из массива.
SetAt	Вызовите этот метод, чтобы задать значение элемента в объекте массива.
SetAtGrow	Вызовите этот метод, чтобы задать значение элемента в объекте массива, расширяя массив по мере необходимости.
SetCount	Вызовите этот метод, чтобы задать размер объекта массива.

Операторы

Operator	Description
operator []	Вызовите этот оператор, чтобы вернуть ссылку на элемент в массиве.

Определения типов

Typedef	Description
INARGTYPE	Тип данных, используемый для добавления элементов в массив.
OUTARGTYPE	Тип данных, используемый для извлечения элементов из массива.

Замечания

CAtlArray предоставляет методы для создания массива элементов определяемого пользователем типа и управления ими. Несмотря на то, что он похож на стандартные массивы C, CAtlArray объект может динамически сжиматься и увеличиваться по мере необходимости. Индекс массива всегда начинается с позиции 0, а верхняя граница может быть исправлена или разрешена для расширения при добавлении новых элементов.

Для массивов с небольшим количеством элементов можно использовать класс ATL CSimpleArray .

CAtlArray тесно связан с классом MFC и будет работать в проекте MFC CArray , хотя и без поддержки сериализации.

Дополнительные сведения см. в разделе "Классы коллекций 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
Массив для добавления.

Возвращаемое значение

Возвращает индекс первого добавленного элемента.

Замечания

Элементы в предоставленном массиве добавляются в конец существующего массива. При необходимости память будет выделена для размещения новых элементов.

Массивы должны иметь один и тот же тип, и невозможно добавить к себе массив.

В отладочных сборках будет вызываться ATLASSERT, если CAtlArray аргумент не является допустимым массивом или если aSrc ссылается на тот же объект. В сборках выпуска недопустимые аргументы могут привести к непредсказуемому поведению.

Пример

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

В отладочных сборках будет вызываться ATLASSERT, если существующий CAtlArray объект недействителен, или если aSrc ссылается на тот же объект. В сборках выпуска недопустимые аргументы могут привести к непредсказуемому поведению.

Примечание.

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

Замечания

Все пустые элементы удаляются, но размер и верхняя граница массива остаются неизменными.

В отладочных сборках объект ATLASSERT будет вызываться, если объект CAtlArray недопустим или если массив превысит его максимальный размер.

CAtlArray::GetAt

Вызовите этот метод, чтобы получить один элемент из объекта массива.

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

Параметры

iElement
Значение индекса возвращаемого элемента массива.

Возвращаемое значение

Возвращает ссылку на обязательный элемент массива.

Замечания

В отладочных сборках объект ATLASSERT будет вызван, если iElement превышает количество элементов в массиве. В сборках выпуска недопустимый аргумент может привести к непредсказуемому поведению.

Пример

// 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. Существующие элементы массива перемещаются, чтобы избежать перезаписи.

В отладочных сборках объект ATLASSERT будет вызван, если CAtlArray объект недопустим, или если указатель paNew имеет значение NULL или недопустимый.

Примечание.

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. Существующие элементы перемещаются, чтобы избежать перезаписи.

В отладочных сборках объект ATLASSERT будет вызываться, если CAtlArray объект недопустим, число добавляемых элементов равно нулю, или объединенное число элементов слишком велико для содержащегося массива. В розничных сборках передача недопустимых параметров может привести к непредсказуемым результатам.

Пример

// 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. В отличие от класса CArray класса MFC, этот оператор нельзя использовать в качестве замены CAtlArray::SetAt.

В отладочных сборках значение ATLASSERT будет возникать, если iElement превышает общее количество элементов в массиве. В розничных сборках недопустимый параметр может привести к непредсказуемым результатам.

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 .

В отладочных сборках объект ATLASSERT будет вызван, если CAtlArray объект недействителен, или если совокупное общее количество элементов iElement и nCount превышает общее количество элементов в массиве. В розничных сборках недопустимые параметры могут привести к непредсказуемым результатам.

Пример

// 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
Индекс, указывающий на заданный элемент массива.

элемент
Новое значение указанного элемента.

Замечания

В отладочных сборках объект ATLASSERT будет вызван, если iElement превышает количество элементов в массиве. В розничных сборках недопустимый параметр может привести к непредсказуемым результатам.

Пример

См. пример 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);

Параметры

iElement
Индекс, указывающий на заданный элемент массива.

элемент
Новое значение указанного элемента.

Замечания

Заменяет значение элемента, на которое указывает индекс. Если iElement больше текущего размера массива, массив автоматически увеличивается с помощью вызова CAtlArray::SetCount. В отладочных сборках объект ATLASSERT будет вызван, если CAtlArray объект недопустим. В розничных сборках недопустимые параметры могут привести к непредсказуемым результатам.

Пример

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

См. также

Пример MMXSwarm
Пример DynamicConsumer
Пример обновленияPV
Пример marquee
Класс CArray
Общие сведения о классе