SelectionCriterion class: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(9 intermediate revisions by 3 users not shown)
Line 10: Line 10:
The <var>SelectionCriterion</var> methods are named for the operation they provide:
The <var>SelectionCriterion</var> methods are named for the operation they provide:
<ul>
<ul>
<li><var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Eq]]</var> (equal to), <var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Ne]]</var> (not equal to), <var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Lt]]</var> (less than), <var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Le]]</var> (less than or equal to),
<li>Comparisons: <var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Eq]]</var> (equal to), <var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Ne]]</var> (not equal to), <var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Lt]]</var> (less than), <var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Le]]</var> (less than or equal to),
<var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Gt]]</var> (greater than), <var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Ge]]</var> (greater than or equal to).
<var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Gt]]</var> (greater than), <var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Ge]]</var> (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: <var>String</var>, <var>Float</var>, or <var>Unicode</var>.
 
<li>The <var>[[And and Or (SelectionCriterion functions)|And]]</var>, <var>[[And and Or (SelectionCriterion functions)|Or]]</var>, and <var>[[Not (SelectionCriterion function)|Not]]</var> methods let you combine comparison operations in a single criterion.
<li>The <var>[[And and Or (SelectionCriterion functions)|And]]</var>, <var>[[And and Or (SelectionCriterion functions)|Or]]</var>, and <var>[[Not (SelectionCriterion function)|Not]]</var> methods let you combine comparison operations in a single criterion.
<li>The <var>[[True and False (SelectionCriterion functions)|True]]</var> and <var>[[True and False (SelectionCriterion functions)|False]]</var> methods respectively match all or no items.
<li>The <var>[[True and False (SelectionCriterion functions)|True]]</var> and <var>[[True and False (SelectionCriterion functions)|False]]</var> methods respectively match all or no items.
<li>The <var>[[IsNull and IsNotNull (SelectionCriterion functions)|IsNull]]</var> and <var>[[IsNull and IsNotNull (SelectionCriterion functions)|IsNotNull]]</var> methods respectively match a collection object that is <var>Null</var>
<li>The <var>[[IsNull and IsNotNull (SelectionCriterion functions)|IsNull]]</var> and <var>[[IsNull and IsNotNull (SelectionCriterion functions)|IsNotNull]]</var> methods respectively match a collection object that is <var>Null</var>
or one that is not <var>Null</var>.
or one that is not <var>Null</var>.
Line 89: Line 92:
The <var>SelectionCriterion</var> class is new as of <var class="product">Sirius Mods</var> version 7.6.
The <var>SelectionCriterion</var> class is new as of <var class="product">Sirius Mods</var> version 7.6.
   
   
The [[List of SelectionCriterion methods|"List of SelectionCriterion methods"]] lists all the methods in this class.
===Declaring a SelectionCriterion object variable===
===Declaring a SelectionCriterion object variable===
The <var>SelectionCriterion</var> class operates on specific objects, so a variable of the
The <var>SelectionCriterion</var> class operates on specific objects, so a variable of the
<var>SelectionCriterion</var> class must be qualified with the object to which it applies:
<var>SelectionCriterion</var> class must be qualified with the object to which it applies:
For example:
For example:
<p class="code"><nowiki>%sel1 is selectionCriterion for object myClass
<p class="code"><nowiki>%sel1 is object selectionCriterion for object myClass
%sel2 is selectionCriterion for object xmlNode
%sel2 is object selectionCriterion for object xmlNode
%sel3 is selectionCriterion for longstring
%sel3 is object selectionCriterion for longstring
</nowiki></p>
</nowiki></p>
   
   
The declaration for <code>%sel</code> in the example in the preceding section
The declaration for <code>%sel</code> in the example in the preceding section might be:
might be:
<p class="code"><nowiki>%sel is object selectionCriterion for float
<p class="code"><nowiki>%sel is selectionCriterion for float
</nowiki></p>
</nowiki></p>
   
   
Line 117: Line 117:
<td>The datatype of the items in the collection to be searched.
<td>The datatype of the items in the collection to be searched.
</td></tr></table>
</td></tr></table>
===Specifying a SelectionCriterion's parameters===
===Specifying a SelectionCriterion's parameters===
As stated earlier, most of the <var>SelectionCriterion</var> methods
The comparison <var>SelectionCriterion</var> methods
accept two parameters, the first a &ldquo;method value&rdquo; and the second an
accept two parameters, the first a "method value" and the second an
intrinsic value.
intrinsic value.
Regarding the first, just as
Regarding the first, just as
a <var class="product">User Language</var> &ldquo;numeric&rdquo; argument can be a numeric literal or a variable or even an
a <var class="product">User Language</var> "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
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.
literal or a method variable or an expression that results in a method.
Line 128: Line 129:
More specifically, a method value is a value assigned to a [[Method variables|method variable]].
More specifically, a method value is a value assigned to a [[Method variables|method variable]].
And for a <var>SelectionCriterion</var>, the method variable's ''implicit'' declaration is:
And for a <var>SelectionCriterion</var>, the method variable's ''implicit'' declaration is:
<p class="syntax"><span class="literal">Is Function (</span><span class="term">itemtype</span><span class="literal">):</span><span class="term">methname</span> <span class="literal">Is</span> <span class="term">intrinType</span></p>
<p class="syntax"><span class="literal">Is Function (</span><span class="term">itemtype</span><span class="literal">):</span><span class="term">methname</span> <span class="literal">Is</span> <span class="term">intrinEnum</span></p>
Where:
Where:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>itemtype</th>
<tr><th>itemtype</th>
<td>The class of the items in the collection to be sorted.
<td>The class of the items in the collection to be searched.
</td></tr>
</td></tr>
<tr><th>methname</th>
<tr><th>methname</th>
<td>A method name, but merely a placeholder in an actual declaration. Any method (system or user), class <var>Variable</var> or <var>Property</var>, local method, or method variable that fits the declaration can be used in the <var>SelectionCriterion</var>.
<td>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 <var>SelectionCriterion</var>.
</td></tr>
</td></tr>
<tr><th>intrinType</th>
<tr><th>intrinEnum</th>
<td>A <var class="product">User Language</var> [[Intrinsic classes#intrins_classes|intrinsic class]] type returned by the function.
<td>A <var class="product">User Language</var> [[Intrinsic classes#intrins_classes|intrinsic class]] type or an [[Enumerations|enumeration]] value returned by the function. <p>
'''Note:''' Enumeration values are allowed as of <var class="product">Sirius Mods</var> 7.8, but only in the <var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Eq]]</var> and <var>[[Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions)|Ne]]</var> methods.</p>
</td></tr></table>
</td></tr></table>
   
   
The method value argument must conform to the following rules:
The method value argument must conform to the following rules:
<ul>
<ul>
<li>It must return an intrinsic value.
<li>It must return an intrinsic or enumeration value.
<li>It cannot have any parameters other than the method object.
<li>It cannot have any parameters other than the method object.
</ul>
</ul>
Line 149: Line 151:
The following examples show different method argument types
The following examples show different method argument types
as the first parameter in a <var>SelectionCriterion</var>.
as the first parameter in a <var>SelectionCriterion</var>.
In the examples below, the method values are respectively a class <var>Variable</var>,
In the examples below, the method values are respectively a class variable,
a local method, and the special method value <var>This</var>, all of which
a local method, and the special method value <var>This</var>, all of which
satisfy the <var>Function</var> template described above.
satisfy the <var>Function</var> template described above.
<ol>
<ol>
<li><div id="xmpxsub"></div>The selectionCriterion in the following example uses a class <var>Variable</var>, <code>Income</code>, as the criterion method parameter. The collection method, <var>SubsetNew</var>, returns a <var>NamedArraylist</var> that contains all the items that satisfied the selection
<li><div id="xmpxsub"></div>The <var>SelectionCriterion</var> in the following example uses a class variable, <code>Income</code>, as the criterion method parameter. The collection method, <var>SubsetNew</var>, returns a <var>NamedArraylist</var> that contains all the items that satisfied the selection criterion.
criterion.
<p class="code"><nowiki>Begin
<p class="code"><nowiki>Begin
class foo
class foo
Line 180: Line 181:
end class
end class
   
   
%i is float
%fool  is namedArraylist of object foo
%fool  is namedArraylist of object foo
%fool = new
%fool = new
Line 204: Line 206:
Jon White tired (income: 70000)
Jon White tired (income: 70000)
</nowiki></p>
</nowiki></p>
<li>The second parameter in most <var>SelectionCriterion</var> methods is a <var class="product">User Language</var>
 
<li>In most cases, the second parameter in most <var>SelectionCriterion</var> methods is a <var class="product">User Language</var>
intrinsic-type value, often a string or numeric literal.
intrinsic-type value, often a string or numeric literal.
Consequently, you cannot specify a criterion that compares two method
Consequently, you cannot specify a criterion that compares two method
Line 222: Line 225:
%custDebtors = %custs:subsetNew(lt(netIncome, 0))
%custDebtors = %custs:subsetNew(lt(netIncome, 0))
</nowiki></p>
</nowiki></p>
<li><div id="xmpthis"></div>The <var>SelectionCriterion</var> in the following request uses the special method value <var>This</var> as the method parameter, and the <var>And</var> constructor combines two criteria to create one criterion. Valid only for intrinsic classes, <var>This</var> simply ret
<li><div id="xmpthis"></div>The <var>SelectionCriterion</var> in the following request uses the special method value <var>This</var> as the method parameter, and the <var>And</var> constructor combines two criteria to create one criterion. Valid only for intrinsic classes, <var>This</var> simply returns the value of the method object.
<p class="code"><nowiki>Begin
<p class="code"><nowiki>Begin
%fooflt is  arraylist of float
%fooflt is  arraylist of float
Line 240: Line 243:
</nowiki></p>
</nowiki></p>
</ol>
</ol>
==See also==
 
<table class="list"><tr>
==List of SelectionCriterion methods==
<td valign="top"><ul style="margin-top:0px;">
The [[List of SelectionCriterion methods|"List of SelectionCriterion methods"]] shows all the class methods.
<li>[[List of SelectionCriterion methods]]
 
</ul></td>
<td valign="top"><ul style="margin-top:0px;">
<li>[[SelectionCriterion methods syntax]]
</ul></td>
</tr>
</table>
[[Category:System classes]]
[[Category:System classes]]

Latest revision as of 20:11, 13 August 2012

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.