FindImageItem and FindImageItemUp (Stringlist functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (syntax digram, tags)
Line 3: Line 3:
{{Template:Stringlist:FindImageItemUp subtitle}}
{{Template:Stringlist:FindImageItemUp subtitle}}


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 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 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.  


The FindImageItemUp method is available as of <var class=product>Sirius Mods</var> version 7.1. The FindImageItem and FindImageItemUp methods 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.
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 <var>FindImageItemUp</var> method is available as of <var class="product">Sirius Mods</var> version 7.1.  


==Syntax==
==Syntax==
Line 14: Line 16:
<tr><th>%number </th>
<tr><th>%number </th>
<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>
<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>
<tr><th>sl</th>
<td>A <var>Stringlist</var> object. </td></tr>
<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>
<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>
<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 <var class="term">item</var> is used as the match value. </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 FindImageItem, and at the last item for FindImageItemUp </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>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''' <var>Stringlist</var>. 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 <var>Stringlist</var> 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 <var class="term">EQ</var>, <var class="term">NE</var>, <var class="term">LE</var>, <var class="term">LT</var>, <var class="term">GE</var>, and <var class="term">GT</var>. If this argument is not specified or null, an equality test (<var class="term">EQ</var>) is done on all <var>Stringlist</var> items.</td></tr>
</table>
</table>


==Examples==
==Examples==
FindImageItem and FindImageItemUp are especially useful for <var>Stringlist</var>s 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>:
<var>FindImageItem</var> and <var>FindImageItemUp</var> are especially useful for <var>Stringlist</var>s whose contents map to an image. For example, in the following code fragment <var class="term">%num</var> is set to the number of the list item that is associated with the product with a code of <var class="term">983</var>:


<pre>
<pre>
Line 38: Line 40:
%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
...
...
Line 65: Line 67:


For inequality comparisons, the appropriate image-item datatype-specific comparison is performed.
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:
For example, this method invocation would start from the last <var class="term">%list</var> item and would match an item with a product code of <var class="term">-2</var>, <var class="term">-1</var>, or any number greater than or equal to zero, but it would not match one with a product code of <var class="term">-3</var> or less:


<pre>
<pre>

Revision as of 04:43, 26 January 2011

Find next matching image item in Stringlist (Stringlist class)

Find 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.

The FindImageItemUp method is available as of Sirius Mods version 7.1.

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 image item specified by item 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.

Examples

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 = findImageItem(%list, %product:code)

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.

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

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')