SelectionCriterion class

Objects in the SelectionCriterion class are used primarily as input to the collection class searching methods. 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:

• Comparisons: 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 type of comparison performed is the same as the type of the first argument of the given comparison method: String, Float, or Unicode.
• 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 virtual 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 object selectionCriterion for object myClass %sel2 is object selectionCriterion for object xmlNode %sel3 is object selectionCriterion for longstring

The declaration for %sel in the example in the preceding section might be:

%sel is object 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

The comparison 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 intrinEnum

Where:

itemtype	The class of the items in the collection to be searched.
methname	A method name, but merely a placeholder in an actual declaration. Any method (system or user), class variable, or method variable that fits the declaration can be used in the SelectionCriterion.
intrinEnum	A User Language intrinsic class type or an enumeration value returned by the function. Note: Enumeration values are allowed as of Sirius Mods 7.8, but only in the Eq and Ne methods.

The method value argument must conform to the following rules:

• It must return an intrinsic or enumeration 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 the special method value This, all of which satisfy the Function template described above.

1. 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 %i is float %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 End

   The result is:

   Jan Green employed (income: 55000) Jed Black retired (income: 30000) Jim Red employed (income: 45000) Jon White tired (income: 70000)

2. In most cases, 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))

3. 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 End

   The result is:

   1: 93 2: 77

List of SelectionCriterion methods

The "List of SelectionCriterion methods" shows all the class methods.