SelectionCriterion class
Objects in the SelectionCriterion class are used primarily as input to the collection class searching methods (?? refid=srchcol.). The searching methods take a SelectionCriterion object as a parameter which provides an item selection specification for the search.
A selection specification, or criterion, is a relational expression that tests a collection item value to determine whether the item (or its item number) is to be returned by the searching method. The SelectionCriterion methods are named for the operation they provide:
- EQ (equal to), NE (not equal to), LT (less than), LE (less than or equal to), GT (greater than), GE (greater than or equal to).
- The AND, OR, and NOT methods let you combine comparison operations in a single criterion.
- The TRUE and FALSE methods respectively match all or no items.
- The IsNull and IsNotNull methods respectively match a collection object that is Null or one that is not Null.
Most SelectionCriterion objects use two parameters to construct a single criterion for selecting a collection item; some use two or more SelectionCriterion objects to construct a single criterion.
As an example specification, the selection criterion %sel in the following statement, instantiated by the LT constructor method, matches a number whose square root is less than 10:
%sel = lt(squareRoot, 10)
Where the left- and right-hand elements of the comparison operation are, respectively, the LT parameter values:
- The squareRoot intrinsic Float function is applied to each item value before the comparison is made.
- 10 might be any expression of any User Language intrinsic type.
This %sel criterion might be used as follows to locate the next Arraylist item after item 3 whose square root is less than 10:
%itemnum = %balance:findNextItemNumber(%sel, start=3)
The requirements for the SelectionCriterion parameter exemplified by the SquareRoot method above are:
- It must be a method or method variable defined to operate on the type of the items in the collection being searched.
- It must return an intrinsic (number, string, unicode) value.
For more about the method in a SelectionCriterion, see "Specifying a SelectionCriterion's parameters" below.
Additional notes:
- Comparison values are evaluated at SelectionCriterion construction time,
not when the search method is evaluated.
That is, the following sequence selects
items with income greater than or equal to 50000, not 100000:
%income = 50000 %sel = ge(income, %income) %income = 100000 %foo2 = %foo:subsetNew(%sel) - SelectionCriterion have a size limit: the SelectionCriterion, including the values for EQ, NE, LT, LE, GE, and GT comparisons must take less than 252 bytes. ANDs and ORs take 4 bytes, and comparison selectors have 12 bytes of overhead plus the length of the value rounded to a 4-byte multiple. So, for example, an And condition with seven 20-byte values would take 4+7*(20+12), or 228, bytes. You can work around a criterion that exceeds 252 bytes by encapsulating some or all of the conditions in a local method, since a local enhancement method can be the method parameter for a comparison SelectionCriterion.
- The SelectionCriterion methods are constructors and as such they can be
called with no method object, with an explicit class name, or with an
object variable, even if that object is null:
%selc1 = NE(criterion1, criterion2) %selc2 = %(selectionCriterion for float): - AND(criterion1, criterion2) %selc3 = %selc3:OR(criterion1, criterion2)
The SelectionCriterion class is new as of Sirius Mods version 7.6.
Declaring a SelectionCriterion object variable
The SelectionCriterion class operates on specific objects, so a variable of the SelectionCriterion class must be qualified with the object to which it applies: For example:
%sel1 is selectionCriterion for object myClass
%sel2 is selectionCriterion for object xmlNode
%sel3 is selectionCriterion for longstring
The declaration for %sel in the example in the preceding section might be:
%sel is selectionCriterion for float
SelectionCriterion object variable declaration syntax
<objvar> Is Object SelectionCriterion For <itemtype>
Where:
- <objvar>
- The name of the SelectionCriterion object variable.
- <itemtype>
- The datatype of the items in the collection to be searched.
Specifying a SelectionCriterion's parameters
As stated earlier, most of the SelectionCriterion methods accept two parameters, the first a “method value” and the second an intrinsic value. Regarding the first, just as a User Language “numeric” argument can be a numeric literal or a variable or even an expression that results in a number, a method value argument can be a method literal or a method variable or an expression that results in a method.
More specifically, a method value is a value assigned to a method variable. And for a SelectionCriterion, the method variable's implicit declaration is:
Is Function (<itemtype>):<methname> Is <intrinType>
Where:
- <itemtype>
- The class of the items in the collection to be sorted.
- <methname>
- A method name, but merely a placeholder in an actual declaration. Any method (system or user), class Variable or Property, local method, or method variable that fits the declaration can be used in the SelectionCriterion.
- <intrinType>
- A User Language intrinsic class type returned by the function.
The method value argument must conform to the following rules:
- It must return an intrinsic value.
- It cannot have any parameters other than the method object.
The following examples show different method argument types as the first parameter in a SelectionCriterion. In the examples below, the method values are respectively a class Variable, a local method, and a special method value, all of which satisfy the Function template described above.
- The selectionCriterion in the following example uses a class Variable, Income, as the criterion method parameter. The collection method, SubsetNew, returns a NamedArraylist that contains all the items that satisfied the selection criterion.
Begin class foo public variable name is string len 20 variable status is string len 8 variable income is float constructor newf(%a is string len 10, - %b string len 8, %c is float) function myprint is longstring end public constructor newf(%a is string len 10, - %b string len 8, %c is float) %this:name = %a %this:status = %b %this:income = %c end constructor function myprint is longstring return %this:name with ' ' with - %this:status with ' ' with - '(income: ' with %this:income with ')' end function end class %fool is namedArraylist of object foo %fool = new %fool('Jim') = newf('Red', 'employed', 45000) %fool('Jed') = newf('Black', 'retired', 30000) %fool('Jan') = newf('Green', 'employed', 55000) %fool('Jud') = newf('Brown', 'expired', 0) %fool('Jon') = newf('White', 'tired', 70000) %fool = %fool:subsetNew(gt(income, 0)) for %i from 1 to %fool:count print %fool:namebynumber(%i) And - %fool:itembyNumber(%i):myprint end for EndThe result is:
Jan Green employed (income: 55000) Jed Black retired (income: 30000) Jim Red employed (income: 45000) Jon White tired (income: 70000) - The second parameter in most SelectionCriterion methods is a User Language
intrinsic-type value, often a string or numeric literal.
Consequently, you cannot specify a criterion that compares two method
values.
For example, for a Cust class (similar to the class in the previous
example) with variables Expenses
and Income, you might want to find all the customers with expenses
greater than income — but the following is not allowed:
%custDebtors = %custs:subsetNew(gt(expenses, income))
However, you can create a local method with which you can achieve the same result:
local function (cust):netIncome is float return %this:income - %this:expenses end function %custDebtors = %custs:subsetNew(lt(netIncome, 0)) - The SelectionCriterion in the following request uses the special method value This as the method parameter, and the And constructor combines two criteria to create one criterion. Valid only for intrinsic classes, This simply returns the value of the method object.
Begin %fooflt is arraylist of float %fooflt = list(111, 29, 93, 77, -345) %sel is object selectioncriterion for float %sel = and(gt(this, 50), le(this, 93)) %fooflt = %fooflt:subsetnew(%sel) %fooflt:print EndThe result is:
1: 93 2: 77