IsNull and IsNotNull (SelectionCriterion functions)

Create selection expression that provides

IsNull and IsNotNull are members of the SelectionCriterion class.

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

  %selc = [%(selectionCriterion for itemtype):] IsNull

  %selc = [%(selectionCriterion for itemtype):] IsNotNull

Syntax terms

%selc

A SelectionCriterion object variable to contain the new object instance.

%(selectionCriterion for itemtype)

This optional specification of the class and collection item type in parentheses indicates that the method is shared and does not operate on a specific instance.

criterion

A SelectionCriterion object specification.

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 collections 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