$List Add Unique Ordered: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
(Automatically generated page update)
 
(33 intermediate revisions by 2 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Conditionally add an item to an ordered $list</span>
<span class="pageSubtitle">Conditionally add an item to an ordered $list</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the <var>$List_Add_Unique_Ordered</var> function is the [[AddUniqueOrdered (Stringlist function)]].</p>
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Add_Unique_Ordered function is the [[AddUniqueOrdered (Stringlist function)]].</p>


This function adds an item to a (presumably) ordered $list if an identical item isn't already there, inserting the item at the proper position to maintain the $lists order.  
This function adds an item to a (presumably) ordered $list if an identical item isn't already there, inserting the item at the proper position to maintain the $lists order.  
Line 17: Line 17:
The second argument is the string to add to the $list. This is a required argument.  
The second argument is the string to add to the $list. This is a required argument.  


<var>$List_Add_Unique_Ordered</var> is a callable $function (see [[Calling Sirius Mods $functions]]).
<var>$List_Add_Unique_Ordered</var> is a [[Calling Sirius Mods $functions|callable]] $function.


==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> [%RC =] $List_Add_Unique_Ordered(list, string)
<p class="syntax">[%RC =] $List_Add_Unique_Ordered(list, string)
<section end="syntax" /></p>
<p class="caption">$List_Add_Unique_Ordered Function
</p>
</p>
<p class="caption">%RC is the item number of the added string, or it is the negative matching item number.</p>
<p>
</p>
<p>%RC is the item number of the added string, or it is the negative matching item number.</p>


All errors in <var>$List_Add_Unique_Ordered</var> result in request cancellation.  
All errors in <var>$List_Add_Unique_Ordered</var> result in request cancellation.  
Line 30: Line 30:
<var>$List_Add_Unique_Ordered</var> only adds the indicated string to the $list if there isn't already an identical $list item on the $list. If the there are no matching items, the new item is inserted so that the $list is in EBCDIC order. <var>$List_Add_Unique_Ordered</var> assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate a match or the correct insertion point. <var>$List_Add_Unique_Ordered</var> does not validate that the $list is in order and, it it isn't, the insertion point or detection of a match is unpredictable.  
<var>$List_Add_Unique_Ordered</var> only adds the indicated string to the $list if there isn't already an identical $list item on the $list. If the there are no matching items, the new item is inserted so that the $list is in EBCDIC order. <var>$List_Add_Unique_Ordered</var> assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate a match or the correct insertion point. <var>$List_Add_Unique_Ordered</var> does not validate that the $list is in order and, it it isn't, the insertion point or detection of a match is unpredictable.  


<var>$List_Add_Unique_Ordered</var> returns the either 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 $list that contains say a count of the number of times a given value occurred, that is was passed as a string to $List_Add_Unique_Ordered.
<var>$List_Add_Unique_Ordered</var> returns the either 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 $list that contains say a count of the number of times a given value occurred, that is was passed as a string to <var>$List_Add_Unique_Ordered</var>.
The following illustrates such an approach:
The following illustrates such an approach:


Line 46: Line 46:
This $function is new in Version 6.3.<p>
This $function is new in Version 6.3.<p>


==Products authorizing {{PAGENAMEE}}==
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[Sirius functions]]</li>
<li>[[List of $functions|Sirius functions]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Janus Open Client]]</li>
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>
<li>[[Janus Open Server]]</li>
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Japanese functions]]</li>
<li>Japanese functions</li>
<li>[[Sir2000 Field Migration Facility]]</li>
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li>
</ul>  
</ul>  
</p>
</p>
<p class="caption">Products authorizing $List_Add_Unique_Ordered
<p>
</p>
</p>




[[Category:$Functions|$List_Add_Unique_Ordered]]
[[Category:$Functions|$List_Add_Unique_Ordered]]

Latest revision as of 22:51, 20 September 2018

Conditionally add an item to an ordered $list

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Add_Unique_Ordered function is the AddUniqueOrdered (Stringlist function).

This function adds an item to a (presumably) ordered $list if an identical item isn't already there, inserting the item at the proper position to maintain the $lists order.

$List_Add_Unique_Ordered accepts two arguments 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.

The first argument is the $list identifier of the $list to which the string is to be added. This is a required argument.

The second argument is the string to add to the $list. This is a required argument.

$List_Add_Unique_Ordered is a callable $function.

Syntax

[%RC =] $List_Add_Unique_Ordered(list, string)

%RC is the item number of the added string, or it is the negative matching item number.

All errors in $List_Add_Unique_Ordered result in request cancellation.

$List_Add_Unique_Ordered only adds the indicated string to the $list if there isn't already an identical $list item on the $list. If the there are no matching items, the new item is inserted so that the $list is in EBCDIC order. $List_Add_Unique_Ordered assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate a match or the correct insertion point. $List_Add_Unique_Ordered does not validate that the $list is in order and, it it isn't, the insertion point or detection of a match is unpredictable.

$List_Add_Unique_Ordered returns the either 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 $list that contains say a count of the number of times a given value occurred, that is was passed as a string to $List_Add_Unique_Ordered. The following illustrates such an approach:

%IN = $List_Add_Unique_Ordered(%OLIST, %DATA) IF %IN GT 0 THEN %RC = $ListIns(%CLIST, %IN, 1) ELSE %IN = -%IN %RC = $ListRep(%CLIST, %IN, $ListInf(%CLIST, %IN) +1 ) END IF

Because $List_Add_Unique_Ordered will insert items into the middle of a $list it will be susceptible to the same page-splitting, sparse $list leaf page issues as $ListIns.

This $function is new in Version 6.3.

Products authorizing $List_Add_Unique_Ordered

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=$List_Add_Unique_Ordered&oldid=116847"