IsNull and IsNotNull (SelectionCriterion functions)

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)]	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.

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

SelectionCriterion class	List of SelectionCriterion methods	SelectionCriterion methods syntax
Notation conventions for methods