Locate (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
m (camelCase) |
m (more consistent layout and better tagging) |
||
| Line 9: | Line 9: | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>% | <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> | <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> | <tr><th>sl</th> | ||
| Line 20: | Line 20: | ||
<td>A number that specifies the starting column of the range of columns in which the search string must be located. This is an optional argument, and it defaults to 1.</td></tr> | <td>A number that specifies the starting column of the range of columns in which the search string must be located. This is an optional argument, and it defaults to 1.</td></tr> | ||
<tr><th>endCol</th> | <tr><th>endCol</th> | ||
<td>A number that specifies the ending column of the range of columns in which the search string must be located. This is an optional argument, and it defaults to 6124. If <var class="term"> | <td>A number that specifies the ending column of the range of columns in which the search string must be located. This is an optional argument, and it defaults to 6124. If <var class="term">caseFlag<var> is a non-zero integer, the width of this column range is reduced to a maximum of 256.</td></tr> | ||
<tr><th>caseFlag</th> | <tr><th>caseFlag</th> | ||
<td>An indicator for case-insensitive comparisons. If this argument is a non-zero integer, the string comparisons use <var>stringlist</var> item data is translated to uppercase (so the search string should be passed as an uppercase value). This is an optional argument, and it defaults to zero. If it is 1, the width of the searched column range is reduced to a maximum of 256.</td></tr> | <td>An indicator for case-insensitive comparisons. If this argument is a non-zero integer, the string comparisons use <var>stringlist</var> item data is translated to uppercase (so the search string should be passed as an uppercase value). This is an optional argument, and it defaults to zero. If it is 1, the width of the searched column range is reduced to a maximum of 256.</td></tr> | ||
| Line 29: | Line 29: | ||
==Examples== | ==Examples== | ||
The following code locates a string in columns 31 through 40 of <var>stringlist</var> %list: | 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 class="code">%num = %list:locate('Eudaemonic', , 31, 40) | ||
Revision as of 02:46, 27 January 2011
Locate next Stringlist item containing string (Stringlist class)
This method locates a specified string in a stringlist.
The Locate method returns the item number of the stringlist item that contains the specified string, or it returns a 0 if no matching items are found.
Syntax
%itemNum = sl:Locate( 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. If this argument is not specified, searching begins at the first item in the 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. |
| startCol | A number that specifies the starting column of the range of columns in which the search string must be located. This is an optional argument, and it defaults to 1. |
| endCol | A number that specifies the ending column of the range of columns in which the search string must be located. This is an optional argument, and it defaults to 6124. If caseFlag is a non-zero integer, the width of this column range is reduced to a maximum of 256. |
| caseFlag | An indicator for case-insensitive comparisons. If this argument is a non-zero integer, the string comparisons use stringlist item data is translated to uppercase (so the search string should be passed as an uppercase value). This is an optional argument, and it defaults to zero. If it is 1, the width of the searched column range is reduced to a maximum of 256. |
Usage notes
- Locate returns a 0 if the indicated string is not found, and it cancels the request for all other errors.
- Although under Sirius Mods Version 6.6 and later, stringlist items can be longer than 6124 bytes, Locate will only look for matches in the first 6124 bytes of any stringlist item.
Examples
The following code locates a string in columns 31 through 40 of stringlist %list:
%num = %list:locate('Eudaemonic', , 31, 40)