SubsetNew (UnicodeNamedArraylist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(15 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:UnicodeNamedArraylist:SubsetNew subtitle}}
{{Template:UnicodeNamedArraylist:SubsetNew subtitle}}
<var>SubsetNew</var> searches the entire <var>UnicodeNamedArraylist</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>UnicodeNamedArraylist</var>.


This function searches the entire UnicodeNamedArraylist 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 UnicodeNamedArraylist.
==Syntax==
==Syntax==
{{Template:UnicodeNamedArraylist:SubsetNew syntax}}
{{Template:UnicodeNamedArraylist:SubsetNew syntax}}
===Syntax terms===
===Syntax terms===
<dl>
<table class="syntaxTable">
<dt><i>%unamraylNew</i>
<tr><th>%outUniNal</th>
<dd>A UnicodeNamedArraylist variable of the same type as the method
<td>A <var>UnicodeNamedArraylist</var> variable of the same type as the method <var>UnicodeNamedArraylist</var> (<var class="term">uniNal</var>) to contain the items that are located by the search. If <var class="term">outUniNal</var> is not empty, its contents are discarded before it is populated by the items returned from <var>SubsetNew</var>. </td></tr>
UnicodeNamedArraylist (''%unamrayl'') to contain the items that are
<tr><th>uniNal</th>
located by the search.
<td>A <var>UnicodeNamedArraylist</var> object. </td></tr>
If ''%unamraylNew'' is not empty, its contents are discarded before it
<tr><th>selectionCriterion</th>
is populated by the return items from SubsetNew.
<td>A <var>[[SelectionCriterion class|SelectionCriterion]]</var> object, which is a relational expression that is applied to a <var class="term">uniNal</var> item value to determine whether the value satisfies the expression. The expression consists of a function, an operator, and a <var class="product">User Language</var> intrinsic type (numeric, string, or Unicode) value.
<dt><i>%unamrayl</i>
<p>For example, <code>LT(this, 91)</code> is the criterion <code>this < 91</code>, where <code>this</code> is an identity function that simply returns the item's value. The items that satisfy this expression populate the <var>UnicodeNamedArraylist</var> that <var>SubsetNew</var> returns.
<dd>A UnicodeNamedArraylist object.
</p>
<dt><i>criterion</i>
<p>The function in the criterion is a method value (a method or class member name literal, or a [[Method variables|method variable]]) for a method that operates on items of the type specified on the <var class="term">uniNal</var> declaration and that returns an intrinsic value. This is described further in [[SelectionCriterion class#Specifying a SelectionCriterion's parameters|"Specifying a SelectionCriterion's parameters"]].
<dd>A SelectionCriterion object, which is a relational expression that is
</p></td></tr>
applied to a ''%unamrayl'' item value to determine
</table>
whether the value satisfies the expression.
The expression consists of a function, an operator, and a User Language intrinsic type
(numeric, string, or Unicode) value.


For example, <tt>LT(this, 91)</tt> is the
criterion <tt>this</tt> <tt><</tt> <tt>91</tt>, where
<tt>this</tt> is an identity function that simply returns the item's value.
The items that satisfy this expression populate the
UnicodeNamedArraylist 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 ''%unamrayl''
declaration and that returns an intrinsic value.
This is described further in "[[SelectionCriterion class#Specifying a SelectionCriterion's parameters|Specifying a SelectionCriterion's parameters]]".
</dl>
==Usage notes==
<ul>
<li>[[FindNextItem (UnicodeNamedArraylist function)|FindNextItem]]
is similar to SubsetNew except that it returns just the first matching item
it encounters.
</ul>
==Examples==
==Examples==
In the following request, a <var>SubsetNew</var> call uses a selection criterion that first applies the intrinsic [[Length (String function)|Length]] function to the collection items:
<p class="code">begin
  %k  is unicodeNamedArraylist of longstring
  %kk  is unicodeNamedArraylist of longstring
  %k = new
  %k('&sect;Jan':u) = 'Orion'
  %k('&sect;Apr':u) = 'Leo'
  %k('&sect;Mar':u) = 'Cancer'
  %k('&sect;Jun':u) = 'Ursa Minor'
  %k('&sect;Nov':u) = 'Andromeda'
  %k('&sect;Dec':u) = 'Aries'
  %k('&sect;Feb':u) = 'Canis Major'


In the following request, a SubsetNew call uses a selection criterion
  %sel is object selectionCriterion for longstring
that first applies the intrinsic [[Length (String function)|Length]] function
  %n is float
to the collection items:
  %sel = GE(length, 9)
<pre style="xmp">
    Begin


    %k  is unicodeNamedArraylist of longstring
  %kk = %k:subsetNew(%sel)
    %kk is unicodeNamedArraylist of longstring
  %kk:print
    %k = new
end
    %k('&sect;Jan':u) = 'Orion'
</p>
    %k('&sect;Apr':u) = 'Leo'
The result is:
    %k('&sect;Mar':u) = 'Cancer'
<p class="output">1: &sect.Feb: Canis Major
    %k('&sect;Jun':u) = 'Ursa Minor'
2: &sect.Jun: Ursa Minor
    %k('&sect;Nov':u) = 'Andromeda'
3: &sect.Nov: Andromeda
    %k('&sect;Dec':u) = 'Aries'
</p>
    %k('&sect;Feb':u) = 'Canis Major'


    %sel is object selectionCriterion for longstring
    %n is float
    %sel = GE(length, 9)
    %kk = %k:subsetNew(%sel)
    %kk:print
    End
</pre>
The result is:
<pre style="xmp">
    1: &sect.Feb: Canis Major
    2: &sect.Jun: Ursa Minor
    3: &sect.Nov: Andromeda
</pre>
==See also==
==See also==
<ul>
<li><var>[[FindNextItem (UnicodeNamedArraylist function)|FindNextItem]]</var> is similar to <var>SubsetNew</var> except that it returns just the first matching item it encounters.
<li>The <var>NamedArraylist</var> <var>[[SubsetNew (NamedArraylist 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>
{{Template:UnicodeNamedArraylist:SubsetNew footer}}
{{Template:UnicodeNamedArraylist:SubsetNew footer}}

Latest revision as of 16:39, 3 August 2012

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

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

Syntax

%outUniNal = uniNal:SubsetNew( selectionCriterion)

Syntax terms

%outUniNal A UnicodeNamedArraylist variable of the same type as the method UnicodeNamedArraylist (uniNal) to contain the items that are located by the search. If outUniNal is not empty, its contents are discarded before it is populated by the items returned from SubsetNew.
uniNal A UnicodeNamedArraylist object.
selectionCriterion A SelectionCriterion object, which is a relational expression that is applied to a uniNal item value to determine whether the value satisfies the expression. The expression consists of a function, an operator, and a User Language intrinsic type (numeric, string, or Unicode) value.

For example, LT(this, 91) is the criterion this < 91, where this is an identity function that simply returns the item's value. The items that satisfy this expression populate the UnicodeNamedArraylist 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 uniNal declaration and that returns an intrinsic value. This is described further in "Specifying a SelectionCriterion's parameters".

Examples

In the following request, a SubsetNew call uses a selection criterion that first applies the intrinsic Length function to the collection items:

begin %k is unicodeNamedArraylist of longstring %kk is unicodeNamedArraylist of longstring %k = new %k('§Jan':u) = 'Orion' %k('§Apr':u) = 'Leo' %k('§Mar':u) = 'Cancer' %k('§Jun':u) = 'Ursa Minor' %k('§Nov':u) = 'Andromeda' %k('§Dec':u) = 'Aries' %k('§Feb':u) = 'Canis Major' %sel is object selectionCriterion for longstring %n is float %sel = GE(length, 9) %kk = %k:subsetNew(%sel) %kk:print end

The result is:

1: &sect.Feb: Canis Major 2: &sect.Jun: Ursa Minor 3: &sect.Nov: Andromeda

See also

  • FindNextItem is similar to SubsetNew except that it returns just the first matching item it encounters.
  • The NamedArraylist 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.