Replace (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
mNo edit summary |
||
| Line 1: | Line 1: | ||
{{Template:Stringlist:Replace subtitle}} | |||
Replace is a member of the [[Stringlist class]]. | Replace is a member of the [[Stringlist class]]. | ||
| Line 5: | Line 5: | ||
This callable method replaces an existing Stringlist item with a string. | This callable method replaces an existing Stringlist item with a string. | ||
== | ==Syntax== | ||
{{Template:Stringlist:Replace syntax}} | |||
===Syntax terms=== | |||
===Syntax | |||
<dl> | <dl> | ||
<dt>%rc<dd>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.<dt>%sl<dd>A Stringlist object.<dt>itemnum<dd>The number of the item that is to be replaced.<dt>string<dd>A string that is to replace the '''itemnum''' Stringlist item. </dl> | <dt>%rc<dd>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.<dt>%sl<dd>A Stringlist object.<dt>itemnum<dd>The number of the item that is to be replaced.<dt>string<dd>A string that is to replace the '''itemnum''' Stringlist item. </dl> | ||
==Usage | ==Usage notes== | ||
<ul><li>All errors in Replace result in request cancellation.<li>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.<li>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)]].</ul> | <ul><li>All errors in Replace result in request cancellation.<li>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.<li>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)]].</ul> | ||
[[Category:Stringlist methods|Replace function]] | [[Category:Stringlist methods|Replace function]] | ||
Revision as of 20:00, 31 December 2010
Replace a Stringlist item with a string (Stringlist class)
Replace is a member of the 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).