$List Add Unique: Difference between revisions

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


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Add_Unique function is the [[AddUnique (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 function is <var>[[AddUnique (Stringlist function)|AddUnique]]</var>.</p>


This function adds an item to a $list if an identical item isn't already there, adding the item to the end of the $list.  
This function adds an item to a $list if an identical item isn't already there, adding the item to the end of the $list.  


<var>$List_Add_Unique</var> accepts two arguments and returns one of the following:
<var>$List_Add_Unique</var> is a [[Calling Sirius Mods $functions|callable]] $function.


<ul>
==Syntax==
<li>The item number of the added string.
<p class="syntax">[%RC =] $List_Add_Unique(list, string)
<li>The negative of the item number that exactly matches the string being added.
</p>
</ul>


The first argument is the $list identifier of the $list to which the string is to be added. This is a required argument.
===Syntax terms===
<table class="syntaxTable">
<tr><th>%rc</th>
<td>A numeric variable that is the item number of the added string, or it is the negative of the item number that exactly matches the string being added.</td></tr>


The second argument is the string to add to the $list. This is a required argument.  
<tr><th>list</th>
<td>The $list identifier of the $list to which the string is to be added. This is a required argument. </td></tr>


<var>$List_Add_Unique</var> is a [[Calling Sirius Mods $functions|callable]] $function.
<tr><th>string</th>
<td>The string to add to the $list. This is a required argument. </td></tr>
</table>


==Syntax==
==Usage notes==
<p class="syntax"><section begin="syntax" /> [%RC =] $List_Add_Unique(list, string)
<ul>
<section end="syntax" /></p>
<li>All errors in <var>$List_Add_Unique</var> result in request cancellation.  
<p class="caption">$List_Add_Unique Function
</p>
<p class="caption">%RC is the item number of the added string or the negative matching item number.</p>
 
All errors in <var>$List_Add_Unique</var> result in request cancellation.  


<var>$List_Add_Unique</var> always adds the indicated string to the end of the $list but does not add it if there's already an identical $list item on the $list. <var>$List_Add_Unique</var> does not assume any order for the $list so sequentially scans the entire $list for matches to the string being added. Because of this, it will generally be more expensive to use than <var>$List_Add_Unique_Ordered</var> for very large $lists though this latter function might not be usable in all cases -- say, if the target $list starts out unordered.  
<li><var>$List_Add_Unique</var> always adds the indicated string to the end of the $list but does not add it if there's already an identical $list item on the $list. <var>$List_Add_Unique</var> does not assume any order for the $list so sequentially scans the entire $list for matches to the string being added. Because of this, it will generally be more expensive to use than <var>$List_Add_Unique_Ordered</var> for very large $lists though this latter function might not be usable in all cases &#x2014; say, if the target $list starts out unordered.  


<var>$List_Add_Unique</var> returns the either the item number added 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</var>.
<li><var>$List_Add_Unique</var> returns the either the item number added 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</var>.
The following illustrates such an approach:
The following illustrates such an approach:


<p class="code"> %IN = $List_Add_Unique(%OLIST, %DATA)
<p class="code">%IN = $List_Add_Unique(%OLIST, %DATA)
IF %IN GT 0 THEN
IF %IN GT 0 THEN
    %RC = $ListIns(%CLIST, %IN, 1)
  %RC = $ListIns(%CLIST, %IN, 1)
ELSE
ELSE
    %IN = -%IN
  %IN = -%IN
    %RC = $ListRep(%CLIST, %IN, $ListInf(%CLIST, %IN) +1 )
  %RC = $ListRep(%CLIST, %IN, $ListInf(%CLIST, %IN) +1 )
END IF
END IF
</p>
</p>
</ul>


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 class="caption">Products authorizing $List_Add_Unique
</p>


[[Category:$Functions|$List_Add_Unique]]
[[Category:$Functions|$List_Add_Unique]]

Latest revision as of 22:51, 20 September 2018

Conditionally add an item to a $list

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Add_Unique function is AddUnique.

This function adds an item to a $list if an identical item isn't already there, adding the item to the end of the $list.

$List_Add_Unique is a callable $function.

Syntax

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

Syntax terms

%rc A numeric variable that is the item number of the added string, or it is the negative of the item number that exactly matches the string being added.
list The $list identifier of the $list to which the string is to be added. This is a required argument.
string The string to add to the $list. This is a required argument.

Usage notes

  • All errors in $List_Add_Unique result in request cancellation.
  • $List_Add_Unique always adds the indicated string to the end of the $list but does not add it if there's already an identical $list item on the $list. $List_Add_Unique does not assume any order for the $list so sequentially scans the entire $list for matches to the string being added. Because of this, it will generally be more expensive to use than $List_Add_Unique_Ordered for very large $lists though this latter function might not be usable in all cases — say, if the target $list starts out unordered.
  • $List_Add_Unique returns the either the item number added 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. The following illustrates such an approach:

    %IN = $List_Add_Unique(%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


Products authorizing $List_Add_Unique