| Home | Table of Contents | Please view with Internet Explorer (version 5.00 or higher) and enable scripting. For reasons, see Browsing This Web Site. |
This function sets a new capacity for a DPA.
BOOL
DPA_Grow (
HDPA pdpa,
int cpCapacity);
The pdpa argument provides a handle to the DPA.
The cpCapacity argument provides the new capacity for the array, measured as a number of pointers.
The function returns TRUE to indicate success, else FALSE for failure.
This function arranges for the given DPA to have at least the given capacity for storing pointers. If the DPA has no memory currently allocated to its pointer array, the function seeks fresh memory from whichever heap was specified or implied when the DPA was created. If memory exists already for the pointer array but is not as large as wanted, the function seeks a reallocation. Either way, the capacity sought is calculated by rounding up from cpCapacity to a multiple of the current allocation unit.
The initial size of this allocation unit is set when the DPA is created, but this function may change it (including when called internally for other DPA functions). Specifically, after a successful allocation or reallocation of memory for the pointer array, if the allocation unit is less than 256 pointers, it gets doubled.
The function fails trivially if the given DPA handle is NULL. The function cannot reduce the memory used for the pointer array: it succeeds trivially if cpCapacity is not greater than the existing capacity.
A variation is known for an early implementation. Version 4.00 merely assumes that the DPA handle is not NULL.
The DPA_Grow function is exported from COMCTL32.DLL as ordinal 330 in version 3.50 and higher.
Though this function dates from as long ago as 1995, it was still not documented by Microsoft in the MSDN Library at least as late as the CD edition dated January 2004.
This function did, however, get documented in 2006. This article now uses Microsoft’s nomenclature.