CObArray Class

Article
12/18/2017

The latest version of this topic can be found at CObArray Class.

Supports arrays of CObject pointers.

Syntax

class CObArray : public CObject

Members

Public Constructors

Name	Description
CObArray::CObArray	Constructs an empty array for `CObject` pointers.

Public Methods

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

Public Operators

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

Remarks

These object arrays are similar to C arrays, but they can dynamically shrink and grow as necessary.

Array indexes always start at position 0. You can decide whether to fix the upper bound or allow 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.

Under Win32, the size of a CObArray object is limited only to available memory.

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

CObArray incorporates the IMPLEMENT_SERIAL macro to support serialization and dumping of its elements. If an array of CObject pointers is stored to an archive, either with the overloaded insertion operator or with the Serialize member function, each CObject element is, in turn, serialized along with its array index.

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

When a CObArray object is deleted, or when its elements are removed, only the CObject pointers are removed, not the objects they reference.

Note

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.

Array class derivation is similar to list derivation. For details on the derivation of a special-purpose list class, see the article Collections.

Note

You must use the IMPLEMENT_SERIAL macro in the implementation of your derived class if you intend to serialize the array.

Inheritance Hierarchy

CObject

CObArray

Requirements

Header: afxcoll.h

CObArray::Add

Adds a new element to the end of an array, growing the array by 1.

INT_PTR Add(CObject* newElement);

Parameters

newElement
The CObject pointer to be added to this array.

Return Value

The index of the added element.

Remarks

If SetSize has been used with an nGrowBy value greater than 1, then extra memory may be allocated. However, the upper bound will increase by only 1.

The following table shows other member functions that are similar to CObArray::Add.

Class	Member Function
CByteArray	INT_PTR Add( BYTE `newElement` ); *throw( CMemoryException );**
CDWordArray	INT_PTR Add( DWORD `newElement` ); *throw( CMemoryException );**
CPtrArray	INT_PTR Add( void* `newElement` ); *throw( CMemoryException );**
CStringArray	INT_PTR Add( LPCTSTR `newElement` *); throw( CMemoryException ); INT_PTR Add(const CString&** `newElement` );
CUIntArray	INT_PTR Add( UINT `newElement` ); *throw( CMemoryException );**
CWordArray	INT_PTR Add( WORD `newElement` ); *throw( CMemoryException );**

Example

See CObList::CObList for a listing of the CAge class used in all collection examples.

         CObArray arr;

         arr.Add(new CAge(21)); // Element 0
         arr.Add(new CAge(40)); // Element 1
         #ifdef _DEBUG
            afxDump.SetDepth(1);
            afxDump << _T("Add example: ") << &arr << _T("\n");
         #endif

The results from this program are as follows:

Add example: A CObArray with 2 elements

[0] = a CAge at $442A 21

[1] = a CAge at $4468 40

CObArray::Append

Call this member function to add the contents of another array to the end of the given array.

INT_PTR Append(const CObArray& src);

Parameters

src
Source of the elements to be appended to the array.

Return Value

The index of the first appended element.

Remarks

The arrays must be of the same type.

If necessary, Append may allocate extra memory to accommodate the elements appended to the array.

The following table shows other member functions that are similar to CObArray::Append.

Class	Member Function
CByteArray	INT_PTR Append( const CByteArray& src );
CDWordArray	INT_PTR Append( const CDWordArray& src );
CPtrArray	INT_PTR Append( const CPtrArray& src );
CStringArray	INT_PTR Append( const CStringArray& src );
CUIntArray	INT_PTR Append( const CUIntArray& src );
CWordArray	INT_PTR Append( const CWordArray& src );

Example

See CObList::CObList for a listing of the CAge class used in all collection examples.

         CObArray myArray1, myArray2;

         // Add elements to the second array.
         myArray2.Add(new CAge(21));
         myArray2.Add(new CAge(42));

         // Add elements to the first array and also append the second array.
         myArray1.Add(new CAge(3));
         myArray1.Append(myArray2);

         #ifdef _DEBUG
            afxDump.SetDepth(1);
            afxDump << _T("myArray1: ") << &myArray1 << _T("\n");
            afxDump << _T("myArray2: ") << &myArray2 << _T("\n");
         #endif

CObArray::Copy

Call this member function to overwrite the elements of the given array with the elements of another array of the same type.

void Copy(const CObArray& src);

Parameters

src
Source of the elements to be copied to the array.

Remarks

Copy does not free memory; however, if necessary, Copy may allocate extra memory to accommodate the elements copied to the array.

The following table shows other member functions that are similar to CObArray::Copy.

Class	Member Function
CByteArray	void Copy( const CByteArray& src );
CDWordArray	void Copy( const CDWordArray& src );
CPtrArray	void Copy( const CPtrArray& src );
CStringArray	void Copy( const CStringArray& src );
CUIntArray	void Copy( const CUIntArray& src );
CWordArray	void Copy( const CWordArray& src );

Example

See CObList::CObList for a listing of the CAge class used in all collection examples.

         CObArray myArray1, myArray2;

         // Add elements to the second array.
         myArray2.Add(new CAge(21));
         myArray2.Add(new CAge(42));

         // Copy the elements from the second array to the first.
         myArray1.Copy(myArray2);

         #ifdef _DEBUG
            afxDump.SetDepth(1);
            afxDump << "myArray1: " << &myArray1 << "\n";
            afxDump << "myArray2: " << &myArray2 << "\n";
         #endif

CObArray::CObArray

Constructs an empty CObject pointer array.

CObArray();

Remarks

The array grows one element at a time.

The following table shows other constructors that are similar to CObArray::CObArray.

Class	Constructor
CByteArray	CByteArray( );
CDWordArray	CDWordArray( );
CPtrArray	CPtrArray( );
CStringArray	CStringArray( );
CUIntArray	CUIntArray( );
CWordArray	CWordArray( );

Example

         CObArray arr; //Array with default blocksize
         CObArray* pArray = new CObArray; //Array on the heap with default blocksize

CObArray::ElementAt

Returns a temporary reference to the element pointer within the array.

CObject*& ElementAt(INT_PTR nIndex);

Parameters

nIndex
An integer index that is greater than or equal to 0 and less than or equal to the value returned by GetUpperBound.

Return Value

A reference to a CObject pointer.

Remarks

It is used to implement the left-side assignment operator for arrays. Note that this is an advanced function that should be used only to implement special array operators.

The following table shows other member functions that are similar to CObArray::ElementAt.

Class	Member Function
CByteArray	BYTE& ElementAt( INT_PTR `nIndex` );
CDWordArray	DWORD& ElementAt( INT_PTR `nIndex` );
CPtrArray	*void& ElementAt( INT_PTR** `nIndex` );
CStringArray	CString& ElementAt( INT_PTR `nIndex` );
CUIntArray	UINT& ElementAt( INT_PTR `nIndex` );
CWordArray	WORD& ElementAt( INT_PTR `nIndex` );

Example

See the example for CObArray::GetSize.

CObArray::FreeExtra

Frees any extra memory that was allocated while the array was grown.

void FreeExtra();

Remarks

This function has no effect on the size or upper bound of the array.

The following table shows other member functions that are similar to CObArray::FreeExtra.

Class	Member Function
CByteArray	void FreeExtra( );
CDWordArray	void FreeExtra( );
CPtrArray	void FreeExtra( );
CStringArray	void FreeExtra( );
CUIntArray	void FreeExtra( );
CWordArray	void FreeExtra( );

Example

See the example for CObArray::GetData.

CObArray::GetAt

Returns the array element at the specified index.

CObject* GetAt(INT_PTR nIndex) const;

Parameters

nIndex
An integer index that is greater than or equal to 0 and less than or equal to the value returned by GetUpperBound.

Return Value

The CObject pointer element currently at this index.

Remarks

Note

Passing a negative value or a value greater than the value returned by GetUpperBound will result in a failed assertion.

The following table shows other member functions that are similar to CObArray::GetAt.

Class	Member Function
CByteArray	BYTE GetAt( INT_PTR `nIndex` ) const;
CDWordArray	DWORD GetAt( INT_PTR `nIndex` ) const;
CPtrArray	*void GetAt( INT_PTR `nIndex` ) const;**
CStringArray	CString GetAt( INT_PTR `nIndex` ) const;
CUIntArray	UINT GetAt( INT_PTR `nIndex` ) const;
CWordArray	WORD GetAt( INT_PTR `nIndex` ) const;

Example

See CObList::CObList for a listing of the CAge class used in all collection examples.

         CObArray arr;

         arr.Add(new CAge(21)); // Element 0
         arr.Add(new CAge(40)); // Element 1
         ASSERT(*(CAge*) arr.GetAt(0) == CAge(21));

CObArray::GetCount

Returns the number of array elements.

INT_PTR GetCount() const;

Return Value

The number of items in the array.

Remarks

Call this method to retrieve the number of elements in the array. Because indexes are zero-based, the size is 1 greater than the largest index.

The following table shows other member functions that are similar to CObArray::GetCount.

Class	Member Function
CByteArray	INT_PTR GetCount( ) const;
CDWordArray	INT_PTR GetCount( ) const;
CPtrArray	INT_PTR GetCount( ) const;
CStringArray	INT_PTR GetCount( ) const;
CUIntArray	INT_PTR GetCount( ) const;
CWordArray	INT_PTR GetCount( ) const;

Example

See CObList::CObList for a listing of the CAge class used in all collection examples.

         CObArray myArray;

         // Add elements to the array.
         for (int i = 0; i < 10; i++)
            myArray.Add(new CAge(i));

         // Add 100 to all the elements of the array.
         for (int i = 0; i < myArray.GetCount(); i++)
         {
            CAge*& pAge = (CAge*&) myArray.ElementAt(i);
            delete pAge;
            pAge = new CAge(100 + i);
         }

CObArray::GetData

Use this member function to gain direct access to the elements in the array.

const CObject** GetData() const;  
  
CObject** GetData();
```  
  
### Return Value  
 A pointer to the array of `CObject` pointers.  
  
### Remarks  
 If no elements are available, `GetData` returns a null value.  
  
 While direct access to the elements of an array can help you work more quickly, use caution when calling `GetData`; any errors you make directly affect the elements of your array.  
  
 The following table shows other member functions that are similar to `CObArray::GetData`.  
  
|Class|Member Function|  
|-----------|---------------------|  
|[CByteArray](../Topic/CByteArray%20Class.md)|**const BYTE\* GetData( ) const;BYTE\* GetData( );**|  
|[CDWordArray](../Topic/CDWordArray%20Class.md)|**const DWORD\* GetData( ) const;DWORD\* GetData( );**|  
|[CPtrArray](../Topic/CPtrArray%20Class.md)|**const void\*\* GetData( ) const;void\*\* GetData( );**|  
|[CStringArray](../Topic/CStringArray%20Class.md)|**const CString\* GetData( ) const;CString\* GetData( );**|  
|[CUIntArray](../Topic/CUIntArray%20Class.md)|**const UINT\* GetData( ) const;UINT\* GetData( );**|  
|[CWordArray](../Topic/CWordArray%20Class.md)|**const WORD\* GetData( ) const;WORD\* GetData( );**|  
  
### Example  
 See [CObList::CObList](../Topic/CObList%20Class.md#coblist__coblist) for a listing of the `CAge` class used in all collection examples.  
  
 [!CODE [NVC_MFCCollections#81](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCCollections#81)]  
  
##  <a name="cobarray__getsize"></a>  CObArray::GetSize  
 Returns the size of the array.

INT_PTR GetSize() const;

  
### Remarks  
 Since indexes are zero-based, the size is 1 greater than the largest index.  
  
 The following table shows other member functions that are similar to `CObArray::GetSize`.  
  
|Class|Member Function|  
|-----------|---------------------|  
|[CByteArray](../Topic/CByteArray%20Class.md)|**INT_PTR GetSize( ) const;**|  
|[CDWordArray](../Topic/CDWordArray%20Class.md)|**INT_PTR GetSize( ) const;**|  
|[CPtrArray](../Topic/CPtrArray%20Class.md)|**INT_PTR GetSize( ) const;**|  
|[CStringArray](../Topic/CStringArray%20Class.md)|**INT_PTR GetSize( ) const;**|  
|[CUIntArray](../Topic/CUIntArray%20Class.md)|**INT_PTR GetSize( ) const;**|  
|[CWordArray](../Topic/CWordArray%20Class.md)|**INT_PTR GetSize( ) const;**|  
  
### Example  
 See [CObList::CObList](../Topic/CObList%20Class.md#coblist__coblist) for a listing of the `CAge` class used in all collection examples.  
  
 [!CODE [NVC_MFCCollections#82](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCCollections#82)]  
  
##  <a name="cobarray__getupperbound"></a>  CObArray::GetUpperBound  
 Returns the current upper bound of this array.

INT_PTR GetUpperBound() const;

  
### Return Value  
 The index of the upper bound (zero-based).  
  
### Remarks  
 Because array indexes are zero-based, this function returns a value 1 less than `GetSize`.  
  
 The condition **GetUpperBound( )** = –1 indicates that the array contains no elements.  
  
 The following table shows other member functions that are similar to `CObArray::GetUpperBound`.  
  
|Class|Member Function|  
|-----------|---------------------|  
|[CByteArray](../Topic/CByteArray%20Class.md)|**INT_PTR GetUpperBound( ) const;**|  
|[CDWordArray](../Topic/CDWordArray%20Class.md)|**INT_PTR GetUpperBound( ) const;**|  
|[CPtrArray](../Topic/CPtrArray%20Class.md)|**INT_PTR GetUpperBound( ) const;**|  
|[CStringArray](../Topic/CStringArray%20Class.md)|**INT_PTR GetUpperBound( ) const;**|  
|[CUIntArray](../Topic/CUIntArray%20Class.md)|**INT_PTR GetUpperBound( ) const;**|  
|[CWordArray](../Topic/CWordArray%20Class.md)|**INT_PTR GetUpperBound( ) const;**|  
  
### Example  
 See [CObList::CObList](../Topic/CObList%20Class.md#coblist__coblist) for a listing of the `CAge` class used in all collection examples.  
  
 [!CODE [NVC_MFCCollections#83](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCCollections#83)]  
  
##  <a name="cobarray__insertat"></a>  CObArray::InsertAt  
 Inserts an element (or all the elements in another array) at a specified index.

void InsertAt( INT_PTR nIndex,
CObject* newElement,
INT_PTR nCount = 1);

void InsertAt( INT_PTR nStartIndex,
CObArray* pNewArray);

  
### Parameters  
 `nIndex`  
 An integer index that may be greater than the value returned by `GetUpperBound`.  
  
 `newElement`  
 The `CObject` pointer to be placed in this array. A `newElement` of value **NULL** is allowed.  
  
 `nCount`  
 The number of times this element should be inserted (defaults to 1).  
  
 `nStartIndex`  
 An integer index that may be greater than the value returned by `GetUpperBound`.  
  
 `pNewArray`  
 Another array that contains elements to be added to this array.  
  
### Remarks  
 The first version of `InsertAt` inserts one element (or multiple copies of an element) at a specified index in an array. In the process, it shifts up (by incrementing the index) the existing element at this index, and it shifts up all the elements above it.  
  
 The second version inserts all the elements from another `CObArray` collection, starting at the `nStartIndex` position.  
  
 The `SetAt` function, in contrast, replaces one specified array element and does not shift any elements.  
  
 The following table shows other member functions that are similar to `CObArray::InsertAt`.  
  
|Class|Member Function|  
|-----------|---------------------|  
|[CByteArray](../Topic/CByteArray%20Class.md)|**void InsertAt( INT_PTR** `nIndex` **, BYTE** `newElement` **, int** `nCount` **= 1 );**<br /><br /> **throw( CMemoryException\* );**<br /><br /> **void InsertAt( INT_PTR** `nStartIndex` **, CByteArray\*** `pNewArray` **);**<br /><br /> **throw( CMemoryException\* );**|  
|[CDWordArray](../Topic/CDWordArray%20Class.md)|**void InsertAt( INT_PTR** `nIndex` **, DWORD** `newElement` **, int** `nCount` **= 1 );**<br /><br /> **throw( CMemoryException\* );**<br /><br /> **void InsertAt( INT_PTR** `nStartIndex` **, CDWordArray\*** `pNewArray` **);**<br /><br /> **throw( CMemoryException\* );**|  
|[CPtrArray](../Topic/CPtrArray%20Class.md)|**void InsertAt( INT_PTR** `nIndex` **, void\*** `newElement` **, int** `nCount` **= 1 );**<br /><br /> **throw( CMemoryException\* );**<br /><br /> **void InsertAt( INT_PTR** `nStartIndex` **, CPtrArray\*** `pNewArray` **);**<br /><br /> **throw( CMemoryException\* );**|  
|[CStringArray](../Topic/CStringArray%20Class.md)|**void InsertAt( INT_PTR** `nIndex` **, LPCTSTR** `newElement` **, int** `nCount` **= 1 );**<br /><br /> **throw( CMemoryException\* );**<br /><br /> **void InsertAt( INT_PTR** `nStartIndex` **, CStringArray\*** `pNewArray` **);**<br /><br /> **throw( CMemoryException\* );**|  
|[CUIntArray](../Topic/CUIntArray%20Class.md)|**void InsertAt( INT_PTR** `nIndex` **, UINT** `newElement` **, int** `nCount` **= 1 );**<br /><br /> **throw( CMemoryException\* );**<br /><br /> **void InsertAt( INT_PTR** `nStartIndex` **, CUIntArray\*** `pNewArray` **);**<br /><br /> **throw( CMemoryException\* );**|  
|[CWordArray](../Topic/CWordArray%20Class.md)|**void InsertAt( INT_PTR** `nIndex` **, WORD** `newElement` **, int** `nCount` **= 1 );**<br /><br /> **throw( CMemoryException\* );**<br /><br /> **void InsertAt( INT_PTR** `nStartIndex` **, CWordArray\*** `pNewArray` **);**<br /><br /> **throw( CMemoryException\* );**|  
  
### Example  
  See [CObList::CObList](../Topic/CObList%20Class.md#coblist__coblist) for a listing of the `CAge` class used in all collection examples.  
  
 [!CODE [NVC_MFCCollections#84](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCCollections#84)]  
  
 The results from this program are as follows:  
  
 `InsertAt example: A CObArray with 3 elements`  
  
 `[0] = a CAge at $45C8 21`  
  
 `[1] = a CAge at $4646 30`  
  
 `[2] = a CAge at $4606 40`  
  
##  <a name="cobarray__isempty"></a>  CObArray::IsEmpty  
 Determines if the array is empty.

BOOL IsEmpty() const;

  
### Return Value  
 Nonzero if the array is empty; otherwise 0.  
  
##  <a name="cobarray__operator_at"></a>  CObArray::operator [ ]  
 These subscript operators are a convenient substitute for the `SetAt` and `GetAt` functions.

CObject*& operator[](INT_PTR nIndex);

CObject* operator[](INT_PTR nIndex) const;

  
### Remarks  
 The first operator, called for arrays that are not **const**, may be used on either the right (r-value) or the left (l-value) of an assignment statement. The second, called for **const** arrays, may be used only on the right.  
  
 The Debug version of the library asserts if the subscript (either on the left or right side of an assignment statement) is out of bounds.  
  
 The following table shows other operators that are similar to **CObArray::operator []**.  
  
|Class|Operator|  
|-----------|--------------|  
|[CByteArray](../Topic/CByteArray%20Class.md)|**BYTE& operator []( INT_PTR** `nIndex` **\);**<br /><br /> **BYTE operator []( INT_PTR** `nIndex` **\) const;**|  
|[CDWordArray](../Topic/CDWordArray%20Class.md)|**DWORD& operator []( INT_PTR** `nIndex` **\);**<br /><br /> **DWORD operator []( INT_PTR** `nIndex` **\) const;**|  
|[CPtrArray](../Topic/CPtrArray%20Class.md)|**void\*& operator []( INT_PTR** `nIndex` **\);**<br /><br /> **void\* operator []( INT_PTR** `nIndex` **\) const;**|  
|[CStringArray](../Topic/CStringArray%20Class.md)|**CString& operator []( INT_PTR** `nIndex` **\);**<br /><br /> **CString operator []( INT_PTR** `nIndex` **\) const;**|  
|[CUIntArray](../Topic/CUIntArray%20Class.md)|**UINT& operator []( INT_PTR** `nIndex` **\);**<br /><br /> **UINT operator []( INT_PTR** `nIndex` **\) const;**|  
|[CWordArray](../Topic/CWordArray%20Class.md)|**WORD& operator []( INT_PTR** `nIndex` **\);**<br /><br /> **WORD operator []( INT_PTR** `nIndex` **\) const;**|  
  
### Example  
 See [CObList::CObList](../Topic/CObList%20Class.md#coblist__coblist) for a listing of the `CAge` class used in all collection examples.  
  
 [!CODE [NVC_MFCCollections#88](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCCollections#88)]  
  
##  <a name="cobarray__removeall"></a>  CObArray::RemoveAll  
 Removes all the pointers from this array but does not actually delete the `CObject` objects.

void RemoveAll();

  
### Remarks  
 If the array is already empty, the function still works.  
  
 The `RemoveAll` function frees all memory used for pointer storage.  
  
 The following table shows other member functions that are similar to `CObArray::RemoveAll`.  
  
|Class|Member Function|  
|-----------|---------------------|  
|[CByteArray](../Topic/CByteArray%20Class.md)|**void RemoveAll( );**|  
|[CDWordArray](../Topic/CDWordArray%20Class.md)|**void RemoveAll( );**|  
|[CPtrArray](../Topic/CPtrArray%20Class.md)|**void RemoveAll( );**|  
|[CStringArray](../Topic/CStringArray%20Class.md)|**void RemoveAll( );**|  
|[CUIntArray](../Topic/CUIntArray%20Class.md)|**void RemoveAll( );**|  
|[CWordArray](../Topic/CWordArray%20Class.md)|**void RemoveAll( );**|  
  
### Example  
 See [CObList::CObList](../Topic/CObList%20Class.md#coblist__coblist) for a listing of the `CAge` class used in all collection examples.  
  
 [!CODE [NVC_MFCCollections#85](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCCollections#85)]  
  
##  <a name="cobarray__removeat"></a>  CObArray::RemoveAt  
 Removes one or more elements starting at a specified index in an array.

void RemoveAt( INT_PTR nIndex,
INT_PTR nCount = 1);

  
### Parameters  
 `nIndex`  
 An integer index that is greater than or equal to 0 and less than or equal to the value returned by `GetUpperBound`.  
  
 `nCount`  
 The number of elements to remove.  
  
### Remarks  
 In the process, it shifts down all the elements above the removed element(s). It decrements the upper bound of the array but does not free memory.  
  
 If you try to remove more elements than are contained in the array above the removal point, then the Debug version of the library asserts.  
  
 The `RemoveAt` function removes the `CObject` pointer from the array, but it does not delete the object itself.  
  
 The following table shows other member functions that are similar to `CObArray::RemoveAt`.  
  
|Class|Member Function|  
|-----------|---------------------|  
|[CByteArray](../Topic/CByteArray%20Class.md)|**void RemoveAt( INT_PTR** `nIndex` **, INT_PTR** `nCount` **= 1 );**|  
|[CDWordArray](../Topic/CDWordArray%20Class.md)|**void RemoveAt( INT_PTR** `nIndex` **, INT_PTR** `nCount` **= 1 );**|  
|[CPtrArray](../Topic/CPtrArray%20Class.md)|**void RemoveAt( INT_PTR** `nIndex` **, INT_PTR** `nCount` **= 1 );**|  
|[CStringArray](../Topic/CStringArray%20Class.md)|**void RemoveAt( INT_PTR** `nIndex` **, INT_PTR** `nCount` **= 1 );**|  
|[CUIntArray](../Topic/CUIntArray%20Class.md)|**void RemoveAt( INT_PTR** `nIndex` **, INT_PTR** `nCount` **= 1 );**|  
|[CWordArray](../Topic/CWordArray%20Class.md)|**void RemoveAt( INT_PTR** `nIndex` **, INT_PTR** *nCount* **= 1 );**|  
  
### Example  
  See [CObList::CObList](../Topic/CObList%20Class.md#coblist__coblist) for a listing of the `CAge` class used in all collection examples.  
  
 [!CODE [NVC_MFCCollections#112](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCCollections#112)]  
  
 The results from this program are as follows:  
  
 `RemoveAt example: A CObArray with 1 elements`  
  
 `[0] = a CAge at $4606 40`  
  
##  <a name="cobarray__setat"></a>  CObArray::SetAt  
 Sets the array element at the specified index.

void SetAt( INT_PTR nIndex,
CObject* newElement);

  
### Parameters  
 `nIndex`  
 An integer index that is greater than or equal to 0 and less than or equal to the value returned by `GetUpperBound`.  
  
 `newElement`  
 The object pointer to be inserted in this array. A **NULL** value is allowed.  
  
### Remarks  
 `SetAt` will not cause the array to grow. Use `SetAtGrow` if you want the array to grow automatically.  
  
 You must ensure that your index value represents a valid position in the array. If it is out of bounds, then the Debug version of the library asserts.  
  
 The following table shows other member functions that are similar to `CObArray::SetAt`.  
  
|Class|Member Function|  
|-----------|---------------------|  
|[CByteArray](../Topic/CByteArray%20Class.md)|**void SetAt( INT_PTR** `nIndex` **, BYTE** `newElement` **);**|  
|[CDWordArray](../Topic/CDWordArray%20Class.md)|**void SetAt( INT_PTR** `nIndex` **, DWORD** `newElement` **);**|  
|[CPtrArray](../Topic/CPtrArray%20Class.md)|**void SetAt( INT_PTR** `nIndex` **, void\*** `newElement` **);**|  
|[CStringArray](../Topic/CStringArray%20Class.md)|**void SetAt( INT_PTR** `nIndex` **, LPCTSTR** `newElement` **);**|  
|[CUIntArray](../Topic/CUIntArray%20Class.md)|**void SetAt( INT_PTR** `nIndex` **, UINT** `newElement` **);**|  
|[CWordArray](../Topic/CWordArray%20Class.md)|**void SetAt( INT_PTR** `nIndex` **, WORD** `newElement` **);**|  
  
### Example  
  See [CObList::CObList](../Topic/CObList%20Class.md#coblist__coblist) for a listing of the `CAge` class used in all collection examples.  
  
 [!CODE [NVC_MFCCollections#86](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCCollections#86)]  
  
 The results from this program are as follows:  
  
 `SetAt example: A CObArray with 2 elements`  
  
 `[0] = a CAge at $47E0 30`  
  
 `[1] = a CAge at $47A0 40`  
  
##  <a name="cobarray__setatgrow"></a>  CObArray::SetAtGrow  
 Sets the array element at the specified index.

void SetAtGrow( INT_PTR nIndex,
CObject* newElement);

  
### Parameters  
 `nIndex`  
 An integer index that is greater than or equal to 0.  
  
 `newElement`  
 The object pointer to be added to this array. A **NULL** value is allowed.  
  
### Remarks  
 The array grows automatically if necessary (that is, the upper bound is adjusted to accommodate the new element).  
  
 The following table shows other member functions that are similar to `CObArray::SetAtGrow`.  
  
|Class|Member Function|  
|-----------|---------------------|  
|[CByteArray](../Topic/CByteArray%20Class.md)|**void SetAtGrow( INT_PTR** `nIndex` **, BYTE** `newElement` **);**<br /><br /> **throw( CMemoryException\* );**|  
|[CDWordArray](../Topic/CDWordArray%20Class.md)|**void SetAtGrow( INT_PTR** `nIndex` **, DWORD** `newElement` **);**<br /><br /> **throw( CMemoryException\* );**|  
|[CPtrArray](../Topic/CPtrArray%20Class.md)|**void SetAtGrow( INT_PTR** `nIndex` **, void\*** `newElement` **);**<br /><br /> **throw( CMemoryException\* );**|  
|[CStringArray](../Topic/CStringArray%20Class.md)|**void SetAtGrow( INT_PTR** `nIndex` **, LPCTSTR** `newElement` **);**<br /><br /> **throw( CMemoryException\* );**|  
|[CUIntArray](../Topic/CUIntArray%20Class.md)|**void SetAtGrow( INT_PTR** `nIndex` **, UINT** `newElement` **);**<br /><br /> **throw( CMemoryException\* );**|  
|[CWordArray](../Topic/CWordArray%20Class.md)|**void SetAtGrow( INT_PTR** `nIndex` **, WORD** `newElement` **);**<br /><br /> **throw( CMemoryException\* );**|  
  
### Example  
  See [CObList::CObList](../Topic/CObList%20Class.md#coblist__coblist) for a listing of the `CAge` class used in all collection examples.  
  
 [!CODE [NVC_MFCCollections#87](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCCollections#87)]  
  
 The results from this program are as follows:  
  
 `SetAtGrow example: A CObArray with 4 elements`  
  
 `[0] = a CAge at $47C0 21`  
  
 `[1] = a CAge at $4800 40`  
  
 `[2] = NULL`  
  
 `[3] = a CAge at $4840 65`  
  
##  <a name="cobarray__setsize"></a>  CObArray::SetSize  
 Establishes the size of an empty or existing array; allocates memory if necessary.

void SetSize( INT_PTR nNewSize,
INT_PTR nGrowBy = -1);

  
### Parameters  
 `nNewSize`  
 The new array size (number of elements). Must be greater than or equal to 0.  
  
 `nGrowBy`  
 The minimum number of element slots to allocate if a size increase is necessary.  
  
### Remarks  
 If the new size is smaller than the old size, then the array is truncated and all unused memory is released. For efficiency, call `SetSize` to set the size of the array before using it. This prevents the need to reallocate and copy the array each time an item is added.  
  
 The `nGrowBy` parameter affects internal memory allocation while the array is growing. Its use never affects the array size as reported by `GetSize` and `GetUpperBound`.  
  
 If the size of the array has grown, all newly allocated **CObject \*** pointers are set to NULL.  
  
 The following table shows other member functions that are similar to `CObArray::SetSize`.  
  
|Class|Member Function|  
|-----------|---------------------|  
|[CByteArray](../Topic/CByteArray%20Class.md)|**void SetSize( INT_PTR** `nNewSize` **, int** `nGrowBy` **= -1 );**<br /><br /> **throw( CMemoryException\* );**|  
|[CDWordArray](../Topic/CDWordArray%20Class.md)|**void SetSize( INT_PTR** `nNewSize` **, int** `nGrowBy` **= -1 );**<br /><br /> **throw( CMemoryException\* );**|  
|[CPtrArray](../Topic/CPtrArray%20Class.md)|**void SetSize( INT_PTR** `nNewSize` **, int** `nGrowBy` **= -1 );**<br /><br /> **throw( CMemoryException\* );**|  
|[CStringArray](../Topic/CStringArray%20Class.md)|**void SetSize( INT_PTR** `nNewSize` **, int** `nGrowBy` **= -1 );**<br /><br /> **throw( CMemoryException\* );**|  
|[CUIntArray](../Topic/CUIntArray%20Class.md)|**void SetSize( INT_PTR** `nNewSize` **, int** `nGrowBy` **= -1 );**<br /><br /> **throw( CMemoryException\* );**|  
|[CWordArray](../Topic/CWordArray%20Class.md)|**void SetSize( INT_PTR** `nNewSize` **, int** `nGrowBy` **= -1 );**<br /><br /> **throw( CMemoryException\* );**|  
  
### Example  
  See the example for [CObArray::GetData](#cobarray__getdata).  
  
## See Also  
 [CObject Class](../Topic/CObject%20Class.md)   
 [Hierarchy Chart](../Topic/Hierarchy%20Chart.md)   
 [CStringArray Class](../Topic/CStringArray%20Class.md)   
 [CPtrArray Class](../Topic/CPtrArray%20Class.md)   
 [CByteArray Class](../Topic/CByteArray%20Class.md)   
 [CWordArray Class](../Topic/CWordArray%20Class.md)   
 [CDWordArray Class](../Topic/CDWordArray%20Class.md)

Share via

CObArray Class

Syntax

Members

Public Constructors

Public Methods

Public Operators

Remarks

Inheritance Hierarchy

Requirements

CObArray::Add

Parameters

Return Value

Remarks

Example

CObArray::Append

Parameters

Return Value

Remarks

Example

CObArray::Copy

Parameters

Remarks

Example

CObArray::CObArray

Remarks

Example

CObArray::ElementAt

Parameters

Return Value

Remarks

Example

CObArray::FreeExtra

Remarks

Example

CObArray::GetAt

Parameters

Return Value

Remarks

Example

CObArray::GetCount

Return Value

Remarks

Example

CObArray::GetData

Additional resources