SubsetImageItem (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(19 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:Stringlist:SubsetImageItem subtitle}}
{{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 a member of the [[Stringlist class]].


==Syntax==
==Syntax==
{{Template:Stringlist:SubsetImageItem syntax}}
{{Template:Stringlist:SubsetImageItem syntax}}
===Syntax terms===
===Syntax terms===
<dl>
<table class="syntaxTable">
<dt>%outlist<dd>A reference to a Stringlist which is set to the newly-created subset Stringlist.<dt>%sl<dd>A Stringlist object.<dt>item<dd>The image item to be matched.<dt>searchvalue<dd>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 '''item''' argument is used as the match value.<dt>operator<dd>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 $list items. </dl>
<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==
==Usage notes==
<ul><li>All errors in SubsetImageItem result in request cancellation.</ul>
<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:


<pre>
<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)
</pre>
</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 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 is restored to its original value. Any data type conversions required between the value and the image item are performed before the subsetting is performed.
That is, this method invocation:
 
<pre>
%olist = %list:subsetImageItem(%product:code, 13)
</pre>


<p class="code">%olist = %list:subsetImageItem(%product:code, 13)
</p>
is identical to this:
is identical to this:
 
<p class="code">%temp = %product:code
<pre>
%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
</pre>
</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 -3 or less.
 
<pre>
%olist= %list:subsetImageItem(%product:code, -2, , 'GE')
</pre>


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


[[Category:Stringlist methods|SubsetImageItem function]]
==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

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

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

  3. 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 -3 or less.

    %olist= %list:subsetImageItem(%product:code, -2, , 'GE')

See also