Replace (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (→Usage notes) |
||
| (10 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Stringlist:Replace subtitle}} | {{Template:Stringlist:Replace subtitle}} | ||
This callable method replaces an existing <var>Stringlist</var> item with a string. | This [[Notation conventions for methods#Callable functions|callable]] method replaces an existing <var>Stringlist</var> item with a string. | ||
==Syntax== | ==Syntax== | ||
| Line 11: | Line 11: | ||
<tr><th>sl</th> | <tr><th>sl</th> | ||
<td>A <var>Stringlist</var> object.</td></tr> | <td>A <var>Stringlist</var> object.</td></tr> | ||
<tr><th> | <tr><th>number</th> | ||
<td>The number of the item that is to be replaced.</td></tr> | <td>The number of the item that is to be replaced.</td></tr> | ||
<tr><th>string</th> | <tr><th>string</th> | ||
<td>A string that is to replace the | <td>A string that is to replace the <var class="term">number</var> <var>Stringlist</var> item.</td></tr> | ||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul><li>All errors in | <ul> | ||
<li>All errors in <var>Replace</var> result in request cancellation. | |||
[[ | <li>Before <var class="product">Sirius Mods</var> Version 6.6, it was a request-cancelling error to try to replace a <var>Stringlist</var> item with 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><var>Replace</var> is extremely efficient if the <var>Stringlist</var> item size is not being changed (return value for <var>Replace</var> of 0), fairly efficient when a <var>Stringlist</var> item is being replaced with a shorter string (return value of 1), and can be fairly expensive when a <var>Stringlist</var> item is being replaced with a longer string (return value of 2). Replacement with a longer string can be expensive because it 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, heavy use of <var>Replace</var> calls that increase <var>Stringlist</var> item size (and <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. <var>Stringlist</var> compression can be achieved using <var>[[CopyItems (Stringlist function)|CopyItems]]</var>. | |||
</ul> | |||
==See also== | |||
{{Template:Stringlist:Replace footer}} | |||
Latest revision as of 00:36, 1 November 2012
Replace a Stringlist item with a string (Stringlist class)
This callable method replaces an existing Stringlist item with a string.
Syntax
[%rc =] sl:Replace( number, string)
Syntax terms
| %rc | A numeric variable that is set to 0 if the new item length is the same as the replaced item length, 1 if it is shorter, or 2 if it is longer. |
|---|---|
| sl | A Stringlist object. |
| number | The number of the item that is to be replaced. |
| string | A string that is to replace the number Stringlist item. |
Usage notes
- All errors in Replace result in request cancellation.
- Before Sirius Mods Version 6.6, it was a request-cancelling error to try to replace a Stringlist item with a string longer than the size limit of a Stringlist item: 6124 bytes. This limitation was eliminated in Sirius Mods Version 6.6.
- Replace is extremely efficient if the Stringlist item size is not being changed (return value for Replace of 0), fairly efficient when a Stringlist item is being replaced with a shorter string (return value of 1), and can be fairly expensive when a Stringlist item is being replaced with a longer string (return value of 2). Replacement with a longer string can be expensive because it can result in the splitting of a Stringlist leaf page. Once a leaf page is split, it will not be merged back together, even if subsequent RemoveItem invocations make this possible. Because of this, heavy use of Replace calls that increase Stringlist item size (and Insert and RemoveItem) can result in "sparse" Stringlists which place an unnecessary burden on the buffer pool and CCATEMP. Stringlist compression can be achieved using CopyItems.