AddUniqueOrdered (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (1 revision)
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 there. It inserts the item at the proper position to maintain the <var>Stringlist</var>'s order. AddUniqueOrdered can also be written '''AddOrderedUnique'''.
This callable method adds an item to a (presumably) ordered <var>Stringlist</var> if an identical item is not already there. It inserts the item at the proper position to maintain the <var>Stringlist</var>'s order. <var>AddUniqueOrdered</var> can also be written '''AddOrderedUnique'''.


AddUniqueOrdered accepts one argument and returns one of the following:
<var>AddUniqueOrdered</var> accepts one argument and returns one of the following:


<ul>
<ul>
Line 10: Line 10:
</ul>
</ul>


AddUniqueOrdered is a member of the [[Stringlist class]].
<var>AddUniqueOrdered</var> is a member of the [[Stringlist class]].


==Syntax==
==Syntax==
Line 26: Line 26:
==Usage notes==
==Usage notes==
<ul>
<ul>
<li>All errors in AddUniqueOrdered result in request cancellation.
<li>All errors in <var>AddUniqueOrdered</var> result in request cancellation.
<li>AddUniqueOrdered 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 in EBCDIC order. AddUniqueOrdered assumes that the <var>Stringlist</var> is 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 <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 in EBCDIC order. <var>AddUniqueOrdered</var> assumes that the <var>Stringlist</var> is 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>Because AddUniqueOrdered 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 [[Insert (Stringlist function)]].
<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 [[Insert (Stringlist function)]].
</ul>
</ul>


==Examples==
==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 <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 AddUniqueOrdered. 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:


<pre>
<pre>

Revision as of 16:11, 19 January 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 there. 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.

AddUniqueOrdered is a member of the Stringlist class.

Syntax

[%number =] sl:AddUniqueOrdered( string)

Syntax terms

%rc 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 the Stringlist.

Usage notes

  • All errors in AddUniqueOrdered result in request cancellation.
  • 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 in EBCDIC order. AddUniqueOrdered assumes that the Stringlist is 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.
  • 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 Insert (Stringlist function).

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