IsNull and IsNotNull (SelectionCriterion functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 21: Line 21:
<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><var>%(SelectionCriterion For</var> itemtype)</th>
<tr><th><var>%(SelectionCriterion For</var> itemtype)</th>
<td>This optional specification of the class in parentheses indicates that the method is 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 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>
</table>
</table>



Revision as of 20:39, 28 July 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 indicates that the method is 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: %(selectionCriterion For itemtype):

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