CArray Class

Supports arrays that are like C arrays, but can dynamically reduce and grow as necessary.

template < class TYPE, class ARG_TYPE = const TYPE& > 
class CArray : 
   public CObject

Parameters

• TYPE
  Template parameter that specifies the type of objects stored in the array. TYPE is a parameter that is returned by CArray.

• ARG _ TYPE
  Template parameter that specifies the argument type that is used to access objects stored in the array. Often a reference to TYPE. ARG_TYPE is a parameter that is passed to CArray.

Members

Public Constructors

Name	Description
CArray::CArray	Constructs an empty array.

Public Methods

Name	Description
CArray::Add	Adds an element to the end of the array; grows the array if necessary.
CArray::Append	Appends another array to the array; grows the array if necessary
CArray::Copy	Copies another array to the array; grows the array if necessary.
CArray::ElementAt	Returns a temporary reference to the element pointer within the array.
CArray::FreeExtra	Frees all unused memory above the current upper bound.
CArray::GetAt	Returns the value at a given index.
CArray::GetCount	Gets the number of elements in this array.
CArray::GetData	Allows access to elements in the array. Can be NULL.
CArray::GetSize	Gets the number of elements in this array.
CArray::GetUpperBound	Returns the largest valid index.
CArray::InsertAt	Inserts an element (or all the elements in another array) at a specified index.
CArray::IsEmpty	Determines whether the array is empty.
CArray::RemoveAll	Removes all the elements from this array.
CArray::RemoveAt	Removes an element at a specific index.
CArray::SetAt	Sets the value for a given index; array not allowed to grow.
CArray::SetAtGrow	Sets the value for a given index; grows the array if necessary.
CArray::SetSize	Sets the number of elements to be contained in this array.

Public Operators

Name	Description
CArray::operator []	Sets or gets the element at the specified index.

Remarks

Array indexes always start at position 0. You can decide whether to fix the upper bound or enable the array to expand when you add elements past the current bound. Memory is allocated contiguously to the upper bound, even if some elements are null.

Note

Most methods that resize a CArray object or add elements to it use memcpy_s to move elements. This is a problem because memcpy_s is not compatible with any objects that require the constructor to be called. If the items in the CArray are not compatible with memcpy_s, you must create a new CArray of the appropriate size. You must then use CArray::Copy and CArray::SetAt to populate the new array because those methods use an assignment operator instead of memcpy_s.

As with a C array, the access time for a CArray indexed element is constant and is independent of the array size.

Tip

Before using an array, use SetSize to establish its size and allocate memory for it. If you do not use SetSize, adding elements to your array causes it to be frequently reallocated and copied. Frequent reallocation and copying are inefficient and can fragment memory.

If you need a dump of individual elements in an array, you must set the depth of the CDumpContext object to 1 or larger.

Certain member functions of this class call global helper functions that must be customized for most uses of the CArray class. See the topic Collection Class Helpers in the MFC Macros and Globals section.

Array class derivation is like list derivation.

For more information about how to use CArray, see the article Collections.

Inheritance Hierarchy

CObject

CArray

Requirements

Header: afxtempl.h

See Also

Reference

CObject Class

Hierarchy Chart

CObArray Class

Concepts

MFC Sample COLLECT

Other Resources

Collection Class Helpers