AddUnique (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
|||
| (17 intermediate revisions by 6 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Stringlist:AddUnique subtitle}} | {{Template:Stringlist:AddUnique subtitle}} | ||
This callable method adds an item to a <var>Stringlist</var> if an identical item is not already present. It adds the item to the end of the <var>Stringlist</var>. <var>AddUnique</var> accepts one argument and returns one of the following: | This [[Notation conventions for methods#Callable functions|callable]] method adds an item to a <var>Stringlist</var> if an identical item is not already present. It adds the item to the end of the <var>Stringlist</var>. <var>AddUnique</var> accepts one argument and returns one of the following: | ||
<ul> | <ul> | ||
| Line 13: | Line 13: | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%number</th> | <tr><th>%number</th> | ||
<td>A numeric variable to contain the item number of the added <var class="term">string</var | <td>A numeric variable to contain the item number of the added <var class="term">string</var>, or the negative item number of an item that already contains the string.</td></tr> | ||
<tr><th>sl</th> | <tr><th>sl</th> | ||
<td>A <var>Stringlist</var> object.</td></tr> | <td>A <var>Stringlist</var> object.</td></tr> | ||
| Line 24: | Line 24: | ||
<li>All errors in <var>AddUnique</var> result in request cancellation. | <li>All errors in <var>AddUnique</var> result in request cancellation. | ||
<li><var>AddUnique</var> always adds the indicated string to the end of the <var>Stringlist</var>, but it does not add it if there is already an identical <var>Stringlist</var> item on the <var>Stringlist</var>. | <li><var>AddUnique</var> always adds the indicated string to the end of the <var>Stringlist</var>, but it does not add it if there is already an identical <var>Stringlist</var> item on the <var>Stringlist</var>. | ||
<li><var>AddUnique</var> does not assume any order for the <var>Stringlist</var>, so it sequentially scans the entire <var>Stringlist</var> for matches to the string being added. Because of this, it is generally more expensive to use than <var> | <li><var>AddUnique</var> does not assume any order for the <var>Stringlist</var>, so it sequentially scans the entire <var>Stringlist</var> for matches to the string being added. Because of this, it is generally more expensive to use than <var>[[AddUniqueOrdered (Stringlist_function)|AddUniqueOrdered]]</var> for very large <var>Stringlists</var>. <var>[[AddUniqueOrdered (Stringlist_function)|AddUniqueOrdered]]</var>, however, may not be usable in all cases — for example, if the target <var>Stringlist</var> starts out unordered. | ||
</ul> | </ul> | ||
==Examples== | ==Examples== | ||
<var>AddUnique</var> returns 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 <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>AddUnique</var>. The following example illustrates such an approach: | <var>AddUnique</var> returns 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 <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>AddUnique</var>. The following example illustrates such an approach: | ||
<p class="code">%in = %olist:addUnique(%data) | <p class="code">%in = %olist:addUnique(%data) | ||
if %in gt 0 then | if %in gt 0 then | ||
| Line 39: | Line 38: | ||
</p> | </p> | ||
==See also== | |||
{{Template:Stringlist:AddUnique footer}} | |||
Latest revision as of 10:18, 14 June 2018
Conditionally add an item to a Stringlist (Stringlist class)
This callable method adds an item to a Stringlist if an identical item is not already present. It adds the item to the end of the Stringlist. AddUnique accepts one argument and returns one of the following:
- The item number of the added string.
- The negative of the item number that exactly matches the string being added.
Syntax
[%number =] sl:AddUnique( 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 AddUnique result in request cancellation.
- AddUnique always adds the indicated string to the end of the Stringlist, but it does not add it if there is already an identical Stringlist item on the Stringlist.
- AddUnique does not assume any order for the Stringlist, so it sequentially scans the entire Stringlist for matches to the string being added. Because of this, it is generally more expensive to use than AddUniqueOrdered for very large Stringlists. AddUniqueOrdered, however, may not be usable in all cases — for example, if the target Stringlist starts out unordered.
Examples
AddUnique returns 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 Stringlist that contains, say, a count of the number of times a given value occurred, that is, was passed as a string to AddUnique. The following example illustrates such an approach:
%in = %olist:addUnique(%data) if %in gt 0 then %clist:insert(%in, 1) else %in = -%in %clist:replace(%in, %clist:item(%in) + 1) end if