$ListFindI and $ListFindI_Up

$ListFindI and $ListFindI_Up: Find image item in $list

Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListFindI and $ListFindI_Up functions are the FindImageItem (Stringlist function) and FindImageItemUp (Stringlist function).

These functions locate a $list item that exactly matches, or satisfies a specified relationship to, either of the following:

The contents of an image item
A value converted to the image item format at the offset and length of the image item

The difference between $ListFindI and $ListFindI_Up is the direction of the search: $ListFindI searches from the starting point in ascending item number order, while $ListFindI_Up searches in descending item number order.

$ListFindI_Up is only available in Sirius Mods Version 7.1 and later.

The $ListFindI and $ListFindI_Up functions accept five arguments, and they return the item number of the $list item that matches the image item, or they returns a 0 indicating that the item was not found. All other errors cause the request to be cancelled.

The first argument is the identifier of the $list in which the value is to be located. This is a required argument.

The second argument is the image item to be matched. This is a required argument.

The third argument is 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 argument two is used as the match value.

The fourth argument is 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 $list for $ListFindI, and at the last item for $ListFindI_Up.

The fifth argument is a string comparison operator that indicates the required relationship between the match value and the item in the $list. 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 $list items. This argument is only available in Sirius Mods Version 6.5 and later.

Syntax

<section begin="syntax" />%result = $ListFindI(list_identifier, image_item, - search_value, start_item, comp_operator) <section end="syntax" />

$ListFindI Function

%result is set to the item number of the first item in the $list that matches the search criterion, or it is set to a 0 if no $list items matched the search criterion.

%RESULT = $ListFindI_Up(list_identifier, image_item, - search_value, start_item, comp_operator)

$ListFindI_Up Function

%result is set to the item number of the first item in the $list (starting from the end of the list) that matches the search criterion, or it is set to a 0 if no $list items matched the search criterion.

Since the $list item must match the offset and length of the image item, $ListFindI and $ListFindI_Up are especially useful for $lists whose contents map to an image. For example, in

IMAGE PRODUCT CODE IS BINARY LEN 2 DESC IS STRING LEN 30 END IMAGE . . . . FR PRODUCTS %PRODUCT:CODE = CODE %PRODUCT:DESC = DESC %RC = $ListAddI(%LIST, %PRODUCT:CODE) END FOR . . . . %PRODUCT:CODE = 983 %NUM = $ListFindI(%LIST, %PRODUCT:CODE)

%NUM is set to the item number associated with the product with a code of 983.

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 data type conversions required between the value and the image item are performed before the search is performed. That is, this function:

%NUM = $ListFindI(%LIST, %PRODUCT:CODE, 422)

is identical to this:

%TEMP = %PRODUCT:CODE %PRODUCT:CODE = 422 %NUM = $ListFindI(%LIST, %PRODUCT:CODE) %PRODUCT:CODE = %TEMP

For inequality comparisons, the appropriate image-item datatype-specific comparison is performed. For example:

%N = $ListFindI_Up(%LIST, %PRODUCT:CODE, -2, , 'GE')

would start from the last %list item and would match a $list item with a product code of -2, -1, or any number greater than or equal to zero, but would not match one with a product code of -3 or less.

Products authorizing $ListFindI and $ListFindI_Up

$ListFindI and $ListFindI_Up

Syntax

Navigation menu