Replace (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (1 revision)
Line 18: Line 18:


==Usage notes==
==Usage notes==
<ul><li>All errors in Replace 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 Longstring 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>Replace is extremely efficient if the <var>Stringlist</var> item size is not being changed (return value for Replace 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 RemoveItem invocations make this possible. Because of this, heavy use of Replace calls that increase <var>Stringlist</var> item size (and Insert and RemoveItem) 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 the [[CopyItems (Stringlist function)]].</ul>
<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 Longstring 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). <var>Replace</var>ment 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 RemoveItem invocations make this possible. Because of this, heavy use of <var>Replace</var> calls that increase <var>Stringlist</var> item size (and Insert and RemoveItem) 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 the [[CopyItems (Stringlist function)]].</ul>


[[Category:Stringlist methods|Replace function]]
[[Category:Stringlist methods|Replace function]]

Revision as of 16:12, 19 January 2011

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.
itemnum The number of the item that is to be replaced.
string A string that is to replace the itemnum 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 Longstring 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 the CopyItems (Stringlist function).