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

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.

Operators

Operator	Description
operator []	Call this operator to return a reference to an element in the array.

Typedefs

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.

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