Two sizing parameters are passed to IVectorModel_EnsureCapacity() -- one that specifies the minimum number of items that will be needed by the vector model, and one that specifies the number of items that the model should grow when adding items beyond the minimum required size of the model. To illustrate, consider a vector model that currently contains 8 items. If IVectorModel_EnsureCapacit()y is called specifying a required minimum of 20 items, with a growth factor of 5 items, the following will happen:
- The vector model will immediately grow to 20 items, adding space for 20 - 8 = 12 items. - New items added or inserted into the vector model will consume the newly allocated (but unoccupied) space. - At the point at which an added item would cause the model to grow beyond the current allocated space of 20 items, space for 5 additional items will be allocated by the vector model.
- po:Pointer to the IVectorModel interface object.
- nRequired:The minimum number of items that will be required by the vector model. The vector model will immediately grow to contain space for exactly this number of items (or fail, if additional memory could not be allocated).
- nGrowBy:Indicates the number of additional items that should be allocated when adding or inserting items beyond the currently allocated number of items.
int IVectorModel_EnsureCapacity(IVectorModel *po, uint32 nRequired, uint32 nGrowBy);
AEE_SUCCESS - The vector model was able to size itself to be at least nRequired items. ENOMEMORY - The vector model was unable to allocate enough memory to accommodate the number of required items.
The size of the vector model will change only if the currently allocated number of items is less than the number of required items. When nRequired is less than the current size of the vector model, the model does _not_ shrink to the specified size.