Класс CArray
Поддерживает массивы, такие как массивы 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
см. в статьях "Коллекции".
Иерархия наследования
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
Класс
Вспомогательные функции классов коллекции