API Reference | developer.brewmp.com API Reference | developer.brewmp.com


API Reference


Brew Release
Brew MP 1.0.2
See Also
IVectorModel Interface IVectorModel_Add() IVectorModel_InsertAt()
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

Pointer to the IVectorModel interface object.
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).
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.
Side Effect
  • None
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.