SubsetNew (NamedArraylist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:NamedArraylist:SubsetNew subtitle}}
{{Template:NamedArraylist:SubsetNew subtitle}}
<var>SubsetNew</var> searches the entire <var>NamedArraylist</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>NamedArraylist</var>.


This function searches the entire NamedArraylist 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 SubsetNew parameter.
If no item satisfies the criterion, SubsetNew returns an empty NamedArraylist.
SubsetNew is available in ''Sirius Mods'' version 7.6 and later.
==Syntax==
==Syntax==
{{Template:NamedArraylist:SubsetNew syntax}}
{{Template:NamedArraylist:SubsetNew syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%namraylNew</th>
<tr><th>%outNal</th>
<td>A NamedArraylist variable of the same type as the method NamedArraylist (''%namrayl'') to contain the items that are located by the search. If ''%namraylNew'' is not empty, its contents are discarded before it is populated by the return items from SubsetNew. </td></tr>
<td>A <var>NamedArraylist</var> variable of the same type as the method <var>NamedArraylist</var> (<var class="term">nal</var>) to contain the items that are located by the search. If <var class="term">outNal</var> is not empty, its contents are discarded before it is populated by the items returned from <var>SubsetNew</var>. </td></tr>
<tr><th>%namrayl</th>
<td>A NamedArraylist object. </td></tr>
<tr><th>criterion</th>
<td>A SelectionCriterion object, which is a relational expression that is applied to a ''%namrayl'' 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, <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 NamedArraylist that SubsetNew returns.
<tr><th>nal</th>
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 ''%namrayl'' 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>
<td>A <var>NamedArraylist</var> object. </td></tr>


<tr><th>selectionCriterion</th>
<td>A <var>SelectionCriterion</var> object, which is a relational expression that is applied to a <var class="term">nal</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.
<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>NamedArraylist</var> that <var>SubsetNew</var> returns.</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">nal</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><var>SubsetNew</var> is available in <var class="product">[[Sirius Mods|Sirius Mods]]</var> Version 7.6 and later.
<li><var>[[FindNextItem (NamedArraylist function)|FindNextItem]]</var>
is similar to <var>SubsetNew</var> except that it returns just the first matching item
it encounters.
</ul>
</ul>
==Examples==
==Examples==
<ul>
<ol>
In the following fragment, a SubsetNew call is applied to a collection
<li>In the following fragment, a <var>SubsetNew</var> call is applied to a collection of objects of the <code>staff</code> class that is defined in the request in the <var>NamedArraylist</var> <var>FindNextItem</var> [[FindNextItem (GenericNamedArraylist function)#Examples|"Examples"]] section:
of objects of the <tt>staff</tt> class that is defined in the
request in the <var>NamedArraylist</var> <var>FindNextItem</var> [[FindNextItem (GenericNamedArraylist function)#Examples|"Examples"]] section:
<p class="code">%old is namedArraylist of object staff
<p class="code">%old is namedArraylist of object staff
%old = new
%old = new
Line 49: Line 41:
%fnd:Print(name, separator=' ')
%fnd:Print(name, separator=' ')
</p>
</p>
The result is:
The result is:
<p class="output">1 Jed Black
<p class="output">1 Jed Black
2 Jud Brown
2 Jud Brown
</p>
</p>
<li>In the following fragment, two nearly identical <var>SubsetNew</var> calls are used.  The first uses a <var>SelectionCriterion</var> whose first argument (<code>this</code>) is a <var>String</var> valued function, and so EBCDIC comparisons are used. The second uses a <var>SelectionCriterion</var> whose first argument (<code>this</code>) is a <var>Unicode</var> valued function, and so Unicode comparisons are used.
<p class="code">%hit is namedArraylist of string len 30           
%hit = new                                       
%hit('Clapton') = 'Layla'                         
%hit('Davies') = 'All Day and All of the Night'   
%hit('Simon') = '50 Ways to Leave Your Lover'     
%Hit = %Hit:subsetNew(LE(this, '51'))             
%Hit:print                                       
%unicHit is namedArraylist of unicode             
%unicHit = new                                   
%unicHit('Clapton') = 'Layla'                     
%unicHit('Davies') = 'All Day and All of the Night'
%unicHit('Simon') = '50 Ways to Leave Your Lover' 
%unicHit = %unicHit:subsetNew(LE(this, '51'))     
%unicHit:print
</p>
The result is:
<p class="output">1: Clapton: Layla                       
2: Davies: All Day and All of the Night 
3: Simon: 50 Ways to Leave Your Lover   
1: Simon: 50 Ways to Leave Your Lover   
</p>
In an EBCDIC comparison, letters (here, <code>L</code> and <code>A</code>) are less then numeric digits (here, <code>5</code>); in a Unicode comparison, (Latin) letters are greater than numeric digits.
==See also==
<ul><li><var>[[FindNextItem (NamedArraylist function)|FindNextItem]]</var> is similar to <var>SubsetNew</var> except that it returns just the first matching item it encounters.
<li>The <var>UnicodeNamedArraylist</var> <var>[[SubsetNew (UnicodeNamedArraylist function)|SubsetNew]]</var> and <var>FloatNamedArraylist</var> <var>[[SubsetNew (FloatNamedArraylist function)|SubsetNew]]</var> functions also perform the subsetting function &mdash; for their respective classes. The examples on those pages may provide for possible additional approaches for <var>SubsetNew</var>.
</ul>
</ul>
==See also==
{{Template:NamedArraylist:SubsetNew footer}}
{{Template:NamedArraylist:SubsetNew footer}}

Latest revision as of 21:51, 11 August 2012

Create NamedArraylist of items matching some selection criteria (NamedArraylist class)

SubsetNew searches the entire NamedArraylist 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 NamedArraylist.

Syntax

%outNal = nal:SubsetNew( selectionCriterion)

Syntax terms

%outNal A NamedArraylist variable of the same type as the method NamedArraylist (nal) to contain the items that are located by the search. If outNal is not empty, its contents are discarded before it is populated by the items returned from SubsetNew.
nal A NamedArraylist object.
selectionCriterion A SelectionCriterion object, which is a relational expression that is applied to a nal 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 NamedArraylist 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 nal declaration and that returns a numeric or string value. This is described further in "Specifying a SelectionCriterion's parameters".

Usage notes

  • SubsetNew is available in Sirius Mods Version 7.6 and later.

Examples

  1. In the following fragment, a SubsetNew call is applied to a collection of objects of the staff class that is defined in the request in the NamedArraylist FindNextItem "Examples" section:

    %old is namedArraylist of object staff %old = new %old('Jim') = newf('Red', 'employed') %old('Jed') = newf('Black', 'retired') %old('Jan') = newf('Green', 'employed') %old('Jud') = newf('Brown', 'retired') %old('Jon') = newf('White', 'retired') %sel is object selectioncriterion for object staff %sel = AND(LT(name, 'Mud'), EQ(status, 'retired')) %fnd is namedArraylist of object staff %fnd = %old:SubsetNew(%sel) %fnd:Print(name, separator=' ')

    The result is:

    1 Jed Black 2 Jud Brown

  2. In the following fragment, two nearly identical SubsetNew calls are used. The first uses a SelectionCriterion whose first argument (this) is a String valued function, and so EBCDIC comparisons are used. The second uses a SelectionCriterion whose first argument (this) is a Unicode valued function, and so Unicode comparisons are used.

    %hit is namedArraylist of string len 30 %hit = new %hit('Clapton') = 'Layla' %hit('Davies') = 'All Day and All of the Night' %hit('Simon') = '50 Ways to Leave Your Lover' %Hit = %Hit:subsetNew(LE(this, '51')) %Hit:print %unicHit is namedArraylist of unicode %unicHit = new %unicHit('Clapton') = 'Layla' %unicHit('Davies') = 'All Day and All of the Night' %unicHit('Simon') = '50 Ways to Leave Your Lover' %unicHit = %unicHit:subsetNew(LE(this, '51')) %unicHit:print

    The result is:

    1: Clapton: Layla 2: Davies: All Day and All of the Night 3: Simon: 50 Ways to Leave Your Lover 1: Simon: 50 Ways to Leave Your Lover

    In an EBCDIC comparison, letters (here, L and A) are less then numeric digits (here, 5); in a Unicode comparison, (Latin) letters are greater than numeric digits.

    See also

    • FindNextItem is similar to SubsetNew except that it returns just the first matching item it encounters.
    • The UnicodeNamedArraylist SubsetNew and FloatNamedArraylist SubsetNew functions also perform the subsetting function — for their respective classes. The examples on those pages may provide for possible additional approaches for SubsetNew.