AddUniqueOrdered (Stringlist function)

Conditionally add an item to an ordered Stringlist

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.

AddUniqueOrdered Syntax

[%rc =] %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