IsNull and IsNotNull (SelectionCriterion functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(10 intermediate revisions by 2 users not shown)
Line 20: Line 20:
<tr><th>%selectionCriterion</th>
<tr><th>%selectionCriterion</th>
<td>A <var>SelectionCriterion</var> object variable to contain the new object instance. </td></tr>
<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>
<tr><th nowrap="true"><var>[%(SelectionCriterion For </var>itemType<var>):]</var>
<td>This optional specification of the class in parentheses indicates that the method is [[Notation conventions for methods#Shared methods|shared]] and does not operate on a specific instance. If you use this option, however, you must include the collection item type to which the selection expression will be applied, like this: <code>%(selectionCriterion For <i>itemtype</i>):</code> </td></tr>
<td>This optional specification of the class in parentheses denotes a [[Notation conventions for methods#Constructors|virtual constructor]]. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a <var>SelectionCriterion</var> virtual constructor.
</td></tr>
</table>
</table>


==Usage notes==
<ul>
<li>As described in [[Object variables#Virtual Constructor methods|"Virtual Constructor methods"]], <var>IsNull</var> and <var>IsNotNull</var> 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 = IsNull
%selCrit = %(SelectionCriterion for float):IsNotNull
%selCrit = %selCrit:IsNull
</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]].
</ul>
==Examples==
==Examples==



Latest revision as of 21:12, 30 November 2011

Create selection expression that provides control for Null objects (SelectionCriterion class)

[Introduced in Sirius Mods 7.8]


These shared methods take no parameters and create a new SelectionCriterion object. The methods provide control for Null objects in the collection you are searching. They also let you determine whether a collection contains items that are objects, because they cancel the request if the collection being searched contains non-object (intrinsic type) items.

An IsNull criterion returns true for a collection item if the item is a Null object; an IsNotNull criterion returns true for item objects that are not Null.

These methods are available as of Sirius Mods version 7.8.

Syntax

%selectionCriterion = [%(SelectionCriterion For itemType):]IsNull

%selectionCriterion = [%(SelectionCriterion For itemType):]IsNotNull

Syntax terms

%selectionCriterion A SelectionCriterion object variable to contain the new object instance.
[%(SelectionCriterion For itemType):] 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.

Usage notes

  • As described in "Virtual Constructor methods", IsNull and IsNotNull 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 = IsNull %selCrit = %(SelectionCriterion for float):IsNotNull %selCrit = %selCrit:IsNull

    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.

Examples

The examples below test a variety of searches against arraylist %al of objects of class T:

class T public variable x is float end public end class %al is arraylist of object t %t is object t %t1 is object t %t2 is object t %t1 = null %t2 = new %al = list(%t1, %t2)

  1. The FindNextItem Arraylist function (or FindNextItem in other collection classes), which throws an exception if its selection criterion matches no item, fails in the Try clause below when it tests the Null object item. The method's exception is not thrown because the test failure prevents the method from completing its search:

    try %t = %al:findNextItem(EQ(x,1)) printtext found t printtext {~} = {%t:x} catch itemNotFound printText None! end try

    The result is:

    CANCELLING REQUEST: MSIR.0750: Class ARRAYLIST, function FindNextItem: reference to null object in line xx

    To complete this request without cancellation, you can use an IsNotNull criterion to bypass Null items:

    try %t = %al:findNextItem(AND(isNotNull, eq(x,1))) printtext found t printtext {~} = {%t:x} catch itemNotFound printText None! end try

    The search finds no matching items, so the Catch clause above catches the method's ItemNotFound exception, and the result is:

    None!

  2. Instead of bypassing Null items, you might instead want the search to include them:

    try %t = %al:findNextItem(OR(isNull, eq(x,1))) printtext found t printtext {~} = {%t:x} catch itemNotFound printText None! end try

    The Null item is found, but the Try clause PrintText invocation of %t:x fails, and the result is:

    CANCELLING REQUEST: MSIR.0561: Text output: reference to null object in line xx

    If you want to search exclusively for the next Null item in a collection, you can simply use this:

    %t = %al:findNextItem(isNull)

  3. To successfully locate the non-Null item in %al, you could use either of the following method calls in the Try clause:

    %t = %al:findNextItem(isNotNull) %t = %al:findNextItem(AND(isNotNull, eq(x,0)))

    Thanks to the change in the Eq criterion in the second call above, the result of trying either of these searches is:

    found t %t:x=0

See also