FindImageItem and FindImageItemUp (Stringlist functions)

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