Locate and LocateUp (Stringlist functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (Created page with "page under construction")
 
 
(25 intermediate revisions by 5 users not shown)
Line 1: Line 1:
page under construction
{{Template:Stringlist:Locate and LocateUp subtitle}}
Both these functions locate a specified string in a <var>Stringlist</var>.
The difference between <var>Locate</var> and <var>LocateUp</var> is the direction of the search: <var>Locate</var>
searches from the starting point in ascending item number order, while <var>LocateUp</var>
searches from the starting point in descending item number order.
Both <var>Locate</var> and <var>LocateUp</var> return the item number of the <var>Stringlist</var> item
that matches the input <var class="term">string</var>, or they return 0 to indicate no matching items
were found.
==Syntax==
{{Template:Stringlist:Locate syntax}}
{{Template:Stringlist:LocateUp syntax}}
 
===Syntax terms===
<table class="syntaxTable">
<tr><th>%itemNum</th>
<td>A numeric variable which will be set to the item number of the first item in the <var class="term">sl</var> <var>Stringlist</var> that contains the search target string, or it is set to a 0 if no items match the search criterion.</td></tr>
 
<tr><th>sl</th>
<td>A <var>Stringlist</var> object.</td></tr>
<tr><th>string</th>
<td>The target string to be located. This is a required argument, and it must be no longer than 255 bytes.</td></tr>
 
<tr><th><var>Start</var></th>
<td>A number that indicates the item number at which the search is to begin. This must be between 1 and the number of items in the <var>Stringlist</var>, inclusive. If this argument is not specified:
<ul>
<li>For <var>Locate</var>, searching begins at the first item in the <var class="term">sl</var> <var>Stringlist</var>.  Not specifying the starting item number is subtly different from specifying a starting item number of 1 &mdash; specifying 1 is an error if the <var>stringlist</var> is empty, while no specification simply returns a 0.
 
<li>For <var>LocateUp</var>, searching begins at the last item in the <var class="term">sl</var> <var>Stringlist</var>.
</ul>
Under <var class="product">Sirius Mods</var> 8.1 and later, this is a [[Notation conventions for methods#Named parameters|name allowed]] parameter.</td></tr>
 
<tr><th><var>StartColumn</var></th>
<td>A number that specifies the starting column of the range of columns within which the target <var class="term">string</var> is searched for. This is an optional argument, and it defaults to 1.<br/>Under <var class="product">Sirius Mods</var> 8.1 and later, this is a name allowed parameter.</td></tr>
 
<tr><th><var>EndColumn</var></th>
<td>A number that specifies the ending column of the range of columns within which the target <var class="term">string</var> is searched for. This is an optional argument, and it defaults to 6124. If either the <var>CaseIndependent</var> or <var>ArbitraryQuote</var> argument has a non-zero numeric value, the width of the searched column range is reduced to a maximum of 256.<br/>Under <var class="product">Sirius Mods</var> 8.1 and later, this is a name allowed parameter.</td></tr>
 
<tr><th><var>CaseIndependent</var></th>
<td>An indicator for case-insensitive comparisons. If this argument is a non-zero integer, the string comparisons use <var class="term">sl</var> <var>Stringlist</var> item data translated to uppercase (so the search target <var class="term">string</var> should be passed as an uppercase value). This is an optional argument, and defaults to 0. If set to a non-zero value, the width of the searched column range is reduced to a maximum of 256.<br/>Under <var class="product">Sirius Mods</var> 8.1 and later, this is a name allowed parameter.</td></tr>
 
<tr><th><var>ArbitraryQuote</var></th>
<td>An indicator for abitrary quote comparisons. If this argument is a non-zero integer, single (<tt>'</tt>) and double(<tt>"</tt>) quotes are considered matches for each other in the string comparisons. This is an optional argument, and defaults to 0. If set to a non-zero value, the width of the searched column range is reduced to a maximum of 256. This can be useful when searching through procedures that contain code where single and double quotes can be used interchangeably to enclose string literals. Such code includes <var class="product">SOUL</var>, Javascript, and XML (including XSLT).
<p>
This parameter, available in <var class="product">Sirius Mods</var> 8.1 and later, is a name allowed parameter.</p></td></tr>
</table>
 
==Usage notes==
<ul>
<li><var>Locate</var> and <var>LocateUp</var> return a 0 if the indicated string is not found, and cancel the request for all other errors.
 
<li>While <var>Stringlist</var> items can be longer than 6124 bytes long, these function will only look for matches in the first 6124 bytes of any <var>Stringlist</var> item.
 
<li>When converting old code from <var>[[$ListLoc]]</var> and <var>[[$ListLup]]</var>, note: '''the parameter order of the Locate and LocateUp methods is not the same as the corresponding $function'''.  The $functions have ''starting position'' followed by ''search string''.  The <var>Locate</var> and <var>LocateUp</var> methods have ''search string'' followed by ''starting position'', making them more consistent with other <var>Stringlist</var> methods.
</ul>
 
==Examples==
<ol>
<li>The following code locates a string in columns 31 through 40 of <var>stringlist</var> <code>%list</code>:
<p class="code">%num = %list:locate('Eudaemonic', , 31, 40)
</p></li>
 
<li>The following code locates a string anywhere in a <var>Stringlist</var> <code>%list</code> item, searching backwards starting at item 100.
<p class="code"><nowiki>%num = %list:locateUp('Vietnamerica', 100)
</nowiki></p></li>
</ol>
==See also==
<ul>
<li>The <var>[[Find and FindUp (Stringlist functions)|Find]]</var> and <var>[[Find and FindUp (Stringlist functions)|FindUp]]</var> functions also search for a target string in a <var>Stringlist</var>, but they find an item only if it is an exact match.</li>
 
<li>The <var>[[RegexLocate and RegexLocateUp (Stringlist functions)|RegexLocate]]</var> and <var>[[RegexLocate and RegexLocateUp (Stringlist functions)|RegexLocateUp]]</var> functions also search for a matching item in a <var>Stringlist</var>, but they find an item that matches a specifed regular expression.</li>
</ul>
 
{{Template:Stringlist:LocateUp footer}}

Latest revision as of 02:36, 18 March 2015

Locate next/previous Stringlist item that contains a string (Stringlist class)


Both these functions locate a specified string in a Stringlist. The difference between Locate and LocateUp is the direction of the search: Locate searches from the starting point in ascending item number order, while LocateUp searches from the starting point in descending item number order.

Both Locate and LocateUp return the item number of the Stringlist item that matches the input string, or they return 0 to indicate no matching items were found.

Syntax

%itemNum = sl:Locate( string, [[Start=] number], [[StartColumn=] number], - [[EndColumn=] number], [[CaseIndependent=] number], - [[ArbitraryQuote=] number])

%itemNum = sl:LocateUp( string, [[Start=] number], [[StartColumn=] number], - [[EndColumn=] number], [[CaseIndependent=] number], - [[ArbitraryQuote=] number])

Syntax terms

%itemNum A numeric variable which will be set to the item number of the first item in the sl Stringlist that contains the search target string, or it is set to a 0 if no items match the search criterion.
sl A Stringlist object.
string The target string to be located. This is a required argument, and it must be no longer than 255 bytes.
Start A number that indicates the item number at which the search is to begin. This must be between 1 and the number of items in the Stringlist, inclusive. If this argument is not specified:
  • For Locate, searching begins at the first item in the sl Stringlist. Not specifying the starting item number is subtly different from specifying a starting item number of 1 — specifying 1 is an error if the stringlist is empty, while no specification simply returns a 0.
  • For LocateUp, searching begins at the last item in the sl Stringlist.
Under Sirius Mods 8.1 and later, this is a name allowed parameter.
StartColumn A number that specifies the starting column of the range of columns within which the target string is searched for. This is an optional argument, and it defaults to 1.
Under Sirius Mods 8.1 and later, this is a name allowed parameter.
EndColumn A number that specifies the ending column of the range of columns within which the target string is searched for. This is an optional argument, and it defaults to 6124. If either the CaseIndependent or ArbitraryQuote argument has a non-zero numeric value, the width of the searched column range is reduced to a maximum of 256.
Under Sirius Mods 8.1 and later, this is a name allowed parameter.
CaseIndependent An indicator for case-insensitive comparisons. If this argument is a non-zero integer, the string comparisons use sl Stringlist item data translated to uppercase (so the search target string should be passed as an uppercase value). This is an optional argument, and defaults to 0. If set to a non-zero value, the width of the searched column range is reduced to a maximum of 256.
Under Sirius Mods 8.1 and later, this is a name allowed parameter.
ArbitraryQuote An indicator for abitrary quote comparisons. If this argument is a non-zero integer, single (') and double(") quotes are considered matches for each other in the string comparisons. This is an optional argument, and defaults to 0. If set to a non-zero value, the width of the searched column range is reduced to a maximum of 256. This can be useful when searching through procedures that contain code where single and double quotes can be used interchangeably to enclose string literals. Such code includes SOUL, Javascript, and XML (including XSLT).

This parameter, available in Sirius Mods 8.1 and later, is a name allowed parameter.

Usage notes

  • Locate and LocateUp return a 0 if the indicated string is not found, and cancel the request for all other errors.
  • While Stringlist items can be longer than 6124 bytes long, these function will only look for matches in the first 6124 bytes of any Stringlist item.
  • When converting old code from $ListLoc and $ListLup, note: the parameter order of the Locate and LocateUp methods is not the same as the corresponding $function. The $functions have starting position followed by search string. The Locate and LocateUp methods have search string followed by starting position, making them more consistent with other Stringlist methods.

Examples

  1. The following code locates a string in columns 31 through 40 of stringlist %list:

    %num = %list:locate('Eudaemonic', , 31, 40)

  2. The following code locates a string anywhere in a Stringlist %list item, searching backwards starting at item 100.

    %num = %list:locateUp('Vietnamerica', 100)

See also

  • The Find and FindUp functions also search for a target string in a Stringlist, but they find an item only if it is an exact match.
  • The RegexLocate and RegexLocateUp functions also search for a matching item in a Stringlist, but they find an item that matches a specifed regular expression.