Класс `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;

Замечания

Так как индексы массива основаны на нулях, эта функция возвращает значение 1 меньше GetSize.

Условие 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
Другой массив, содержащий элементы, добавляемые в этот массив.

Замечания

В процессе он сдвигается (путем увеличения индекса) существующего элемента в этом индексе, и он сдвигает все элементы над ним.

Вторая версия вставляет все элементы из другой CArray коллекции, начиная с nStartIndex позиции.

Функция 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 []`

Эти операторы подстрока являются удобной заменой для SetAt функций и GetAt функций.

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 использует этот метод для копирования старых данных в новый буфер, когда массив должен увеличиваться или сжиматься (когда SetSize или FreeExtra вызывается). Реализация по умолчанию просто копирует данные.

Для массивов, в которых элемент содержит указатель на один из своих членов, или другая структура содержит указатель на один из элементов массива, указатели не обновляются в простом копировании. В этом случае можно исправить указатели, реализуя специализацию 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 влияет на выделение внутренней памяти во время роста массива. Его использование никогда не влияет на размер массива, как сообщается GetSize и GetUpperBound. Если используется значение по умолчанию, 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::SetAtGrow

Класс `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`