RemoveItem (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (1 revision) |
||
| (10 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Stringlist:RemoveItem subtitle}} | {{Template:Stringlist:RemoveItem subtitle}} | ||
This callable method removes an item from a Stringlist, decrementing the item numbers of all items which follow. If removal of an item makes a CCATEMP Stringlist page empty, that page is removed from use by the Stringlist. Otherwise, space taken up by a removed item is made available on the Stringlist page for other items in the same Stringlist. | This [[Notation conventions for methods#Callable functions|callable]] method removes an item from a <var>Stringlist</var>, decrementing the item numbers of all items which follow. If removal of an item makes a CCATEMP <var>Stringlist</var> page empty, that page is removed from use by the <var>Stringlist</var>. Otherwise, space taken up by a removed item is made available on the <var>Stringlist</var> page for other items in the same <var>Stringlist</var>. | ||
==Syntax== | ==Syntax== | ||
| Line 7: | Line 7: | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>% | <tr><th>%count</th> | ||
<td> | <td>An optional, numeric variable to contain the number of items remaining in the <var>Stringlist</var> after the item has been removed.</td></tr> | ||
<tr><th>sl</th> | <tr><th>sl</th> | ||
<td>A Stringlist object.</td></tr> | <td>A <var>Stringlist</var> object.</td></tr> | ||
<tr><th> | <tr><th>itemNum</th> | ||
<td>A number that specifies the item number in the Stringlist.</td></tr> | <td>A number that specifies the item number in the <var>Stringlist</var> to be removed.</td></tr> | ||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul><li>All errors in RemoveItem result in request cancellation.<li>Consecutive Stringlist leaf pages that are made relatively empty with RemoveItem will not be merged together. Because of this, heavy use of Insert and RemoveItem can result in "sparse" | <ul><li>All errors in <var>RemoveItem</var> result in request cancellation.<li>Consecutive <var>Stringlist</var> leaf pages that are made relatively empty with <var>RemoveItem</var> will not be merged together. Because of this, heavy use of <var>[[Insert (Stringlist function)|Insert]]</var> and <var>RemoveItem</var> can result in "sparse" <var>Stringlist</var>s which place an unnecessary burden on the buffer pool and CCATEMP.<li>Heavy use of <var>[[Insert (Stringlist function)|Insert]]</var> and <var>RemoveItem</var> can result in an inability to add an item to the end of the <var>Stringlist</var> (via the <var>[[Add (Stringlist function)|Add]]</var> method) because of a full pointer page, even though the <var>Stringlist</var> is nowhere near the theoretical capacity for a <var>Stringlist</var>. 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== | |||
{{Template:Stringlist:RemoveItem footer}} | |||
Latest revision as of 19:40, 14 July 2011
Remove item from Stringlist (Stringlist class)
This callable method removes an item from a Stringlist, decrementing the item numbers of all items which follow. If removal of an item makes a CCATEMP Stringlist page empty, that page is removed from use by the Stringlist. Otherwise, space taken up by a removed item is made available on the Stringlist page for other items in the same Stringlist.
Syntax
[%count =] sl:RemoveItem( itemNum)
Syntax terms
| %count | An optional, numeric variable to contain the number of items remaining in the Stringlist after the item has been removed. |
|---|---|
| sl | A Stringlist object. |
| itemNum | A number that specifies the item number in the Stringlist to be removed. |
Usage notes
- All errors in RemoveItem result in request cancellation.
- Consecutive Stringlist leaf pages that are made relatively empty with RemoveItem will not be merged together. Because of this, heavy use of Insert and RemoveItem can result in "sparse" Stringlists which place an unnecessary burden on the buffer pool and CCATEMP.
- Heavy use of Insert and RemoveItem can result in an inability to add an item to the end of the Stringlist (via the Add method) because of a full pointer page, even though the Stringlist is nowhere near the theoretical capacity for a Stringlist. 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.