Futurebasic/Language/Reference/def dynamicinsertitems

DEF DYNAMICINSERTITEMS Statement

DEF DYNAMICINSERTITEMS

Statement

✔ Appearance ✔ Standard ✔ Console

Syntax

DEF DYNAMICINSERTITEMS(gMyDynamicArray, Where&, HowMany&, FillPtr&)

Revised

November 2006 (FB 4, Release 4)

Description

This function shifts item Where& and all subsequent items in gMyDynamicArray, 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.

Note

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 DYNAMIC or DIMÊDYNAMIC.

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. DEF DYNAMICINSERTITEMS does not check to ensure there is adequate data to copy.

See Also

DEF DYNAMICREMOVEITEMS; DYNAMIC; USR DYNAMICITEMSIZE