CAtlArray Class
This class implements an array object.
template<typename E, class ETraits = CElementTraits<E>>
class CAtlArray
E
The type of data to be stored in the array.
ETraits
The code used to copy or move elements.
| Function | Description |
|---|---|
| Add | Call this method to add an element to the array object. |
| Append | Call this method to add the contents of one array to the end of another. |
| AssertValid | Call this method to confirm that the array object is valid. |
| CAtlArray | The constructor. |
| ~CAtlArray | The destructor. |
| Copy | Call this method to copy the elements of one array to another. |
| FreeExtra | Call this method to remove any empty elements from the array. |
| GetAt | Call this method to retrieve a single element from the array object. |
| GetCount | Call this method to return the number of elements stored in the array. |
| GetData | Call this method to return a pointer to the first element in the array. |
| InsertArrayAt | Call this method to insert one array into another. |
| InsertAt | Call this method to insert a new element (or multiple copies of an element) into the array object. |
| IsEmpty | Call this method to test if the array is empty. |
| RemoveAll | Call this method to remove all elements from the array object. |
| RemoveAt | Call this method to remove one or more elements from the array. |
| SetAt | Call this method to set the value of an element in the array object. |
| SetAtGrow | Call this method to set the value of an element in the array object, expanding the array as required. |
| SetCount | Call this method to set the size of the array object. |
| Operator | Description |
|---|---|
operator [] |
Call this operator to return a reference to an element in the array. |
| Typedef | Description |
|---|---|
| INARGTYPE | The data type to use for adding elements to the array. |
| OUTARGTYPE | The data type to use for retrieving elements from the array. |
CAtlArray provides methods for creating and managing an array of elements of a user-defined type. Although similar to standard C arrays, the CAtlArray object can dynamically shrink and grow as necessary. The array index always starts at position 0, and the upper bound can be fixed, or allowed to expand as new elements are added.
For arrays with a small number of elements, the ATL class CSimpleArray can be used.
CAtlArray is closely related to MFC's CArray class and will work in an MFC project, albeit without serialization support.
For more information, see ATL Collection Classes.
Header: atlcoll.h
Call this method to add an element to the array object.
size_t Add(INARGTYPE element);
size_t Add();
element
The element to be added to the array.
Returns the index of the added element.
The new element is added to the end of the array. If no element is provided, an empty element is added; that is, the array is increased in size as though a real element has been added. If the operation fails, AtlThrow is called with the argument 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);
Call this method to add the contents of one array to the end of another.
size_t Append(const CAtlArray<E, ETraits>& aSrc);
aSrc
The array to append.
Returns the index of the first appended element.
The elements in the supplied array are added to the end of the existing array. If necessary, memory will be allocated to accommodate the new elements.
The arrays must be of the same type, and it is not possible to append an array to itself.
In debug builds, an ATLASSERT will be raised if the CAtlArray argument is not a valid array or if aSrc refers to the same object. In release builds, invalid arguments may lead to unpredictable behavior.
// 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);
Call this method to confirm that the array object is valid.
void AssertValid() const;
If the array object is not valid, ATLASSERT will throw an assertion. This method is available only if _DEBUG is defined.
CAtlArray<float> fArray;
// AssertValid only exists in debug builds
#ifdef _DEBUG
fArray.AssertValid();
#endif
The constructor.
CAtlArray() throw();
Initializes the array object.
CAtlArray<int> iArray;
The destructor.
~CAtlArray() throw();
Frees up any resources used by the array object.
Call this method to copy the elements of one array to another.
void Copy(const CAtlArray<E, ETraits>& aSrc);
aSrc
The source of the elements to copy to an array.
Call this method to overwrite elements of one array with the elements of another array. If necessary, memory will be allocated to accommodate the new elements. It is not possible to copy elements of an array to itself.
If the existing contents of the array are to be retained, use CAtlArray::Append instead.
In debug builds, an ATLASSERT will be raised if the existing CAtlArray object is not valid, or if aSrc refers to the same object. In release builds, invalid arguments may lead to unpredictable behavior.
Note
CAtlArray::Copy does not support arrays consisting of elements created with the CAutoPtr class.
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);
Call this method to remove any empty elements from the array.
void FreeExtra() throw();
Any empty elements are removed, but the size and upper bound of the array remain unchanged.
In debug builds, an ATLASSERT will be raised if the CAtlArray object is not valid, or if the array would exceed its maximum size.
Call this method to retrieves a single element from the array object.
const E& GetAt(size_t iElement) const throw();
E& GetAt(size_t iElement) throw();
iElement
The index value of the array element to return.
Returns a reference to the required array element.
In debug builds, an ATLASSERT will be raised if iElement exceeds the number of elements in the array. In release builds, an invalid argument may lead to unpredictable behavior.
// 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);
}
Call this method to return the number of elements stored in the array.
size_t GetCount() const throw();
Returns the number of elements stored in the array.
As the first element in the array is at position 0, the value returned by GetCount is always 1 greater than the largest index.
See the example for CAtlArray::GetAt.
Call this method to return a pointer to the first element in the array.
E* GetData() throw();
const E* GetData() const throw();
Returns a pointer to the memory location storing the first element in the array. If no elements are available, NULL is returned.
// 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;
}
The data type to use for adding elements to the array.
typedef ETraits::INARGTYPE INARGTYPE;
Call this method to insert one array into another.
void InsertArrayAt(size_t iStart, const CAtlArray<E, ETraits>* paNew);
iStart
The index at which the array is to be inserted.
paNew
The array to be inserted.
Elements from the array paNew are copied into the array object, beginning at element iStart. The existing array elements are moved to avoid being overwritten.
In debug builds, an ATLASSERT will be raised if the CAtlArray object is not valid, or if the paNew pointer is NULL or invalid.
Note
CAtlArray::InsertArrayAt does not support arrays consisting of elements created with the CAutoPtr class.
// 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);
Call this method to insert a new element (or multiple copies of an element) into the array object.
void InsertAt(size_t iElement, INARGTYPE element, size_t nCount = 1);
iElement
The index where the element or elements are to be inserted.
element
The value of the element or elements to be inserted.
nCount
The number of elements to add.
Inserts one or more elements into the array, starting at index iElement. Existing elements are moved to avoid being overwritten.
In debug builds, an ATLASSERT will be raised if the CAtlArray object is invalid, the number of elements to be added is zero, or the combined number of elements is too large for the array to contain. In retail builds, passing invalid parameters may cause unpredictable results.
// 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);
Call this method to test if the array is empty.
bool IsEmpty() const throw();
Returns true if the array is empty, false otherwise.
The array is said to be empty if it contains no elements. Therefore, even if the array contains empty elements, it is not empty.
// 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());
Call this operator to return a reference to an element in the array.
E& operator[](size_t ielement) throw();
const E& operator[](size_t ielement) const throw();
iElement
The index value of the array element to return.
Returns a reference to the required array element.
Performs a similar function to CAtlArray::GetAt. Unlike the MFC class CArray, this operator cannot be used as a substitute for CAtlArray::SetAt.
In debug builds, an ATLASSERT will be raised if iElement exceeds the total number of elements in the array. In retail builds, an invalid parameter may cause unpredictable results.
The data type to use for retrieving elements from the array.
typedef ETraits::OUTARGTYPE OUTARGTYPE;
Call this method to remove all elements from the array object.
void RemoveAll() throw();
Removes all of the elements from the array object.
This method calls CAtlArray::SetCount to resize the array and subsequently frees any allocated memory.
See the example for CAtlArray::IsEmpty.
Call this method to remove one or more elements from the array.
void RemoveAt(size_t iElement, size_t nCount = 1);
iElement
The index of the first element to remove.
nCount
The number of elements to remove.
Removes one or more elements from the array. Any remaining elements are shifted down. The upper bound is decremented, but memory is not freed until a call to CAtlArray::FreeExtra is made.
In debug builds, an ATLASSERT will be raised if the CAtlArray object is not valid, or if the combined total of iElement and nCount exceeds the total number of elements in the array. In retail builds, invalid parameters may cause unpredictable results.
// 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);
Call this method to set the value of an element in the array object.
void SetAt(size_t iElement, INARGTYPE element);
iElement
The index pointing to the array element to set.
element
The new value of the specified element.
In debug builds, an ATLASSERT will be raised if iElement exceeds the number of elements in the array. In retail builds, an invalid parameter may result in unpredictable results.
See the example for CAtlArray::GetAt.
Call this method to set the size of the array object.
bool SetCount(size_t nNewSize, int nGrowBy = - 1);
nNewSize
The required size of the array.
nGrowBy
A value used to determine how large to make the buffer. A value of -1 causes an internally calculated value to be used.
Returns true if the array is successfully resized, false otherwise.
The array can be increased or decreased in size. If increased, extra empty elements are added to the array. If decreased, the elements with the largest indices will be deleted and memory freed.
Use this method to set the size of the array before using it. If SetCount is not used, the process of adding elements — and the subsequent memory allocation performed — will reduce performance and fragment memory.
See the example for CAtlArray::GetData.
Call this method to set the value of an element in the array object, expanding the array as required.
void SetAtGrow(size_t iElement, INARGTYPE element);
iElement
The index pointing to the array element to set.
element
The new value of the specified element.
Replaces the value of the element pointed to by the index. If iElement is larger than the current size of the array, the array is automatically increased using a call to CAtlArray::SetCount. In debug builds, an ATLASSERT will be raised if the CAtlArray object is not valid. In retail builds, invalid parameters may cause unpredictable results.
// 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 Sample
DynamicConsumer Sample
UpdatePV Sample
Marquee Sample
CArray Class
Class Overview