Developer

API Reference

IVectorModel_EnsureCapacity()

Brew Release
Brew MP 1.0.2
See Also
IVectorModel Interface IVectorModel_Add() IVectorModel_InsertAt()
Description
This function allows callers to preflight the memory that will be needed by a vector model. For example, if an implementation knows ahead of time that it will require, as a minimum, some established number of data items, it may allocate the storage for these items in one operation and know immediately whether or not there is sufficient memory to support the entire collection of data. This is more efficient than calling IVectorModel_Add() for every item in the collection, only to encounter a failure well into the allocation of items.
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.

Parameters
  • 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.
Interface
Prototype
   int IVectorModel_EnsureCapacity(IVectorModel *po, uint32 nRequired, uint32 nGrowBy);
Return
   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.
Side Effect
None
Comment
IVectorModel_EnsureCapacity() only ensures that there is enough space in the vector model for the item pointers; it does not ensure that there is enough memory available for the memory required by the individual items. Applications may also wish to preflight the memory that would be required for the individual item contents, if they wish to make absolutely sure that memory is available to accommodate a large allocation of vector 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.
  • Follow