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.

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
    
       %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. 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 :hp3.is not allowed:ehp3.:

       %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 when applied to User Language intrinsic method objects, 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