AddUniqueOrdered (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
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. <var>AddUniqueOrdered</var> 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 <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 16: Line 16:
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%rc</th>
<tr><th>%number</th>
<td>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.</td></tr>
<td>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.</td></tr>
<tr><th>sl</th>
<tr><th>sl</th>
Line 28: Line 28:
<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> 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><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 <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)]].
<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</var> method ([[Insert (Stringlist function)]]).
</ul>
</ul>


Line 36: Line 36:
<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)
  %clist:insert(%in, 1)
else
else
%in = -%in
  %in = -%in
%clist:replace(%in, %clist:item(%in) +1 )
  %clist:replace(%in, %clist:item(%in) +1 )
end if
end if
</p>
</p>

Revision as of 00:17, 25 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

%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 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 the Insert method (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