Skip to content

Latest commit

 

History

History
809 lines (534 loc) · 34 KB

cobarray-class.md

File metadata and controls

809 lines (534 loc) · 34 KB
title description ms.date f1_keywords helpviewer_keywords
CObArray Class
API reference for the `CObArray` `MFC` class which stores `CObject` pointers in an array.
08/27/2020
CObArray
AFXCOLL/CObArray
AFXCOLL/CObArray::CObArray
AFXCOLL/CObArray::Add
AFXCOLL/CObArray::Append
AFXCOLL/CObArray::Copy
AFXCOLL/CObArray::ElementAt
AFXCOLL/CObArray::FreeExtra
AFXCOLL/CObArray::GetAt
AFXCOLL/CObArray::GetCount
AFXCOLL/CObArray::GetData
AFXCOLL/CObArray::GetSize
AFXCOLL/CObArray::GetUpperBound
AFXCOLL/CObArray::InsertAt
AFXCOLL/CObArray::IsEmpty
AFXCOLL/CObArray::RemoveAll
AFXCOLL/CObArray::RemoveAt
AFXCOLL/CObArray::SetAt
AFXCOLL/CObArray::SetAtGrow
AFXCOLL/CObArray::SetSize
CObArray [MFC], CObArray
CObArray [MFC], Add
CObArray [MFC], Append
CObArray [MFC], Copy
CObArray [MFC], ElementAt
CObArray [MFC], FreeExtra
CObArray [MFC], GetAt
CObArray [MFC], GetCount
CObArray [MFC], GetData
CObArray [MFC], GetSize
CObArray [MFC], GetUpperBound
CObArray [MFC], InsertAt
CObArray [MFC], IsEmpty
CObArray [MFC], RemoveAll
CObArray [MFC], RemoveAt
CObArray [MFC], SetAt
CObArray [MFC], SetAtGrow
CObArray [MFC], SetSize

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.

[!code-cppNVC_MFCCollections#75]

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.

[!code-cppNVC_MFCCollections#76]

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 doesn't free memory. 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.

[!code-cppNVC_MFCCollections#77]

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

[!code-cppNVC_MFCCollections#78]

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's used to implement the left-side assignment operator for arrays. 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 const 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.

[!code-cppNVC_MFCCollections#79]

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.

[!code-cppNVC_MFCCollections#80]

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 const BYTE* GetData() const; BYTE* GetData();
CDWordArray const DWORD* GetData() const; DWORD* GetData();
CPtrArray const void** GetData() const; void** GetData();
CStringArray const CString* GetData() const; CString* GetData();
CUIntArray const UINT* GetData() const; UINT* GetData();
CWordArray const WORD* GetData() const; WORD* GetData();

Example

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

[!code-cppNVC_MFCCollections#81]

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 INT_PTR GetSize() const;
CDWordArray INT_PTR GetSize() const;
CPtrArray INT_PTR GetSize() const;
CStringArray INT_PTR GetSize() const;
CUIntArray INT_PTR GetSize() const;
CWordArray INT_PTR GetSize() const;

Example

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

[!code-cppNVC_MFCCollections#82]

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 INT_PTR GetUpperBound() const;
CDWordArray INT_PTR GetUpperBound() const;
CPtrArray INT_PTR GetUpperBound() const;
CStringArray INT_PTR GetUpperBound() const;
CUIntArray INT_PTR GetUpperBound() const;
CWordArray INT_PTR GetUpperBound() const;

Example

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

[!code-cppNVC_MFCCollections#83]

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 doesn't 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.

[!code-cppNVC_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

CObArray::IsEmpty

Determines if the array is empty.

BOOL IsEmpty() const;

Return Value

Nonzero if the array is empty; otherwise 0.

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 aren't 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 BYTE& operator [](INT_PTR nindex);

BYTE operator [](INT_PTR nindex) const;
CDWordArray DWORD& operator [](INT_PTR nindex);

DWORD operator [](INT_PTR nindex) const;
CPtrArray void*& operator [](INT_PTR nindex);

void* operator [](INT_PTR nindex) const;
CStringArray CString& operator [](INT_PTR nindex);

CString operator [](INT_PTR nindex) const;
CUIntArray UINT& operator [](INT_PTR nindex);

UINT operator [](INT_PTR nindex) const;
CWordArray WORD& operator [](INT_PTR nindex);

WORD operator [](INT_PTR nindex) const;

Example

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

[!code-cppNVC_MFCCollections#88]

CObArray::RemoveAll

Removes all the pointers from this array but doesn't 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 void RemoveAll();
CDWordArray void RemoveAll();
CPtrArray void RemoveAll();
CStringArray void RemoveAll();
CUIntArray void RemoveAll();
CWordArray void RemoveAll();

Example

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

[!code-cppNVC_MFCCollections#85]

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 doesn't 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 doesn't delete the object itself.

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

Class Member Function
CByteArray void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);
CDWordArray void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);
CPtrArray void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);
CStringArray void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);
CUIntArray void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);
CWordArray void RemoveAt(INT_PTR nIndex, INT_PTR nCount = 1);

Example

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

[!code-cppNVC_MFCCollections#112]

The results from this program are as follows:

RemoveAt example: A CObArray with 1 elements
[0] = a CAge at $4606 40

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 won't cause the array to grow. Use SetAtGrow if you want the array to grow automatically.

Ensure that your index value represents a valid position in the array. If it's 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 void SetAt(INT_PTR nIndex, BYTE newElement);
CDWordArray void SetAt(INT_PTR nIndex, DWORD newElement);
CPtrArray void SetAt(INT_PTR nIndex, void* newElement);
CStringArray void SetAt(INT_PTR nIndex, LPCTSTR newElement);
CUIntArray void SetAt(INT_PTR nIndex, UINT newElement);
CWordArray void SetAt(INT_PTR nIndex, WORD newElement);

Example

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

[!code-cppNVC_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

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 void SetAtGrow(INT_PTR nIndex, BYTE newElement);

throw(CMemoryException*);
CDWordArray void SetAtGrow(INT_PTR nIndex, DWORD newElement);

throw(CMemoryException*);
CPtrArray void SetAtGrow(INT_PTR nIndex, void* newElement);

throw( CMemoryException*);
CStringArray void SetAtGrow(INT_PTR nIndex, LPCTSTR newElement);

throw(CMemoryException*);
CUIntArray void SetAtGrow(INT_PTR nIndex, UINT newElement);

throw(CMemoryException*);
CWordArray void SetAtGrow(INT_PTR nIndex, WORD newElement);

throw(CMemoryException*);

Example

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

[!code-cppNVC_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

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 void SetSize(INT_PTR nNewSize, int nGrowBy = -1);

throw(CMemoryException*);
CDWordArray void SetSize(INT_PTR nNewSize, int nGrowBy = -1);

throw(CMemoryException*);
CPtrArray void SetSize(INT_PTR nNewSize, int nGrowBy = -1);

throw(CMemoryException*);
CStringArray void SetSize(INT_PTR nNewSize, int nGrowBy = -1);

throw(CMemoryException*);
CUIntArray void SetSize(INT_PTR nNewSize, int nGrowBy = -1);

throw(CMemoryException*);
CWordArray void SetSize(INT_PTR nNewSize, int nGrowBy = -1);

throw(CMemoryException*);

Example

See the example for CObArray::GetData.

See also

CObject Class
Hierarchy Chart
CStringArray Class
CPtrArray Class
CByteArray Class
CWordArray Class
CDWordArray Class