Replace (Stringlist function)

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).