AddUniqueOrdered (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
m (consistent example formatting) |
m (1 revision) |
||
| (9 intermediate revisions by 4 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's</var> order. <var>AddUniqueOrdered</var> can also be written <var>AddOrderedUnique</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 21: | Line 19: | ||
<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> | ||
| Line 31: | Line 29: | ||
==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: | |||
<p class="code">%in = %olist:addUniqueOrdered(%data) | <p class="code">%in = %olist:addUniqueOrdered(%data) | ||
if %in gt 0 then | if %in gt 0 then | ||
%clist:insert(%in, 1) | |||
else | else | ||
%in = -%in | |||
%clist:replace(%in, %clist:item(%in) +1 ) | %clist:replace(%in, %clist:item(%in) +1 ) | ||
end if | |||
</p> | </p> | ||
==See also== | ==See also== | ||
{{Template:Stringlist:AddUniqueOrdered footer}} | {{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