SubsetNew (NamedArraylist function)

From m204wiki
Revision as of 23:08, 31 January 2011 by Wiccan (talk | contribs) (1 revision)
Jump to navigation Jump to search

<section begin=dpl_desc/>Return all matching NamedArraylist items<section end=dpl_desc/>

SubsetNew is a member of the NamedArraylist class.

This function 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.

SubsetNew is available in Sirius Mods version 7.6 and later.

Syntax

%namraylNew = %namrayl:SubsetNew(criterion)

Syntax terms

%namraylNew 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.
%namrayl A NamedArraylist object.
criterion 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, GT(this, -11) is the criterion this > -11, where this is an identity function 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 %namrayl declaration and that returns a numeric or string value. This is described further in "Specifying a SelectionCriterion's parameters".

Usage Notes

  • FindNextItem is similar to SubsetNew except that it returns just the first matching item it encounters.

Examples

    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 "NamedArrayArraylist FindPreviousItem function example":

    %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