FindImageItem and FindImageItemUp (Stringlist functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:Stringlist:FindImageItem subtitle}}
{{Template:Stringlist:FindImageItem and FindImageItemUp subtitle}}


{{Template:Stringlist:FindImageItemUp subtitle}}
Both these methods locate a <var>Stringlist</var> item that exactly matches the contents of an image item (or of a value converted to the image item format at the offset and length of the image item). The difference between <var>FindImageItem</var> and <var>FindImageItemUp</var> is the direction of the search: <var>FindImageItem</var> searches from the starting point in ascending item number order, while <var>FindImageItemUp</var> searches in descending item number order.


These methods locate a Stringlist item that exactly matches the contents of an image item (or of a value converted to the image item format at the offset and length of the image item). The difference between FindImageItem and FindImageItemUp is the direction of the search: FindImageItem searches from the starting point in ascending item number order, while FindImageItemUp searches in descending item number order.
Both <var>FindImageItem</var> and <var>FindImageItemUp</var> accept four arguments, and they return the item number of the <var>Stringlist</var> item that matches the image item, or they return a 0 indicating that the item was not found. All other errors cause the request to be canceled.
 
The FindImageItemUp method is available as of ''[[Sirius Mods]]'' version 7.1. The FindImageItem and FindImageItemUp methods accept four arguments, and they return the item number of the Stringlist item that matches the image item, or they return a 0 indicating that the item was not found. All other errors cause the request to be canceled.


==Syntax==
==Syntax==
{{Template:Stringlist:FindImageItem syntax}}
{{Template:Stringlist:FindImageItem syntax}}
{{Template:Stringlist:FindImageItemUp syntax}}
{{Template:Stringlist:FindImageItemUp syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%number </th>
<tr><th>%number </th>
<td>A numeric variable that is set to the number of the first item in the Stringlist that matches the search criterion, or it is set to 0 if no Stringlist items matched the search criterion. </td></tr>
<td>A numeric variable that is set to the number of the first item in the <var>Stringlist</var> that matches the search criterion, or it is set to 0 if no <var>Stringlist</var> items matched the search criterion. </td></tr>
<tr><th>sl </th>
 
<td>A Stringlist object. </td></tr>
<tr><th>sl</th>
<td>A <var>Stringlist</var> object. </td></tr>
 
<tr><th>imageItem </th>
<tr><th>imageItem </th>
<td>The image item to be matched. This is a required argument. </td></tr>
<td>The image item to be matched. This is a required argument.</td></tr>
<tr><th>searchvalue </th>
 
<td>The value to be found. This is an optional argument. When this argument is not specified, the current contents of the image item specified by '''item''' is used as the match value. </td></tr>
<tr><th>searchValue </th>
<tr><th>startitem </th>
<td>The value to be found. This is an optional argument. When this argument is not specified, the current contents of the <var class="term">imageItem</var> is used as the match value. </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 Stringlist for FindImageItem, and at the last item for FindImageItemUp </td></tr>
 
<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>FindImageItem</var>, and at the last item for <var>FindImageItemUp</var> </td></tr>
 
<tr><th>operator </th>
<tr><th>operator </th>
<td>A string comparison operator that indicates the required relationship between the match value and the item in the '''%sl''' Stringlist. Valid comparison operators are <tt>.EQ</tt>, <tt>.NE</tt>, <tt>.LE</tt>,<tt>.LT</tt>, <tt>.GE</tt>, and <tt>.GT</tt>. If this argument is not specified or null, an equality test (<tt>.EQ</tt>) is done on all Stringlist items.</td></tr>
<td>A string comparison operator that indicates the required relationship between the match value and the item in the <var class="term">sl</var> <var>Stringlist</var>. Valid comparison operators are <code>'EQ'</code>, <code>'NE'</code>, <code>'LE'</code>, <code>'LT'</code>, <code>'GE'</code>, and <code>'GT'</code>. If this argument is not specified or null, an equality test (<code>'EQ'</code>) is done on all <var>Stringlist</var> items.</td></tr>
</table>
</table>
==Usage Notes==
<ul><li><var>FindImageItemUp</var> is available as of <var class="product">Sirius Mods</var> version 7.1. </ul>


==Examples==
==Examples==
FindImageItem and FindImageItemUp are especially useful for Stringlists whose contents map to an image. For example, in the following code fragment<tt>.%num</tt> is set to the number of the list item that is associated with the product with a code of <tt>.983</tt>:
<ol><li><var>FindImageItem</var> and <var>FindImageItemUp</var> are especially useful for <var>Stringlists</var> whose contents map to an image. For example, in the following code fragment <code>%num</code> is set to the number of the list item that is associated with the product with a code of <code>983</code>:


<pre>
<p class="code">image product
image product
code is binary len 2
code is binary len 2
desc is string len 30
desc is string len 30
end image
end image


. . . .
  ...
%list = new('PRODUCT')
%list = new('PRODUCT')
fr products
fr products
%product:code = code
  %product:code = code
%product:desc = desc
  %product:desc = desc
%rc = %list:addImage
  %rc = %list:addImage
end for
end for
...
  ...
%product:code = 983
%product:code = 983
%num = findImageItem(%list, %product:code)
%num = %list:findImageItem(%product:code)
</pre>
</p>


If a value is specified in addition to the image item, processing is performed as if the value were assigned to the image item and then the image item restored to its original value. Any datatype conversions required between the value and the image item are performed before the search is performed.  
<li>If a <var class="term">searchValue</var> is specified in addition to the <var class="term">imageItem</var>, processing is performed as if the <var class="term">searchValue</var> were assigned to the <var class="term">imageItem</var> and then the <var class="term">imageItem</var> is restored to its original value upon completion. Any datatype conversions required between the <var class="term">searchValue</var> and the <var class="term">imageItem</var> are performed before the search is performed.  


That is, this method invocation
That is, this method invocation


<pre>
<p class="code">%num = %list:findImageItem(%product:code, 422)
%num = %list:findImageItem(%product:code, 422)
</p>
</pre>


is identical to this:
is identical to this:


<pre>
<p class="code">%temp = %product:code
%temp = %product:code
%product:code = 422
%product:code = 422
%num = %list:findImageItem(%product:code)
%num = %list:findImageItem(%product:code)
%product:code = %temp
%product:code = %temp
</pre>
</p>
 
For inequality comparisons, the appropriate image-item datatype-specific comparison is performed.
For example, this method invocation would start from the last %list item and would match an item with a product code of <tt>.-2</tt>, <tt>.-1</tt>, or any number greater than or equal to zero, but it would not match one with a product code of <tt>.-3</tt> or less:


<pre>
<li>For inequality comparisons, the appropriate image-item datatype-specific comparison is performed.
%n = %list:findImageItemUp(%product:code, -2, , 'GE')
For example, this method invocation would start from the last <code>%list</code> item and would match an item with a product code of <code>-2</code>, <code>-1</code>, or any number greater than or equal to zero, but it would not match one with a product code of <code>-3</code> or less:
</pre>


<p class="code">%n = %list:findImageItemUp(%product:code, -2, , 'GE')
</p></ol>


[[Category:Stringlist methods|FindImageItem/FindImageItemUp function]]
==See also==
{{Template:Stringlist:FindImageItem and FindImageItemUp footer}}

Latest revision as of 15:27, 31 October 2012

Find next/previous matching image item in Stringlist (Stringlist class)


Both these methods locate a Stringlist item that exactly matches the contents of an image item (or of a value converted to the image item format at the offset and length of the image item). The difference between FindImageItem and FindImageItemUp is the direction of the search: FindImageItem searches from the starting point in ascending item number order, while FindImageItemUp searches in descending item number order.

Both FindImageItem and FindImageItemUp accept four arguments, and they return the item number of the Stringlist item that matches the image item, or they return a 0 indicating that the item was not found. All other errors cause the request to be canceled.

Syntax

%number = sl:FindImageItem( imageItem, [searchValue], [startItem], [operator])

%number = sl:FindImageItemUp( imageItem, [searchValue], [startItem], - [operator])

Syntax terms

%number A numeric variable that is set to the number of the first item in the Stringlist that matches the search criterion, or it is set to 0 if no Stringlist items matched the search criterion.
sl A Stringlist object.
imageItem The image item to be matched. This is a required argument.
searchValue The value to be found. This is an optional argument. When this argument is not specified, the current contents of the imageItem is used as the match value.
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 FindImageItem, and at the last item for FindImageItemUp
operator A string comparison operator that indicates the required relationship between the match value and the item in the sl Stringlist. Valid comparison operators are 'EQ', 'NE', 'LE', 'LT', 'GE', and 'GT'. If this argument is not specified or null, an equality test ('EQ') is done on all Stringlist items.

Usage Notes

  • FindImageItemUp is available as of Sirius Mods version 7.1.

Examples

  1. FindImageItem and FindImageItemUp are especially useful for Stringlists whose contents map to an image. For example, in the following code fragment %num is set to the number of the list item that is associated with the product with a code of 983:

    image product code is binary len 2 desc is string len 30 end image ... %list = new('PRODUCT') fr products %product:code = code %product:desc = desc %rc = %list:addImage end for ... %product:code = 983 %num = %list:findImageItem(%product:code)

  2. If a searchValue is specified in addition to the imageItem, processing is performed as if the searchValue were assigned to the imageItem and then the imageItem is restored to its original value upon completion. Any datatype conversions required between the searchValue and the imageItem are performed before the search is performed. That is, this method invocation

    %num = %list:findImageItem(%product:code, 422)

    is identical to this:

    %temp = %product:code %product:code = 422 %num = %list:findImageItem(%product:code) %product:code = %temp

  3. For inequality comparisons, the appropriate image-item datatype-specific comparison is performed. For example, this method invocation would start from the last %list item and would match an item with a product code of -2, -1, or any number greater than or equal to zero, but it would not match one with a product code of -3 or less:

    %n = %list:findImageItemUp(%product:code, -2, , 'GE')

See also