AddOrdered (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
m (→Syntax terms) |
m (1 revision) |
||
| (22 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Stringlist:AddOrdered subtitle}} | {{Template:Stringlist:AddOrdered subtitle}} | ||
This method adds an item to a (presumably) ordered Stringlist, inserting the item at the proper position to maintain the Stringlist's order. AddOrdered accepts one argument and returns the item number of the inserted string. AddOrdered is a callable method. | This method adds an item to a (presumably) ordered <var>Stringlist</var>, inserting the item at the proper position to maintain the <var>Stringlist</var>'s order. <var>AddOrdered</var> accepts one argument and returns the item number of the inserted string. <var>AddOrdered</var> is a [[Notation conventions for methods#Callable functions|callable]] method. | ||
==Syntax== | ==Syntax== | ||
| Line 8: | Line 8: | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%number</th> | <tr><th>%number</th> | ||
<td>A numeric variable to contain the item number of the added string in the Stringlist.</td></tr> | <td>A numeric variable to contain the item number of the added string in the <var>Stringlist</var>.</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>string</th> | <tr><th>string</th> | ||
<td>A string that is to be added to the Stringlist.</td></tr> | <td>A string that is to be added to the <var>Stringlist</var>.</td></tr> | ||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul><li>All errors in AddOrdered result in request cancellation.<li>AddOrdered | <ul><li>All errors in <var>AddOrdered</var> result in request cancellation.<li><var>AddOrdered</var> assumes that the <var>Stringlist</var> is already in EBCDIC order, so it does a pseudo binary search to locate the correct insertion point. <var>AddOrdered</var> does not validate that the <var>Stringlist</var> is in order; if it is not in order, the insertion point is unpredictable.<li><var>AddOrdered</var> always adds the indicated string, even if that string already exists on the <var>Stringlist</var>, with the new item being inserted so that the <var>Stringlist</var> is maintained in EBCDIC order. | ||
<li>Because <var>AddOrdered</var> will insert items into the middle of a <var>Stringlist</var>, it is susceptible to the same page-splitting, sparse <var>Stringlist</var> leaf-page issues as the <var>[[Insert (Stringlist function)|Insert]]</var> method.</ul> | |||
==Examples== | ==Examples== | ||
The following code builds a sorted output Stringlist from an input Stringlist: | The following code builds a sorted output <var>Stringlist</var> from an input <var>Stringlist</var>: | ||
<p class="code">for %i from 1 to %inlist:count | |||
< | %string = %inlist:item(%i) | ||
for %i from 1 to %inlist:count | %outlist:addOrdered(%string) | ||
%string = %inlist:item(%i) | |||
%outlist:addOrdered(%string) | |||
end for | end for | ||
</ | </p> | ||
While it is generally more efficient to simply copy and sort (via the <var>[[SortNew (Stringlist_function)|SortNew]]</var> method) the input <var>Stringlist</var>, the technique above might be useful if the target <var>Stringlist</var> already has a large number of items. | |||
While it is generally more efficient to simply copy and sort (via the SortNew method) the input Stringlist, the technique above might be useful if the target Stringlist already has a large number of items. | |||
==See also== | |||
{{Template:Stringlist:AddOrdered footer}} | |||
Latest revision as of 19:40, 14 July 2011
Add an item to an ordered Stringlist (Stringlist class)
This method adds an item to a (presumably) ordered Stringlist, inserting the item at the proper position to maintain the Stringlist's order. AddOrdered accepts one argument and returns the item number of the inserted string. AddOrdered is a callable method.
Syntax
[%number =] sl:AddOrdered( string)
Syntax terms
| %number | A numeric variable to contain the item number of the added string in the Stringlist. |
|---|---|
| sl | A Stringlist object. |
| string | A string that is to be added to the Stringlist. |
Usage notes
- All errors in AddOrdered result in request cancellation.
- AddOrdered assumes that the Stringlist is already in EBCDIC order, so it does a pseudo binary search to locate the correct insertion point. AddOrdered does not validate that the Stringlist is in order; if it is not in order, the insertion point is unpredictable.
- AddOrdered always adds the indicated string, even if that string already exists on the Stringlist, with the new item being inserted so that the Stringlist is maintained in EBCDIC order.
- Because AddOrdered will insert items into the middle of a Stringlist, it is susceptible to the same page-splitting, sparse Stringlist leaf-page issues as the Insert method.
Examples
The following code builds a sorted output Stringlist from an input Stringlist:
for %i from 1 to %inlist:count %string = %inlist:item(%i) %outlist:addOrdered(%string) end for
While it is generally more efficient to simply copy and sort (via the SortNew method) the input Stringlist, the technique above might be useful if the target Stringlist already has a large number of items.