Developer

API Reference

IVectorModel_ReplaceAt()

Brew Release
Brew MP 1.0.2
See Also
Model Events ListModelEvent IVectorModel Interface IVectorModel_SetPfnFree()
Description
This function replaces the item stored at a specified index location within the model, with a different item. Callers provide to IVectorModel_ReplaceAt() the zero-based index of the item to be replaced, as well as a pointer to the replacement item. IVectorModel_ReplaceAt() merely replaces the original item pointer with a new item pointer and does not actually replace the original item contents. However, the memory occupied by the original item _will_ be released by the vector model's PFNMODEL_NOTIFY callback function, if such a callback has been established by a prior call to IVectorModel_SetPfnFree().
The figures below illustrates the state of the information stored in a vector model before and after calling IVectorModel_ReplaceAt(). Because items in the vector model are zero-based, the caller would specify an index that is one less than the item to be removed when calling IVectorModel_ReplaceAt(). For example, to replace the third item in the model, the caller would specify '2' as the index of the item to be replaced. In the figure, the item to be removed is stored at location index-1 in the array of item content pointers, and points to the contents of the original item.
         Vector Model before calling IVectorModel_ReplaceAt()
         
                                :
                                :
                   |--------------------------|   
  Item (index - 2) |                          |
                   |          void *      +---------> Points to the contents of item (index - 2)
                   |                          |
                   |--------------------------|
                   |                          |
  Item (index - 1) |      old void *      +--------->  --------------------------
                   |                          |       |                          |
                   |--------------------------|       |      Contents of the     |
                                :                     |       original item      |
                                :                     |                          |
                                                      |                          |
                                                       --------------------------

After calling IVectorModel_ReplaceAt(), the memory occupied by the original index-1 item will be released, and the original index-1 pointer will have been replaced by a new pointer, now pointing to the contents of the new item referenced by index-1.
         Vector Model after calling IVectorModel_ReplaceAt()
         
                                :
                                :
                   |--------------------------|   
  Item (index - 2) |                          |
                   |          void *      +---------> Points to the contents of item (index - 2)
                   |                          |
                   |--------------------------|
                   |                          |
  Item (index - 1) |      new void *      +-------     --------------------------
                   |                          |  |    |                          |
                   |--------------------------|  |    |        RELEASED!!!       |
                                :                |    |      Contents of the     |
                                :                |    |       original item      |
                                                 |    |                          |
                                                 |     --------------------------
                                                 |     
                                                  -->  --------------------------
                                                      |                          |
                                                      |                          |   
                                                      |      Contents of the     |
                                                      |          new item        |
                                                      |                          |
                                                       --------------------------
Parameters
  • nIndex
    []:
    Indicates the zero-based index of the item to be replaced. The first item in the model is indexed by 0, the second is indexed by 1, and so on...
  • pvItem
    []:
    Pointer to the contents of the new item that is replacing the item indexed by nIndex.
Interface
Prototype
   int IVectorModel_ReplaceAt(IVectorModel *pif, uint32 nIndex, void *pvItem)
   int IVectorModel_ReplaceAt(IVectorModel *po, uint32 nIndex, void *pvNew); 
Return
   AEE_SUCCESS   - The model was able to successfully replace the desired item.
   AEE_EBADPARM  - The requested index is not within the range of items stored in the model.
Side Effect
Replacing an item stored in a vector model by calling IVectorModel_ReplaceAt() will cause BREW to send an EVT_MDL_LIST_CHANGE ListModelEvent to any object that has registered as a listener with the model.
The fields of the ListModelEvent will contain the following information:
       pos:      The index of the vector item that has been replace. 
       oldSize:  The number of items in the vector model.
       newSize:  The number of items in the vector model.
Comment
The vector model may define a custom free memory routine to release the memory consumed by complex items. The custom free memory routine is registered with the vector model by calling IVectorModel_SetPfnFree().
  • Follow