Eq, Ne, Ge, Gt, Le and Lt (SelectionCriterion functions): Difference between revisions
mNo edit summary |
|||
(27 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
{{ | {{Template:SelectionCriterion:Eq, Ne, Ge, Gt, Le and Lt subtitle}} | ||
These shared methods each create a new SelectionCriterion object | These [[Notation conventions for methods#Shared members|shared methods]] each create a new <var>SelectionCriterion</var> object | ||
that is a relational expression used to select items from a collection. | that is a relational expression used to select items from a collection. | ||
Each of these constructors provides a different comparison operator. | Each of these constructors provides a different comparison operator. | ||
The | The <var>Eq</var> method, for example, constructs an equality expression that | ||
selects a collection item if the expression is true for that item. | selects a collection item if the expression is true for that item. | ||
The other methods construct, respectively, not-equal-to, greater-than-or-equal-to, | The other methods construct, respectively, not-equal-to, greater-than-or-equal-to, | ||
greater-than, less-than-or-equal-to, or less-than expressions. | greater-than, less-than-or-equal-to, or less-than expressions. | ||
The first of the two parameters in a selection criterion specifies a function | The first of the two parameters in a selection criterion specifies a function | ||
that is applied to a collection item. | that is applied to a collection item. | ||
The function result is the | The function result is the "left-side" operand in the criterion's expression. | ||
The second selection criterion parameter is a string or numeric that is | The second selection criterion parameter is a string or numeric that is | ||
the | the "right-side" operand in the expression. | ||
< | <code>Eq(name, 'Ortiz')</code> specifies the expression <code>name='Ortiz'</code>. | ||
The function parameter of one of these | The function parameter of one of these methods might simply be an | ||
identity function that returns the item value. | identity function that returns the item value. | ||
Or, for example, | Or, for example, | ||
Line 37: | Line 22: | ||
for an item that is an object. | for an item that is an object. | ||
This function must be | This function must be | ||
a method that operates on the item type and returns a User Language intrinsic | a method that operates on the item type and returns a <var class="product">User Language</var> [[Intrinsic classes#Two generic intrinsic classes: string and numeric|intrinsic datatype]] | ||
(<var>Float</var>, <var>String</var>, or <var>Unicode</var>) value. | |||
== | |||
==Syntax == | |||
{{Template:SelectionCriterion:Eq syntax}} | |||
{{Template:SelectionCriterion:Ne syntax}} | |||
{{Template:SelectionCriterion:Ge syntax}} | |||
{{Template:SelectionCriterion:Gt syntax}} | |||
{{Template:SelectionCriterion:Le syntax}} | |||
{{Template:SelectionCriterion:Lt syntax}} | |||
===Syntax terms=== | ===Syntax terms=== | ||
< | <table class="syntaxTable"> | ||
< | <tr><th>%selectionCriterion</th> | ||
< | <td>A <var>SelectionCriterion</var> object variable to contain the new object instance.</td></tr> | ||
< | |||
< | <tr><th nowrap="true"><var>[%(SelectionCriterion For <i>itemType</i>):]</var></th> | ||
in parentheses | <td>For a shared function, this optional specification of the class in parentheses denotes a [[Notation conventions for methods#Shared methods|virtual constructor]]. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a <var>SelectionCriterion</var> virtual constructor. </td></tr> | ||
< | <tr><th>itemFunctionEnum</th> | ||
< | <td>A method value (a method name literal, a method variable, a class <var>Variable</var>, or even a method that returns a method value) for a method that operates on objects of the type specified on the declaration of the collection being searched, and that returns a <var class="product">User Language</var> intrinsic (<var>String</var>, <var>Float</var>, or <var>Unicode</var>) value. The returned type determines the type of comparison used to determine if an item satisfies the criterion. See [[#examp3|Example 3]] below. | ||
or even a method that returns a method value) for a method | <p> | ||
that operates on objects of the type specified on the | For the <var>Eq</var> and <var>Ne</var> methods only, the return value of this argument's function may also be an enumeration value, as of <var class="product">Sirius Mods</var> Version 7.8. See [[#Examples|Example 1]] below. </p></td></tr> | ||
declaration of the collection being searched, and that returns a User Language intrinsic | |||
( | <tr><th>result</th> | ||
< | <td>An intrinsic value or expression, or an enumeration value (allowed for <var>Eq</var> and <var>Ne</var> only).</td></tr> | ||
< | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul> | <ul> | ||
<li>For more information about the | <li>As described in [[Object variables#Virtual Constructor methods|"Virtual Constructor methods"]], <var>Eq</var> and the rest of these functions can be invoked with | ||
no method object, with an explicit class specification, or with an object variable of the class, | |||
even if that object is <var>Null</var>: | |||
<p class="code">%selCrit = Eq(<i>itemFunctionEnum</i>, <i>result</i>) | |||
%selCrit = %(SelectionCriterion for float):LE(<i>itemFunctionEnum</i>, <i>result</i>) | |||
%selCrit = %selCrit:Gt(<i>itemFunctionEnum</i>, <i>result</i>) | |||
</p> | |||
'''Note:''' | |||
As shown in the second of these above, if you explicitly specify the | |||
class name, you must include the item datatype of the collection to be searched, just as on a <var>SelectionCriterion</var> object variable's [[SelectionCriterion class#Declaring a SelectionCriterion object variable|declaration]]. | |||
<li>For more information about the <var class="term">itemFunctionEnum</var> parameter, | |||
see "[[SelectionCriterion class#Specifying a SelectionCriterion's parameters|Specifying a SelectionCriterion's parameters]]". | see "[[SelectionCriterion class#Specifying a SelectionCriterion's parameters|Specifying a SelectionCriterion's parameters]]". | ||
<li>The | |||
and you may not specify a function that itself has an argument. | <li>The <var class="term">itemFunctionEnum</var> parameter is a method value, not a <var class="product">User Language</var> expression, and you may not specify a function that itself has an argument. | ||
The SelectionCriterion syntax does not provide | The <var>SelectionCriterion</var> syntax does not provide | ||
for specifying a parameter for the | for specifying a parameter for the <var class="term">itemFunctionEnum</var> parameter. | ||
If necessary, the workaround for this restriction is to define a local method | If necessary, the workaround for this restriction is to define a [[Local and Common entities|local method]] | ||
that accepts an argument, then use that method as the | that accepts an argument, then use that method as the <var class="term">itemFunctionEnum</var> parameter. | ||
parameter. | |||
<li>The | <li>The <var class="term">itemFunctionEnum</var> may be <var>This</var>, an identity | ||
method that is valid for User Language intrinsic method objects only. | method that is valid for <var class="product">User Language</var> intrinsic method objects only. | ||
The < | The <var>This</var> method returns the value of the item to which it is applied. | ||
to which it is applied. | [[SelectionCriterion class#xmpthis|This example]] on the [[SelectionCriterion class|"SelectionCriterion class"]] page uses <var>This</var>. | ||
<li>If <var class="term">itemFunctionEnum</var> is an enumeration, null values are not a problem. But the <var>Eq</var> and <var>Ne</var> methods handle nulls differently: for example, | |||
<code>Eq(foo, true)</code> does not match an item with a null value of <code>foo</code>, but <code>Ne(foo, false)</code> does. | |||
</ul> | </ul> | ||
==Examples== | ==Examples== | ||
<ol> | <ol> | ||
<li>The following criterion matches a number greater than 10: | <li>The following criterion matches a number greater than 10: | ||
< | <p class="code">%sel = gt(this, 10) | ||
</p> | |||
</ | |||
The following matches a number with an absolute value less than or | The following matches a number with an absolute value less than or | ||
equal to 100: | equal to 100: | ||
< | <p class="code">%sel = le(absolute, 100) | ||
</p> | |||
</ | |||
The following matches items whose <code>reserve</code> return value is a <var>[[Boolean enumeration|Boolean]]</var> <var>True</var>: | |||
<p class="code">%sel = eq(reserve, true) </p> | |||
The following matches numbers less than 70 and greater than or equal to 95: | The following matches numbers less than 70 and greater than or equal to 95: | ||
< | <p class="code">%sel = or(lt(this,70), ge(this,95)) | ||
</p> | |||
</ | |||
<li>The following request fragment selects two items from | <li>The following request fragment selects two items from | ||
the <tt>%fool</tt> NamedArraylist in the [[SelectionCriterion class#xmpxsub|SubsetNew example]]: | the <tt>%fool</tt> NamedArraylist in the [[SelectionCriterion class#xmpxsub|SubsetNew example]]: | ||
< | <p class="code"> ... | ||
%sel is object selectionCriterion for object foo | |||
%sel = EQ(status, 'employed') | |||
%fool = %fool:subsetNew(%sel) | |||
for %i from 1 to %fool:count | |||
print %fool:namebynumber(%i) And - | |||
%fool:itembyNumber(%i):myprint | |||
end for | |||
... | |||
</ | </p> | ||
The result is: | The result is: | ||
< | <p class="output">Jan Green employed (income: 55000) | ||
Jim Red employed (income: 45000) | |||
</p> | |||
</ | <div id="examp3"></div> | ||
<li>In the following fragment, two nearly identical <var>SubsetNew</var> calls are used. The first uses a <var>SelectionCriterion</var> whose first argument (<code>this</code>) is a <var>String</var> valued function, and so EBCDIC comparisons are used. The second uses a <var>SelectionCriterion</var> whose first argument (<code>this</code>) is a <var>Unicode</var> valued function, and so Unicode comparisons are used. | |||
<p class="code">%hit is namedArraylist of string len 30 | |||
%hit = new | |||
%hit('Clapton') = 'Layla' | |||
%hit('Davies') = 'All Day and All of the Night' | |||
%hit('Simon') = '50 Ways to Leave Your Lover' | |||
%hit = %hit:subsetNew(LE(this, '51')) | |||
%hit:print | |||
%unicHit is namedArraylist of unicode | |||
%unicHit = new | |||
%unicHit('Clapton') = 'Layla' | |||
%unicHit('Davies') = 'All Day and All of the Night' | |||
%unicHit('Simon') = '50 Ways to Leave Your Lover' | |||
%unicHit = %unicHit:subsetNew(LE(this, '51')) | |||
%unicHit:print | |||
</p> | |||
The result is: | |||
<p class="output">1: Clapton: Layla | |||
2: Davies: All Day and All of the Night | |||
3: Simon: 50 Ways to Leave Your Lover | |||
1: Simon: 50 Ways to Leave Your Lover | |||
</p> | |||
In an EBCDIC comparison, letters (here, <code>L</code> and <code>A</code>) are less then numeric digits (here, <code>5</code>); in a Unicode comparison, (Latin) letters are greater than numeric digits. | |||
</ol> | </ol> | ||
==See also== | |||
{{Template:SelectionCriterion:Eq, Ne, Ge, Gt, Le and Lt footer}} | |||
[[Category:SelectionCriterion methods]] |
Latest revision as of 21:34, 13 August 2012
Create selection expression based on comparison operator (SelectionCriterion class)
These shared methods each create a new SelectionCriterion object
that is a relational expression used to select items from a collection.
Each of these constructors provides a different comparison operator.
The Eq method, for example, constructs an equality expression that
selects a collection item if the expression is true for that item.
The other methods construct, respectively, not-equal-to, greater-than-or-equal-to,
greater-than, less-than-or-equal-to, or less-than expressions.
The first of the two parameters in a selection criterion specifies a function
that is applied to a collection item.
The function result is the "left-side" operand in the criterion's expression.
The second selection criterion parameter is a string or numeric that is
the "right-side" operand in the expression.
Eq(name, 'Ortiz')
specifies the expression name='Ortiz'
.
The function parameter of one of these methods might simply be an identity function that returns the item value. Or, for example, it might be a function that returns the value of a class member for an item that is an object. This function must be a method that operates on the item type and returns a User Language intrinsic datatype (Float, String, or Unicode) value.
Syntax
%selectionCriterion = [%(SelectionCriterion For itemType):]Eq( itemFunctionEnum, - result)
%selectionCriterion = [%(SelectionCriterion For itemType):]Ne( itemFunctionEnum, - result)
%selectionCriterion = [%(SelectionCriterion For itemType):]Ge( itemFunction, - %output)
%selectionCriterion = [%(SelectionCriterion For itemType):]Gt( itemFunction, - %output)
%selectionCriterion = [%(SelectionCriterion For itemType):]Le( itemFunction, - %output)
%selectionCriterion = [%(SelectionCriterion For itemType):]Lt( itemFunction, - %output)
Syntax terms
%selectionCriterion | A SelectionCriterion object variable to contain the new object instance. |
---|---|
[%(SelectionCriterion For itemType):] | For a shared function, this optional specification of the class in parentheses denotes a virtual constructor. See "Usage notes", below, for more information about invoking a SelectionCriterion virtual constructor. |
itemFunctionEnum | A method value (a method name literal, a method variable, a class Variable, or even a method that returns a method value) for a method that operates on objects of the type specified on the declaration of the collection being searched, and that returns a User Language intrinsic (String, Float, or Unicode) value. The returned type determines the type of comparison used to determine if an item satisfies the criterion. See Example 3 below.
For the Eq and Ne methods only, the return value of this argument's function may also be an enumeration value, as of Sirius Mods Version 7.8. See Example 1 below. |
result | An intrinsic value or expression, or an enumeration value (allowed for Eq and Ne only). |
Usage notes
- As described in "Virtual Constructor methods", Eq and the rest of these functions can be invoked with
no method object, with an explicit class specification, or with an object variable of the class,
even if that object is Null:
%selCrit = Eq(itemFunctionEnum, result) %selCrit = %(SelectionCriterion for float):LE(itemFunctionEnum, result) %selCrit = %selCrit:Gt(itemFunctionEnum, result)
Note: As shown in the second of these above, if you explicitly specify the class name, you must include the item datatype of the collection to be searched, just as on a SelectionCriterion object variable's declaration.
- For more information about the itemFunctionEnum parameter, see "Specifying a SelectionCriterion's parameters".
- The itemFunctionEnum parameter is a method value, not a User Language expression, and you may not specify a function that itself has an argument. The SelectionCriterion syntax does not provide for specifying a parameter for the itemFunctionEnum parameter. If necessary, the workaround for this restriction is to define a local method that accepts an argument, then use that method as the itemFunctionEnum parameter.
- The itemFunctionEnum may be This, an identity method that is valid for User Language intrinsic method objects only. The This method returns the value of the item to which it is applied. This example on the "SelectionCriterion class" page uses This.
- If itemFunctionEnum is an enumeration, null values are not a problem. But the Eq and Ne methods handle nulls differently: for example,
Eq(foo, true)
does not match an item with a null value offoo
, butNe(foo, false)
does.
Examples
- The following criterion matches a number greater than 10:
%sel = gt(this, 10)
The following matches a number with an absolute value less than or equal to 100:
%sel = le(absolute, 100)
The following matches items whose
reserve
return value is a Boolean True:%sel = eq(reserve, true)
The following matches numbers less than 70 and greater than or equal to 95:
%sel = or(lt(this,70), ge(this,95))
- The following request fragment selects two items from
the %fool NamedArraylist in the SubsetNew example:
... %sel is object selectionCriterion for object foo %sel = EQ(status, 'employed') %fool = %fool:subsetNew(%sel) for %i from 1 to %fool:count print %fool:namebynumber(%i) And - %fool:itembyNumber(%i):myprint end for ...
The result is:
Jan Green employed (income: 55000) Jim Red employed (income: 45000)
- In the following fragment, two nearly identical SubsetNew calls are used. The first uses a SelectionCriterion whose first argument (
this
) is a String valued function, and so EBCDIC comparisons are used. The second uses a SelectionCriterion whose first argument (this
) is a Unicode valued function, and so Unicode comparisons are used.%hit is namedArraylist of string len 30 %hit = new %hit('Clapton') = 'Layla' %hit('Davies') = 'All Day and All of the Night' %hit('Simon') = '50 Ways to Leave Your Lover' %hit = %hit:subsetNew(LE(this, '51')) %hit:print %unicHit is namedArraylist of unicode %unicHit = new %unicHit('Clapton') = 'Layla' %unicHit('Davies') = 'All Day and All of the Night' %unicHit('Simon') = '50 Ways to Leave Your Lover' %unicHit = %unicHit:subsetNew(LE(this, '51')) %unicHit:print
The result is:
1: Clapton: Layla 2: Davies: All Day and All of the Night 3: Simon: 50 Ways to Leave Your Lover 1: Simon: 50 Ways to Leave Your Lover
In an EBCDIC comparison, letters (here,
L
andA
) are less then numeric digits (here,5
); in a Unicode comparison, (Latin) letters are greater than numeric digits.