Insert (Stringlist function)
Insert strings into a Stringlist (Stringlist class)
This callable method inserts one or more strings into a Stringlist at a specific location.
Syntax
[%count =] sl:Insert( itemNum, itemList)
Syntax terms
| %count | A numeric variable to contain the number of items in sl after the strings have been inserted. |
|---|---|
| sl | A Stringlist object. |
| itemNum | The item number before which the strings are to be inserted. If itemNum is equal to the number of items in the Stringlist plus one, the strings are added to the end of the Stringlist (the same effect as an Add invocation). Because the strings are inserted before the indicated item number, itemNum is also the item number of the first new Stringlist item after Insert returns. |
| itemList | Under Sirius Mods 7.9 and later, this is a comma-delimited set of strings, each of which, from left to right, is inserted into the method object Stringlist. The items in the list could themselves be Stringlists, in which case each item in the input Stringlist is inserted into the target Stringlist. Under Sirius Mods 7.8 and earlier, itemList could only be a single string that is to be inserted into the Stringlist. |
Usage notes
- All errors in Insert result in request cancellation.
- An Insert can result in the splitting of a stringlist leaf page. Once a leaf page is split, it will not be merged back together again, even if subsequent RemoveItem invocations make this possible. Because of this splitting, heavy use of Insert and RemoveItem can result in "sparse" stringlists which place an unnecessary burden on the buffer pool and CCATEMP. To make matters worse, Copy does a page-for-page copy of a stringlist, so it does not result in any compression of the resultant stringlist. stringlist compression can be achieved using the CopyItems.
Examples
Inserting a single item to a Stringlist
In the following example, four comma-delimited field values are inserted into the start of a Stringlist for each record in a Recordset:
%list is object stringList ... %list = new for each record in %recset %data = ssn with ',' with lname with ',' - fname with ',' with mi %list:insert(1, %data) end for
Inserting multiple items to a Stringlist
In the following example, a string literal, the contents of a variable, and the contents of anotherStringlist are inserted into a Stringlist:
b %sl is object stringlist %python is string len 32 %stooges is object stringlist %stooges = list('Moe', 'Larry', 'Curly') %sl = list('John', 'Michael', 'Eric') %python = 'Graham' %sl:insert(3, 'Terry', %python, %stooges) %sl:print end
This outputs:
John Michael Terry Graham Moe Larry Curly Eric