SubsetNew (Arraylist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
 
(18 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Template:Arraylist:SubsetNew subtitle}}
{{Template:Arraylist:SubsetNew subtitle}}
<var>SubsetNew</var> searches the entire <var>Arraylist</var> to find and return all items that match a specified criterion.  The criterion is supplied by the <var>[[SelectionCriterion class|SelectionCriterion]]</var> object that is the required <var>SubsetNew</var> parameter.  If no item satisfies the criterion, <var>SubsetNew</var> returns an empty <var>Arraylist</var>.


This function searches the entire <var>Arraylist</var> to find and return
all items that match a specified criterion.
The criterion is supplied by the [[SelectionCriterion class|SelectionCriterion]] object
that is the required <var>SubsetNew</var> parameter.
If no item satisfies the criterion, <var>SubsetNew</var> returns an empty <var>Arraylist</var>.
<var>SubsetNew</var> is available in ''Sirius Mods'' version 7.6 and later.
==Syntax==
==Syntax==
{{Template:Arraylist:SubsetNew syntax}}
{{Template:Arraylist:SubsetNew syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th><i><var class="term">al</var>New</i></th>
<tr><th>%newList</th>
<td>An <var>Arraylist</var> variable of the same type as the method <var>Arraylist</var> (''<var class="term">al</var>'') to contain the items that are located by the search. If ''<var class="term">al</var>New'' is not empty, its contents are discarded before it is populated by the return items from <var>SubsetNew</var>. </td></tr>
<td>An <var>Arraylist</var> variable of the same type as the method <var>Arraylist</var> (<var class="term">al</var>) to receive the items that are located by the search. If <var class="term">%newList</var> is not empty, its contents are discarded before it is populated by any items returned from <var>SubsetNew</var>.</td></tr>
<tr><th><i><var class="term">al</var></i></th>
 
<tr><th>al</th>
<td>An <var>Arraylist</var> object. </td></tr>
<td>An <var>Arraylist</var> object. </td></tr>
<tr><th><i>criterion</i></th>
 
<td>A <var>SelectionCriterion</var> object, which is a relational expression that is applied to an ''<var class="term">al</var>'' item value to determine whether the value satisfies the expression. The expression consists of a function, an operator, and a numeric or string value.
<tr><th>selectionCriterion</th>
<p class="code">For example, <tt>GT(this, -11)</tt> is the criterion <tt>this</tt> <tt>></tt> <tt>-11</tt>, where <tt>this</tt> is an identity function that simply returns the item's value. The items that satisfy this expression populate the <var>Arraylist</var> that <var>SubsetNew</var> returns.
<td>A <var>[[SelectionCriterion class|SelectionCriterion]]</var> object, which is a relational expression that is applied to an <var class="term">al</var> item value to determine whether the value satisfies the expression. The expression consists of a function, an operator, and a numeric or string value.
The function in the criterion is a method value (a method or class member name literal, or a method variable) for a method that operates on items of the type specified on the ''<var class="term">al</var>'' declaration and that returns a numeric or string value. This is described further in "[[SelectionCriterion class#Specifying a SelectionCriterion's parameters|Specifying a SelectionCriterion's parameters]]".</td></tr>
<p>For example, <code>GT(this, -11)</code> is the criterion <code>this > -11</code>, where <var>this</var> is an identity function value that simply returns the item's value. The items that satisfy this expression populate the <var>Arraylist</var> that <var>SubsetNew</var> returns.</p>
</p>
<p>The function in the criterion is a method value (a method or class member name literal, or a method variable) for a method that operates on items of the type specified on the <var class="term">al</var> declaration and that returns a numeric or string value. This is described further in [[SelectionCriterion class#Specifying a SelectionCriterion's parameters|"Specifying a SelectionCriterion's parameters"]].</p></td></tr>
</table>
</table>
==Usage notes==
==Usage notes==
<ul>
<ul>
<li>[[FindNextItem (Arraylist function)|FindNextItem]] without the ''Start='' argument
<li><var>[[FindNextItem (Arraylist function)|FindNextItem]]</var> without the <var>Start</var> argument is similar to <var>SubsetNew</var> except that it returns just the first matching item it encounters.
is similar to <var>SubsetNew</var> except that it returns just the first matching item
<li><var>[[CountSubset (Arraylist function)|CountSubset]]</var> returns a count of the subset of an <var>Arraylist</var> that matches a selection criterion.
it encounters.
<li><var>SubsetNew</var> is available in <var class="product">[[Sirius Mods|Sirius Mods]]</var> Version 7.6 and later.
</ul>
</ul>
==Examples==
==Examples==
<ul>
The following request contains two <var>SubsetNew</var> calls, one with a simple selection criterion and one with a compound criterion:
<li>The following request contains two <var>SubsetNew</var> calls, one with a simple
<p class="code">begin
selection criterion and one with a compound criterion:
  %al is  arraylist of float
<p class="code">Begin
  %alnew is  arraylist of float
 
  %al = list(111, 29, 0, 93, 77, -345)
%al is  arraylist of float
%alnew is  arraylist of float
  %sel1 is object selectioncriterion for float
%al = list(111, 29, 0, 93, 77, -345)
  %sel2 is object selectioncriterion for float
 
  %sel1 = GT(this, 0)
%sel1 is object selectioncriterion for float
  %sel2 = AND(GE(this, 50), LT(this, 93))
%sel2 is object selectioncriterion for float
%sel1 = GT(this, 0)
  %alnew = %al:SubsetNew(%sel1)
%sel2 = AND(GE(this, 50), LT(this, 93))
  Print 'The result of selection1 is:'
 
  %alnew:print
%alnew = %al:<var>SubsetNew</var>(%sel1)
  %alnew = %al:SubsetNew(%sel2)
Print 'The result of selection1 is:'
  print 'The result of selection2 is:'
%alnew:print
  %alnew:print
%alnew = %al:<var>SubsetNew</var>(%sel2)
end
Print 'The result of selection2 is:'
%alnew:print
 
End
</p>
</p>


Line 63: Line 57:
2: 77
2: 77
</p>
</p>
</ul>
 
==See also==
==See also==
{{Template:Arraylist:SubsetNew footer}}
{{Template:Arraylist:SubsetNew footer}}

Latest revision as of 20:23, 17 July 2012

Return all matching Arraylist items (Arraylist class)

SubsetNew searches the entire Arraylist to find and return all items that match a specified criterion. The criterion is supplied by the SelectionCriterion object that is the required SubsetNew parameter. If no item satisfies the criterion, SubsetNew returns an empty Arraylist.

Syntax

%newList = al:SubsetNew( selectionCriterion)

Syntax terms

%newList An Arraylist variable of the same type as the method Arraylist (al) to receive the items that are located by the search. If %newList is not empty, its contents are discarded before it is populated by any items returned from SubsetNew.
al An Arraylist object.
selectionCriterion A SelectionCriterion object, which is a relational expression that is applied to an al item value to determine whether the value satisfies the expression. The expression consists of a function, an operator, and a numeric or string value.

For example, GT(this, -11) is the criterion this > -11, where this is an identity function value that simply returns the item's value. The items that satisfy this expression populate the Arraylist that SubsetNew returns.

The function in the criterion is a method value (a method or class member name literal, or a method variable) for a method that operates on items of the type specified on the al declaration and that returns a numeric or string value. This is described further in "Specifying a SelectionCriterion's parameters".

Usage notes

  • FindNextItem without the Start argument is similar to SubsetNew except that it returns just the first matching item it encounters.
  • CountSubset returns a count of the subset of an Arraylist that matches a selection criterion.
  • SubsetNew is available in Sirius Mods Version 7.6 and later.

Examples

The following request contains two SubsetNew calls, one with a simple selection criterion and one with a compound criterion:

begin %al is arraylist of float %alnew is arraylist of float %al = list(111, 29, 0, 93, 77, -345) %sel1 is object selectioncriterion for float %sel2 is object selectioncriterion for float %sel1 = GT(this, 0) %sel2 = AND(GE(this, 50), LT(this, 93)) %alnew = %al:SubsetNew(%sel1) Print 'The result of selection1 is:' %alnew:print %alnew = %al:SubsetNew(%sel2) print 'The result of selection2 is:' %alnew:print end

The result is:

The result of selection1 is: 1: 111 2: 29 3: 93 4. 77 The result of selection2 is: 1: 93 2: 77

See also