CObArray::InsertAt

  • Article

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

void InsertAt( INT_PTR nIndex, BYTE newElement, int nCount = 1 );

    throw( CMemoryException* );

void InsertAt( INT_PTR nStartIndex, CByteArray* pNewArray );

    throw( CMemoryException* );

CDWordArray

void InsertAt( INT_PTR nIndex, DWORD newElement, int nCount = 1 );

    throw( CMemoryException* );

void InsertAt( INT_PTR nStartIndex, CDWordArray* pNewArray );

    throw( CMemoryException* );

CPtrArray

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

    throw( CMemoryException* );

void InsertAt( INT_PTR nStartIndex, CPtrArray* pNewArray );

    throw( CMemoryException* );

CStringArray

void InsertAt( INT_PTR nIndex, LPCTSTR newElement, int nCount = 1 );

    throw( CMemoryException* );

void InsertAt( INT_PTR nStartIndex, CStringArray* pNewArray );

    throw( CMemoryException* );

CUIntArray

void InsertAt( INT_PTR nIndex, UINT newElement, int nCount = 1 );

    throw( CMemoryException* );

void InsertAt( INT_PTR nStartIndex, CUIntArray* pNewArray );

    throw( CMemoryException* );

CWordArray

void InsertAt( INT_PTR nIndex, WORD newElement, int nCount = 1 );

    throw( CMemoryException* );

void InsertAt( INT_PTR nStartIndex, CWordArray* pNewArray );

    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 (will become 2).
arr.InsertAt(1, new CAge(30));  // New element 1
#ifdef _DEBUG
   afxDump.SetDepth(1);
   afxDump << _T("InsertAt example: ") << &arr << _T("\n");
#endif

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

Requirements

Header: afxcoll.h

See Also

Reference

CObArray Class

Hierarchy Chart

CObArray::SetAt

CObArray::RemoveAt

Other Resources

CObArray Members