IsNull and IsNotNull (SelectionCriterion functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
Line 1: Line 1:
<span style="font-size:120%; color:black"><b>Create selection expression that provides</b></span>
{{Template:SelectionCriterion:IsNull and IsNotNull subtitle}}
[[Category:SelectionCriterion methods|IsNull and IsNotNull constructors]]
<!--DPL?? Category:SelectionCriterion methods|IsNull and IsNotNull constructors: Create selection expression that provides-->
<!--DPL?? Category:System methods|IsNull and IsNotNull (SelectionCriterion constructors): Create selection expression that provides-->
<p>
IsNull and IsNotNull are members of the [[SelectionCriterion class]].
</p>


These shared methods take no parameters and create a new SelectionCriterion object.
These shared methods take no parameters and create a new <var>SelectionCriterion</var> object.
The methods provide control for Null objects in the collection you are searching.
The methods provide control for <var>Null</var> objects in the collection you are searching.
They also let you determine whether a collection contains items that are objects,
They also let you determine whether a collection contains items that are objects,
because they cancel the request if the collection being searched contains
because they cancel the request if the collection being searched contains
non-object (intrinsic type) items.
non-object ([[Intrinsic classes#Two generic intrinsic classes: string and numeric|intrinsic type]]) items.


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


These methods are available as of ''Sirius Mods'' version 7.8.
These methods are available as of <var class="product">Sirius Mods</var> version 7.8.
===Syntax===
==Syntax==
  %selc = [%(selectionCriterion for itemtype):] IsNull
{{Template:SelectionCriterion:IsNull syntax}}
{{Template:SelectionCriterion:IsNotNull syntax}}


  %selc = [%(selectionCriterion for itemtype):] IsNotNull
===Syntax terms===
===Syntax terms===
<dl>
<table class="syntaxTable">
<dt><i>%selc</i>
<tr><th>%selectionCriterion</th>
<dd>A SelectionCriterion object variable to contain the new object instance.
<td>A <var>SelectionCriterion</var> object variable to contain the new object instance. </td></tr>
<dt><i>%(selectionCriterion for itemtype)</i>
<tr><th><var>%(SelectionCriterion For</var> itemtype)</th>
<dd>This optional specification of the class and collection item type
<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>
in parentheses indicates
</table>
that the method is shared and does not operate on a specific instance.
<dt><i>criterion</i>
<dd>A SelectionCriterion object specification.


</dl>
==Examples==
===Examples===


The examples below test a variety of searches against
The examples below test a variety of searches against
arraylist <tt>%al</tt> of objects of class <tt>T</tt>:
arraylist <code>%al</code> of objects of class <code>T</code>:
<pre>
<p class="code">class T
    class T
  public
      public
    variable x is float
        variable x is float
  end public
      end public
end class
    end class


    %al is arraylist of object t
%al is arraylist of object t
    %t  is object t
%t  is object t
    %t1 is object t
%t1 is object t
    %t2 is object t
%t2 is object t


    %t1 = null
%t1 = null
    %t2 = new
%t2 = new
    %al = list(%t1, %t2)
%al = list(%t1, %t2)
</pre>
</p>
<ol>
<ol>
<li>The [[FindNextItem (Arraylist function)|FindNextItem Arraylist function]] (or FindNextItem in other [[Collections|collections]] classes),
<li>The <var>[[FindNextItem (Arraylist function)|FindNextItem]]</var> <var>Arraylist</var> function (or <var>FindNextItem</var> in other [[Collections|collection]] classes),
which throws an exception if its selection criterion
which throws an exception if its selection criterion
matches no item, fails in the Try clause below when it tests the Null object item.
matches no item, fails in the <var>Try</var> clause below when it tests the <var>Null</var> object item.
The method's exception is not thrown because the test failure prevents the method
The method's exception is not thrown because the test failure prevents the method
from completing its search:
from completing its search:
<pre>
<p class="code">try  %t = %al:findNextItem(EQ(x,1))
    try  %t = %al:findNextItem(EQ(x,1))
  printtext found t
      printtext found t
  printtext {~} = {%t:x}
      printtext {~} = {%t:x}
catch itemNotFound
    catch itemNotFound
  printText None!
      printText None!
end try
    end try
</p>
</pre>


The result is:
The result is:
<pre>
<p class="code">CANCELLING REQUEST: MSIR.0750: Class ARRAYLIST, function
    CANCELLING REQUEST: MSIR.0750: Class ARRAYLIST, function
  FindNextItem: reference to null object in line xx
      FindNextItem: reference to null object in line xx
</p>
</pre>
To complete this request without cancellation,
To complete this request without cancellation,
you can use an IsNotNull criterion to bypass Null items:
you can use an <var>IsNotNull</var> criterion to bypass <var>Null</var> items:
<pre>
<p class="code">try  %t = %al:findNextItem(AND(isNotNull, eq(x,1)))
    try  %t = %al:findNextItem(AND(isNotNull, eq(x,1)))
  printtext found t
      printtext found t
  printtext {~} = {%t:x}
      printtext {~} = {%t:x}
catch itemNotFound
    catch itemNotFound
  printText None!
      printText None!
end try
    end try
</pre>
</pre>


The search finds no matching items, so the Catch clause above catches the
The search finds no matching items, so the <var>Catch</var> clause above catches the
method's ItemNotFound exception, and the result is:
method's <var>ItemNotFound</var> exception, and the result is:
<pre>
<p class="output">None!
    None!
</p>
</pre>
<li>Instead of bypassing <var>Null</var> items, you might instead want the search to
<li>Instead of bypassing Null items, you might instead want the search to
include them:
include them:
<pre>
<p class="code">try  %t = %al:findNextItem(OR(isNull, eq(x,1)))
    try  %t = %al:findNextItem(OR(isNull, eq(x,1)))
  printtext found t
      printtext found t
  printtext {~} = {%t:x}
      printtext {~} = {%t:x}
catch itemNotFound
    catch itemNotFound
  printText None!
      printText None!
end try
    end try
</p>
</pre>


The Null item is found, but the Try clause PrintText invocation
The <var>Null</var> item is found, but the <var>Try</var> clause <var>PrintText</var> invocation
of <tt>%t:x</tt> fails, and the result is:
of <code>%t:x</code> fails, and the result is:
<pre>
<p class="code">CANCELLING REQUEST: MSIR.0561: Text output:
    CANCELLING REQUEST: MSIR.0561: Text output:
  reference to null object in line xx
      reference to null object in line xx
</p>
</pre>


If you want to search exclusively for the next Null item in a collection,
If you want to search exclusively for the next <var>Null</var> item in a collection,
you can simply use this:
you can simply use this:
<pre>
<p class="code">%t = %al:findNextItem(isNull)
    %t = %al:findNextItem(isNull)
</p>
</pre>
<li>To successfully locate the non-<var>Null</var> item in <code>%al</code>,
<li>To successfully locate the non-Null item in <tt>%al</tt>,
you could use either of the following method calls in the <var>Try</var> clause:
you could use either of the following method calls in the Try clause:
<p class="code">%t = %al:findNextItem(isNotNull)
<pre>
    %t = %al:findNextItem(isNotNull)


    %t = %al:findNextItem(AND(isNotNull, eq(x,0)))
%t = %al:findNextItem(AND(isNotNull, eq(x,0)))
</pre>
</p>


Thanks to the change in the EQ criterion in the second call above,
Thanks to the change in the <var>Eq</var> criterion in the second call above,
the result of trying either of these searches is:
the result of trying either of these searches is:
<pre>
<p class="output">found t
    found t
%t:x=0
    %t:x=0
</p>
</pre>
</ol>
</ol>
==See also==
{{Template:SelectionCriterion:IsNull and IsNotNull footer}}

Revision as of 19:20, 24 June 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