Share via


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