AddUniqueOrdered (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
m (Better linking) |
m (1 revision) |
||
| (16 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Stringlist:AddUniqueOrdered subtitle}} | {{Template:Stringlist:AddUniqueOrdered subtitle}} | ||
This callable method adds an item to a (presumably) ordered <var>Stringlist</var> if an identical item is not already present. It inserts the item at the proper position to maintain the <var>Stringlist</var> | This [[Notation conventions for methods#Callable functions|callable]] method adds an item to a (presumably) ordered <var>Stringlist</var> if an identical item is not already present. It inserts the item at the proper position to maintain the <var>Stringlist's</var> order. <var>AddUniqueOrdered</var> can also be written <var>AddOrderedUnique</var>. | ||
<var>AddUniqueOrdered</var> accepts one argument and returns one of the following: | <var>AddUniqueOrdered</var> accepts one argument and returns one of the following: | ||
| Line 9: | Line 9: | ||
<li>The negative of the item number that exactly matches the string being added. | <li>The negative of the item number that exactly matches the string being added. | ||
</ul> | </ul> | ||
==Syntax== | ==Syntax== | ||
| Line 17: | Line 15: | ||
<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 <var class="term">string</var | <td>A numeric variable to contain the item number of the added <var class="term">string</var>, or the negative item number of an item that already contains the <var class="term">string</var>.</td></tr> | ||
<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>string</th> | <tr><th>string</th> | ||
<td>A string that is to be added to | <td>A string that is to be added to <var class="term">sl</var>.</td></tr> | ||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul> | <ul> | ||
<li>All errors in <var>AddUniqueOrdered</var> result in request cancellation. | <li>All errors in <var>AddUniqueOrdered</var> result in request cancellation.<li><var>AddUniqueOrdered</var> assumes that the <var>Stringlist</var> is already in EBCDIC order, so it does a pseudo binary search to locate a match or the correct insertion point. <var>AddUniqueOrdered</var> does not validate that the <var>Stringlist</var> is in order, and if it is not in order, the insertion point or detection of a match is unpredictable.<li><var>AddUniqueOrdered</var> adds the indicated string to the <var>Stringlist</var> only if no identical <var>Stringlist</var> item already exists on the <var>Stringlist</var>. If the there are no matching items, the new item is inserted so that the <var>Stringlist</var> is maintained in EBCDIC order. | ||
<li> | |||
<li>Because <var>AddUniqueOrdered</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. | <li>Because <var>AddUniqueOrdered</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> | </ul> | ||
| Line 33: | Line 30: | ||
==Examples== | ==Examples== | ||
<var>AddUniqueOrdered</var> returns the item number added or inserted (if no match was found) or the negative item number of the matching item (if one was found). This return code makes it easy to maintain a parallel <var>Stringlist</var> that contains, say, a count of the number of times a given value occurred, that is, was passed as a string to <var>AddUniqueOrdered</var>. The following example illustrates such an approach: | <var>AddUniqueOrdered</var> returns the item number added or inserted (if no match was found) or the negative item number of the matching item (if one was found). This return code makes it easy to maintain a parallel <var>Stringlist</var> that contains, say, a count of the number of times a given value occurred, that is, was passed as a string to <var>AddUniqueOrdered</var>. The following example illustrates such an approach: | ||
<p class="code">%in = %olist:addUniqueOrdered(%data) | <p class="code">%in = %olist:addUniqueOrdered(%data) | ||
if %in gt 0 then | if %in gt 0 then | ||
| Line 43: | Line 39: | ||
</p> | </p> | ||
==See also== | |||
{{Template:Stringlist:AddUniqueOrdered footer}} | |||
Latest revision as of 19:40, 14 July 2011
Conditionally add an item to an ordered Stringlist (Stringlist class)
This callable method adds an item to a (presumably) ordered Stringlist if an identical item is not already present. It inserts the item at the proper position to maintain the Stringlist's order. AddUniqueOrdered can also be written AddOrderedUnique.
AddUniqueOrdered accepts one argument and returns one of the following:
- The item number of the inserted string.
- The negative of the item number that exactly matches the string being added.
Syntax
[%number =] sl:AddUniqueOrdered( string)
Syntax terms
| %number | A numeric variable to contain the item number of the added string, or the negative item number of an item that already contains the string. |
|---|---|
| sl | A Stringlist object. |
| string | A string that is to be added to sl. |
Usage notes
- All errors in AddUniqueOrdered result in request cancellation.
- AddUniqueOrdered assumes that the Stringlist is already in EBCDIC order, so it does a pseudo binary search to locate a match or the correct insertion point. AddUniqueOrdered does not validate that the Stringlist is in order, and if it is not in order, the insertion point or detection of a match is unpredictable.
- AddUniqueOrdered adds the indicated string to the Stringlist only if no identical Stringlist item already exists on the Stringlist. If the there are no matching items, the new item is inserted so that the Stringlist is maintained in EBCDIC order.
- Because AddUniqueOrdered 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
AddUniqueOrdered returns the item number added or inserted (if no match was found) or the negative item number of the matching item (if one was found). This return code makes it easy to maintain a parallel Stringlist that contains, say, a count of the number of times a given value occurred, that is, was passed as a string to AddUniqueOrdered. The following example illustrates such an approach:
%in = %olist:addUniqueOrdered(%data) if %in gt 0 then %clist:insert(%in, 1) else %in = -%in %clist:replace(%in, %clist:item(%in) +1 ) end if