DynamicInsertItems( gMyDynamicArray, Where&, HowMany&, FillPtr& )
This function shifts item
Where& and all subsequent items in
HowMany& positions higher, to leave
HowMany& new items beginning at position
Where&. The total number of items in the array increases by
HowMany& (or more - see below), and the inserted items (beginning at
Where&) are filled with data located at
FillPtr&, or with zeros if
FillPtr& is 0.
Whether currently populated or not, a dynamic array must have held data at some point before being passed to this function.
gMyDynamicArray is any FutureBasic Dynamic Array previously dimensioned using
Where& is the array position at which the first item will be inserted. It must be >= 0.
Where& will normally be less than the current number of items in the array, but can be greater. If it is greater, enough new empty items will be inserted to provide
HowMany& items beginning at item
Where&. For example, if you have 10 items (0-9) in the array, and insert 2 items beginning at item #13, your array will hold the original 10 items, followed by 3 empty items (10-12), and the 2 inserted items (13-14) for a total of 15 items.
HowMany& specifies the number of items to be inserted. It also represents the number by which the index of any specific item higher in the array will increase.
FillPtr& is an address where new data are waiting to be inserted into
gMyDynamicArray. These must be in the same format, with the same size elements as
gMyDynamicArray. In OS 9, if you pass a dereferenced handle as
FillPtr&, you should first lock the handle.
DynamicInsertItems does not check to ensure there is adequate data to copy.