Insert (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
m (camelCase) |
m (better tagging all the time) |
||
| Line 12: | Line 12: | ||
<td>A <var>Stringlist</var> object. </td></tr> | <td>A <var>Stringlist</var> object. </td></tr> | ||
<tr><th>itemNum</th> | <tr><th>itemNum</th> | ||
<td>The item number before which the string is to be inserted. If <var class="term"> | <td>The item number before which the string is to be inserted. If <var class="term">itemNum</var> is equal to the number of items in the <var>Stringlist</var> plus one, <var class="term">string</var> is added to the end of the <var>Stringlist</var> (the same effect as an <var>[[Add (Stringlist function)|Add]]</var> invocation). Because the string is inserted before the indicated item number, <var class="term">itemNum</var> is also the item number of the new <var>Stringlist</var> item after <var>Insert</var> returns. </td></tr> | ||
<tr><th>string</th> | <tr><th>string</th> | ||
<td>A <var class="term">string</var> that is to be inserted into the <var>sl</var> <var>Stringlist</var>.</td></tr> | <td>A <var class="term">string</var> that is to be inserted into the <var class="term">sl</var> <var>Stringlist</var>.</td></tr> | ||
</table> | </table> | ||
| Line 21: | Line 21: | ||
<li>All errors in <var>Insert</var> result in request cancellation. | <li>All errors in <var>Insert</var> result in request cancellation. | ||
<li>Before <var class="product">Sirius Mods</var> Version 6.6, it was a request canceling error to try to insert a string longer than the size limit of a <var>Stringlist</var> item: 6124 bytes. This limitation was eliminated in <var class="product">Sirius Mods</var> Version 6.6. | <li>Before <var class="product">Sirius Mods</var> Version 6.6, it was a request canceling error to try to insert a string longer than the size limit of a <var>Stringlist</var> item: 6124 bytes. This limitation was eliminated in <var class="product">Sirius Mods</var> Version 6.6. | ||
<li>An <var>Insert</var> can result in the splitting of a <var>stringlist</var> leaf page. Once a leaf page is split, it will not be merged back together, even if subsequent <var>[[RemoveItem (Stringlist function)|RemoveItem]]</var> invocations make this possible. Because of this splitting, heavy use of <var>Insert</var> and <var>[[RemoveItem (Stringlist function)|RemoveItem]]</var> can result in "sparse" <var>stringlists</var> which place an unnecessary burden on the buffer pool and CCATEMP. To make matters worse, <var>[[Copy (Stringlist function)|Copy]]</var> does a page-for-page copy of a <var>stringlist</var>, so it does not result in any compression of the resultant <var>stringlist</var>. <var>stringlist</var> compression can be achieved using the <var>[[CopyItems (Stringlist function)|CopyItems]]</var>.</ul> | <li>An <var>Insert</var> can result in the splitting of a <var>stringlist</var> leaf page. Once a leaf page is split, it will not be merged back together again, even if subsequent <var>[[RemoveItem (Stringlist function)|RemoveItem]]</var> invocations make this possible. Because of this splitting, heavy use of <var>Insert</var> and <var>[[RemoveItem (Stringlist function)|RemoveItem]]</var> can result in "sparse" <var>stringlists</var> which place an unnecessary burden on the buffer pool and CCATEMP. To make matters worse, <var>[[Copy (Stringlist function)|Copy]]</var> does a page-for-page copy of a <var>stringlist</var>, so it does not result in any compression of the resultant <var>stringlist</var>. <var>stringlist</var> compression can be achieved using the <var>[[CopyItems (Stringlist function)|CopyItems]]</var>.</ul> | ||
==See also== | ==See also== | ||
{{Template:Stringlist:Insert footer}} | {{Template:Stringlist:Insert footer}} | ||
Revision as of 02:18, 27 January 2011
Insert strings into a Stringlist (Stringlist class)
This callable method inserts a string 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 string has been inserted. |
|---|---|
| sl | A Stringlist object. |
| itemNum | The item number before which the string is to be inserted. If itemNum is equal to the number of items in the Stringlist plus one, string is added to the end of the Stringlist (the same effect as an Add invocation). Because the string is inserted before the indicated item number, itemNum is also the item number of the new Stringlist item after Insert returns. |
| string | A string that is to be inserted into the sl Stringlist. |
Usage notes
- All errors in Insert result in request cancellation.
- Before Sirius Mods Version 6.6, it was a request canceling error to try to insert a string longer than the size limit of a Stringlist item: 6124 bytes. This limitation was eliminated in Sirius Mods Version 6.6.
- 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.