CAtlArray Class
The latest version of this topic can be found at CAtlArray Class.
This class implements an array object.
Syntax
template<typename E, class ETraits = CElementTraits<E>>
class CAtlArray
Parameters
E
The type of data to be stored in the array.
ETraits
The code used to copy or move elements.
Members
Methods
| 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. |
Operators
| operator [] | Call this operator to return a reference to an element in the array. |
Typedefs
| INARGTYPE | The data type to use for adding elements to the array. |
| OUTARGTYPE | The data type to use for retrieving elements from the array. |
Remarks
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.
Requirements
Header: atlcoll.h
CAtlArray::Add
Call this method to add an element to the array object.
size_t Add(INARGTYPE element);
size_t Add();
Parameters
element
The element to be added to the array.
Return Value
Returns the index of the added element.
Remarks
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.
Example
// 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
Call this method to add the contents of one array to the end of another.
size_t Append(const CAtlArray<E, ETraits>& aSrc);
Parameters
aSrc
The array to append.
Return Value
Returns the index of the first appended element.
Remarks
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.
Example
// 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
Call this method to confirm that the array object is valid.
void AssertValid() const;
Remarks
If the array object is not valid, ATLASSERT will throw an assertion. This method is available only if _DEBUG is defined.
Example
CAtlArray<float> fArray;
// AssertValid only exists in debug builds
#ifdef _DEBUG
fArray.AssertValid();
#endif
CAtlArray::CAtlArray
The constructor.
CAtlArray() throw();
Remarks
Initializes the array object.
Example
CAtlArray<int> iArray;
CAtlArray::~CAtlArray
The destructor.
~CAtlArray() throw();
Remarks
Frees up any resources used by the array object.
CAtlArray::Copy
Call this method to copy the elements of one array to another.
void Copy(const CAtlArray<E, ETraits>& aSrc);
Parameters
aSrc
The source of the elements to copy to an array.
Remarks
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.
Example
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
Call this method to remove any empty elements from the array.
void FreeExtra() throw();
Remarks
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.
CAtlArray::GetAt
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();
Parameters
iElement
The index value of the array element to return.
Return Value
Returns a reference to the required array element.
Remarks
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.
Example
// 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
Call this method to return the number of elements stored in the array.
size_t GetCount() const throw();
Return Value
Returns the number of elements stored in the array.
Remarks
As the first element in the array is at position 0, the value returned by GetCount is always 1 greater than the largest index.
Example
See the example for CAtlArray::GetAt.
CAtlArray::GetData
Call this method to return a pointer to the first element in the array.
E* GetData() throw();
const E* GetData() const throw();
Return Value
Returns a pointer to the memory location storing the first element in the array. If no elements are available, NULL is returned.
Example
// 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
The data type to use for adding elements to the array.
typedef ETraits::INARGTYPE INARGTYPE;
CAtlArray::InsertArrayAt
Call this method to insert one array into another.
void InsertArrayAt(size_t iStart, const CAtlArray<E, ETraits>* paNew);
Parameters
iStart
The index at which the array is to be inserted.
paNew
The array to be inserted.
Remarks
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.
Example
// 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
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);
Parameters
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.
Remarks
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.
Example
// 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
Call this method to test if the array is empty.
bool IsEmpty() const throw();
Return Value
Returns true if the array is empty, false otherwise.
Remarks
The array is said to be empty if it contains no elements. Therefore, even if the array contains empty elements, it is not empty.
Example
// 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 []
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();
Parameters
iElement
The index value of the array element to return.
Return Value
Returns a reference to the required array element.
Remarks
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.
CAtlArray::OUTARGTYPE
The data type to use for retrieving elements from the array.
typedef ETraits::OUTARGTYPE OUTARGTYPE;
CAtlArray::RemoveAll
Call this method to remove all elements from the array object.
void RemoveAll() throw();
Remarks
Removes all of the elements from the array object.
This method calls CAtlArray::SetCount to resize the array and subsequently frees any allocated memory.
Example
See the example for CAtlArray::IsEmpty.
CAtlArray::RemoveAt
Call this method to remove one or more elements from the array.
void RemoveAt(size_t iElement, size_t nCount = 1);
Parameters
iElement
The index of the first element to remove.
nCount
The number of elements to remove.
Remarks
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.
Example
// 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
Call this method to set the value of an element in the array object.
void SetAt(size_t iElement, INARGTYPE element);
Parameters
iElement
The index pointing to the array element to set.
element
The new value of the specified element.
Remarks
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.
Example
See the example for CAtlArray::GetAt.
CAtlArray::SetCount
Call this method to set the size of the array object.
bool SetCount(size_t nNewSize, int nGrowBy = - 1);
Parameters
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.
Return Value
Returns true if the array is successfully resized, false otherwise.
Remarks
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.
Example
See the example for CAtlArray::GetData.
CAtlArray::SetAtGrow
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);
Parameters
iElement
The index pointing to the array element to set.
element
The new value of the specified element.
Remarks
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.
Example
// 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.
See Also
MMXSwarm Sample
DynamicConsumer Sample
UpdatePV Sample
Marquee Sample
CArray Class
Class Overview