SubsetImageItem (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
m (→Examples) |
||
| (20 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Stringlist:SubsetImageItem subtitle}} | |||
This method locates all Stringlist items that exactly match the contents of an image item, or that match a value converted to the image item format at the offset and length of the image item, and it places these image items into a new Stringlist that is a subset of the old Stringlist. The SubsetImageItem method accepts three arguments and returns a Stringlist. | This method locates all <var>Stringlist</var> items that exactly match the contents of an image item, or that match a value converted to the image item format at the offset and length of the image item, and it places these image items into a new <var>Stringlist</var> that is a subset of the old <var>Stringlist</var>. The <var>SubsetImageItem</var> method accepts three arguments and returns a <var>Stringlist</var>. | ||
SubsetImageItem is | ==Syntax== | ||
{{Template:Stringlist:SubsetImageItem syntax}} | |||
===Syntax terms=== | |||
<table class="syntaxTable"> | |||
<tr><th>%outlist</th> | |||
<td>A reference to a <var>Stringlist</var> which is set to the newly-created subset <var>Stringlist</var>.</td></tr> | |||
<tr><th>sl</th> | |||
<td>A <var>Stringlist</var> object.</td></tr> | |||
<tr><th>imageItem</th> | |||
<td>The image item to be matched.</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 the <var class="term">imageItem</var> argument is used as the match value.</td></tr> | |||
<tr><th>operator</th> | |||
<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 class="term">sl</var> items.</td></tr> | |||
</table> | |||
== | ==Usage notes== | ||
< | <ul><li>All errors in <var>SubsetImageItem</var> result in request cancellation.</ul> | ||
</ | |||
==Examples== | ==Examples== | ||
SubsetImageItem is especially useful for Stringlists whose contents map to an image, as for example in the following: | <ol><li><var>SubsetImageItem</var> is especially useful for <var>Stringlists</var> whose contents map to an image, as for example in the following: | ||
< | <p class="code">image product | ||
image product | code is binary len 2 | ||
code is binary len 2 | type is string len 8 | ||
type is string len 8 | desc is string len 30 | ||
desc is string len 30 | |||
end image | end image | ||
... | ... | ||
fr products | fr products | ||
%product:code = code | %product:code = code | ||
%product:type = type | %product:type = type | ||
%product:desc = desc | %product:desc = desc | ||
%list:addImage('PRODUCT') | %list:addImage('PRODUCT') | ||
end for | end for | ||
... | ... | ||
%product:type = 'WIDGET' | %product:type = 'WIDGET' | ||
%wlist = %list:subsetImageItem(%product:type) | %wlist = %list:subsetImageItem(%product:type) | ||
</ | </p> | ||
<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 first assigned to the <var class="term">imageItem</var>, and then the <var class="term">imageItem</var> is restored to its original value upon processing completion. Any data type conversions required between the <var class="term">searchValue</var> and the <var class="term">imageItem</var> are performed before the subsetting is performed. That is, this method invocation: | |||
If a | |||
That is, this method invocation: | |||
<p class="code">%olist = %list:subsetImageItem(%product:code, 13) | |||
</p> | |||
is identical to this: | is identical to this: | ||
<p class="code">%temp = %product:code | |||
< | |||
%temp = %product:code | |||
%product:code = 13 | %product:code = 13 | ||
%olist = %list:subsetImageItem(%product:code) | %olist = %list:subsetImageItem(%product:code) | ||
%product:code = %temp | %product:code = %temp | ||
</ | </p> | ||
<li>For inequality comparisons, the appropriate image-item datatype-specific comparison is performed. For example, the following method selects all <var>Stringlist</var> items with a product code of <code>-2</code>, <code>-1</code>, or any number greater than or equal to zero, but it does not select any with a product code of <code>-3</code> or less. | |||
For inequality comparisons, the appropriate image-item datatype-specific comparison is performed. | |||
For example, the following method selects all Stringlist items with a product code of -2, -1, or any number greater than or equal to zero, but it does not select any with a product code of | |||
< | |||
</ | |||
<p class="code">%olist= %list:subsetImageItem(%product:code, -2, , 'GE') | |||
</p> | |||
</ol> | |||
==See also== | |||
{{Template:Stringlist:SubsetImageItem footer}} | |||
Latest revision as of 00:51, 1 November 2012
Create Stringlist subset based on image item (Stringlist class)
This method locates all Stringlist items that exactly match the contents of an image item, or that match a value converted to the image item format at the offset and length of the image item, and it places these image items into a new Stringlist that is a subset of the old Stringlist. The SubsetImageItem method accepts three arguments and returns a Stringlist.
Syntax
%outList = sl:SubsetImageItem( imageItem, [searchValue], [operator])
Syntax terms
| %outlist | A reference to a Stringlist which is set to the newly-created subset Stringlist. |
|---|---|
| sl | A Stringlist object. |
| imageItem | The image item to be matched. |
| 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 the imageItem argument is used as the match value. |
| 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 sl items. |
Usage notes
- All errors in SubsetImageItem result in request cancellation.
Examples
- SubsetImageItem is especially useful for Stringlists whose contents map to an image, as for example in the following:
image product code is binary len 2 type is string len 8 desc is string len 30 end image ... fr products %product:code = code %product:type = type %product:desc = desc %list:addImage('PRODUCT') end for ... %product:type = 'WIDGET' %wlist = %list:subsetImageItem(%product:type)
- If a searchValue is specified in addition to the imageItem, processing is performed as if the searchValue were first assigned to the imageItem, and then the imageItem is restored to its original value upon processing completion. Any data type conversions required between the searchValue and the imageItem are performed before the subsetting is performed. That is, this method invocation:
%olist = %list:subsetImageItem(%product:code, 13)
is identical to this:
%temp = %product:code %product:code = 13 %olist = %list:subsetImageItem(%product:code) %product:code = %temp
- For inequality comparisons, the appropriate image-item datatype-specific comparison is performed. For example, the following method selects all Stringlist items with a product code of
-2,-1, or any number greater than or equal to zero, but it does not select any with a product code of-3or less.%olist= %list:subsetImageItem(%product:code, -2, , 'GE')