Find and FindUp (Stringlist functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(2 intermediate revisions by one other user not shown)
Line 16: Line 16:
<td>The <var class="term">string</var> to be matched. This is a required argument. </td></tr>
<td>The <var class="term">string</var> to be matched. This is a required argument. </td></tr>
<tr><th>startItem </th>
<tr><th>startItem </th>
<td>A number that indicates the item number at which the search is to begin. If this argument is not specified, searching begins at the first item in the <var>Stringlist</var> for <var>Find</var>, and at the last item for <var>FindUp</var>. Not specifying the starting item number is subtly different from specifying a starting item number of 1 -- the latter is an error if the <var>Stringlist</var> is empty, while the former simply returns a 0.</td></tr>
<td>A number that indicates the item number at which the search is to begin. If this argument is not specified, searching begins at the first item in the <var>Stringlist</var> for <var>Find</var>, and at the last item for <var>FindUp</var>. Not specifying the starting item number is subtly different from specifying a starting item number of 1 the latter is an error if the <var>Stringlist</var> is empty, while the former simply returns a 0.</td></tr>
</table>
</table>


Line 22: Line 22:
<ul>
<ul>
<li>A return code of 0 from <var>Find</var> or <var>FindUp</var> indicates that the string was not found. All other errors result in request cancellation.
<li>A return code of 0 from <var>Find</var> or <var>FindUp</var> indicates that the string was not found. All other errors result in request cancellation.
<li>The difference between <var>Find</var> / <var>FindUp</var> and <var>[[Locate and LocateUp (Stringlist functions)|Locate]]</var> / <var>[[Locate and LocateUp (Stringlist functions)|LocateUp]]</var> is that when <var>Find</var> or <var>FindUp</var> are used, a <var>Stringlist</var> item must exactly match the search <var class="term">string</var> rather than simply containing the search <var class="term">string</var>. Moreover, <var>Find</var> and <var>FindUp</var> do not allow specification of a range of columns (or positions) that are to be searched.<li><var>FindUp</var> is available in <var class="product">[[Sirius Mods]]</var> Version 6.9 and later.
<li>The difference between <var>Find</var> / <var>FindUp</var> and <var>[[Locate and LocateUp (Stringlist functions)|Locate]]</var> / <var>[[Locate and LocateUp (Stringlist functions)|LocateUp]]</var> is that when <var>Find</var> or <var>FindUp</var> are used, a <var>Stringlist</var> item must exactly match the search <var class="term">string</var> rather than simply containing the search <var class="term">string</var>. Moreover, <var>Find</var> and <var>FindUp</var> do not allow specification of a range of columns (or positions) that are to be searched.
<li> When the search parameter is longer than 255 bytes, the <var>Find</var> function treats it as a String and not a longstring.
<li><var>FindUp</var> is available in <var class="product">[[Sirius Mods]]</var> Version 6.9 and later.
</ul>
</ul>


==See also==
==See also==
{{Template:Stringlist:Find and FindUp footer}}
{{Template:Stringlist:Find and FindUp footer}}

Latest revision as of 18:11, 11 February 2022

Find next/previous Stringlist item that exactly matches a string (Stringlist class)

Both these methods locate a Stringlist item that exactly matches a specified string. The difference between Find and FindUp is the direction of the search: Find searches from the starting point in ascending item number order, while FindUp searches in descending item number order.

Both Find and FindUp return the item number of the Stringlist item that matches the input string, or they return an error code.

Syntax

%number = sl:Find( string, [startItem])

%number = sl:FindUp( string, [startItem])

Syntax terms

%number A numeric variable that is set to the number of the first item in the Stringlist that matches the search string, or it is set to 0 if the search string is not found.
sl A Stringlist object.
string The string to be matched. This is a required argument.
startItem A number that indicates the item number at which the search is to begin. If this argument is not specified, searching begins at the first item in the Stringlist for Find, and at the last item for FindUp. Not specifying the starting item number is subtly different from specifying a starting item number of 1 — the latter is an error if the Stringlist is empty, while the former simply returns a 0.

Usage notes

  • A return code of 0 from Find or FindUp indicates that the string was not found. All other errors result in request cancellation.
  • The difference between Find / FindUp and Locate / LocateUp is that when Find or FindUp are used, a Stringlist item must exactly match the search string rather than simply containing the search string. Moreover, Find and FindUp do not allow specification of a range of columns (or positions) that are to be searched.
  • When the search parameter is longer than 255 bytes, the Find function treats it as a String and not a longstring.
  • FindUp is available in Sirius Mods Version 6.9 and later.

See also