Janus SOAP ULI V7.8 changes: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 192: Line 192:
   
   
==New SelectionCriterion methods: IsNull and IsNotNull==
==New SelectionCriterion methods: IsNull and IsNotNull==
These shared methods take no parameters and create a new [[SelectionCriterion class|SelectionCriterion]] object.
These shared methods take no parameters and create a new <var>[[SelectionCriterion class|SelectionCriterion]]</var> object.
The methods provide control for Null objects in the [[Collections|collection]] you are searching.
The methods provide control for Null objects in the [[Collections|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,
Line 202: Line 202:
   
   
The syntax of the methods follows:
The syntax of the methods follows:
{{Template:SelectionCriterion:IsNull syntax}}
{{Template:SelectionCriterion:IsNull syntax}}
{{Template:SelectionCriterion:IsNotNull syntax}}
{{Template:SelectionCriterion:IsNotNull syntax}}
Line 224: Line 223:
</p>
</p>
<ol>
<ol>
<li>The <var>Arraylist</var> class <var>[[FindNextItem (ArrayList function)|FindNextItem]]</var> method, which throws an exception if its selection criterion
<li>The <var>Arraylist</var> class <var>[[FindNextItem (Arraylist function)|FindNextItem]]</var> method, which throws an exception if its selection criterion
matches no item, fails in the <var>Try</var> clause below when it tests the Null object item.
matches no item, fails in the <var>Try</var> clause below when it tests the Null 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
Line 289: Line 288:
==New intrinsic Float methods: ToDegrees and ToRadians==
==New intrinsic Float methods: ToDegrees and ToRadians==
===ToDegrees===
===ToDegrees===
This [[Float class|Float]] function converts to angular degrees its floating point argument which is a number of radians.
This <var>[[Float class|Float]]</var> function converts to angular degrees its floating point argument which is a number of radians.
   
   
The syntax of ToDegrees is:
The syntax of <var>ToDegrees</var> is:
{{Template:Float:ToDegrees syntax}}
  %deg = number:toDegrees
Where:
<table class="syntaxTable">
where:
<tr><th>%number</th>
<td>A variable to contain the number of degrees of the method object.</td></tr>
''%deg'' is a variable to contain the number of degrees of the method object.
<tr><th>float</th>
<td>A Float (datatype) value that is the number of radians.</td></tr>
''number'' is a Float value that is the number of radians.
</table>
The following example shows the result of several <var>ToDegrees</var> calls:
The following example shows the result of several ToDegrees calls:
<p class="code">begin
  begin
printText {~} = {1:toDegrees}
  printText {~} = {1:toDegrees}
printText {~} = {0:toDegrees}
  printText {~} = {0:toDegrees}
printText {~} = {0.1:toDegrees}
  printText {~} = {0.1:toDegrees}
printText {~} = {-0.1:toDegrees}
  printText {~} = {-0.1:toDegrees}
printText {~} = {3.1415926:toDegrees}
  printText {~} = {3.1415926:toDegrees}
printText {~} = {$pi:toDegrees}
  printText {~} = {$pi:toDegrees}
end
  end
</p>
   
   
The result is:
The result is:
<p class="code">1:toDegrees = 57.2957795130823
  1:toDegrees = 57.2957795130823
0:toDegrees = 0
  0:toDegrees = 0
0.1:toDegrees = 5.72957795130823
  0.1:toDegrees = 5.72957795130823
-0.1:toDegrees = -5.72957795130823
  -0.1:toDegrees = -5.72957795130823
3.1415926:toDegrees = 179.999996929531
  3.1415926:toDegrees = 179.999996929531
$pi:toDegrees = 180
  $pi:toDegrees = 180
</p>
===ToRadians===
===ToRadians===
This Float function converts to radians its floating point argument which is a number of angular degrees.
This <var>Float</var> function converts to radians its floating point argument which is a number of angular degrees.
   
   
The syntax of ToRadians is:
The syntax of <var>ToRadians</var> is:
{{Template:Float:ToRadians syntax}}
  %rad = number:toRadians
Where:
<table class="syntaxTable">
where:
<tr><th>%number</th>
<td>A variable to contain the number of radians of the method object.</td></tr>
''%rad'' is a variable to contain the number of radians of the method object.
<tr><th>float</th>
<td>A <var>Float</var> value that is the number of degrees.</td></tr>
''number'' is a Float value that is the number of degrees.
</table>
The following example shows the result of several <var>ToRadians</var> calls:
The following example shows the result of several ToRadians calls:
<p class="code">begin
  begin
printText {~} = {57:toRadians}
  printText {~} = {57:toRadians}
printText {~} = {0:toRadians}
  printText {~} = {0:toRadians}
printText {~} = {120:toRadians}
  printText {~} = {120:toRadians}
printText {~} = {-120:toRadians}
  printText {~} = {-120:toRadians}
printText {~} = {360:toRadians}
  printText {~} = {360:toRadians}
end
  end
</p>
   
   
The result is:
The result is:
<p class="output">57:toRadians = 0.994837673636768
  57:toRadians = 0.994837673636768
0:toRadians = 0
  0:toRadians = 0
120:toRadians = 2.0943951023932
  120:toRadians = 2.0943951023932
-120:toRadians = -2.0943951023932
  -120:toRadians = -2.0943951023932
360:toRadians = 6.28318530717959
  360:toRadians = 6.28318530717959
</p>
   
   
==New Collection methods==
==New Collection methods==
Seven new methods are added to each of the [[collection classes]] in <var class="product>Sirius Mods</var> Version 7.8.
Seven new methods are added to each of the [[Collections|collection classes]]
in <var class="product>Sirius Mods</var> Version 7.8.
   
   
===The Sum, Average, Variance, and StandardDeviation methods===
===The Sum, Average, Variance, and StandardDeviation methods===
Line 357: Line 356:
These functions have the same syntax and perform mathematical operations:
These functions have the same syntax and perform mathematical operations:
   
   
<dl>
<table>
<dt>Sum
<tr><th>Sum
<dd>Returns the simple sum of the values of the items in the collection.
</th><td>Returns the simple sum of the values of the items in the collection.
<dt>Average
</td></tr>
<dd>Returns the average of the values of the items in the collection.
<tr><th>Average
<dt>Variance
</th><td>Returns the average of the values of the items in the collection.
<dd>Returns the "mean standard deviation" of the values of the items in the collection.
</td></tr>
From statistics, this is the average of the squares of the deviations of the
<tr><th>Variance
value of each item from the mean of all the items.
</th><td>Returns the "mean standard deviation" of the values of the items in the collection. From statistics, this is the average of the squares of the deviations of the value of each item from the mean of all the items.
<dt>StandardDeviation
</td></tr>
<dd>Returns the standard deviation, the variation from the mean, of the values of the items in the collection. This is the square root of the collection's variance.
<tr><th>StandardDeviation
</dl>
</th><td>Returns the standard deviation, the variation from the mean, of the values of the items in the collection. This is the square root of the collection's variance.
</td></tr></table>
Here is an example:
Here is an example:
<p class="code">b
%al is arrayList of float
   
   
  b
%al = new
  %al is arrayList of float
%al:add(5)
%al:add(3)
  %al = new
%al:add(8)
  %al:add(5)
  %al:add(3)
  %al:add(8)
  print %al:sum
  print %al:average
  print %al:variance
  print %al:standardDeviation
  end
   
   
print %al:sum
print %al:average
print %al:variance
print %al:standardDeviation
end
</p>
The result is:
The result is:
<p class="code">16
  16
5.33333333333333
  5.33333333333333
4.22222222222222
  4.22222222222222
2.05480466765633
  2.05480466765633
</p>
The syntax of the methods is:
The syntax of the methods is:
  %num = %collectionType:methodName( [function] )
<p class="code">%num = %collectionType:methodName( [method] )
</p>
Where:
Where:
<table class=syntaxTable">
''%num'' is a float variable to contain the numeric result.
<tr><th>%num</th>
<td>A <var>Float</var> variable to contain the numeric result.</td></tr>
''%collectionType'' is an [[ArrayList class|ArrayList]], [[NamedArrayList class|NamedArrayList]], [[FloatNamedArrayList class|FloatNamedArrayList]],or [[UnicodeNamedArrayList  class|UnicodeNamedArrayList]] object variable.
<tr><th>%collectionType</th>
<td>An <var>[[Arraylist class|Arraylist]]</var>, <var>[[NamedArraylist class|NamedArraylist]]</var>, <var>[[FloatNamedArraylist class|FloatNamedArraylist]]</var>, or <var>[[UnicodeNamedArraylist class|UnicodeNamedArraylist]]</var> object variable.</td></tr>
''function'' is a function that operates on the type of
<tr><th>method</th>
the items in the collection. It may be a [[local method]] or [[method variable]] or a class
<td>A function that operates on the type of the items in the collection. It may be a
member (variable, property), and it must return an [[intrinsic]] (probably float) value. The
[[Local and Common entities#Defining and invoking a local method|local method]]
default ''function'' value is the special identity function, <tt>This</tt>, which simply returns the item value.
or [[Method variables|method variable]] or a class
member (<var>Variable</var>, <var>Property</var>), and it must return an
The optional ''function'' parameter lets you further manipulate the collection item values
[[Intrinsic classes|intrinsic]] (probably <var>Float</var>) value.
The default <var class="term">method</var> value is the special identity function, <var>This</var>, which simply returns the item value.</td></tr>
</table>
The optional <var class="term>method</var> parameter lets you further manipulate the collection item values
before performing the requested method's operation.
before performing the requested method's operation.
If your collection's items are not intrinsic
If your collection's items are not intrinsic
Line 413: Line 414:
   
   
For example, for a collection that is a list of coordinates, you could
For example, for a collection that is a list of coordinates, you could
return the average of their distance from the origin by first applying a local function as the Average method's ''function'' parameter:
return the average of their distance from the origin by first applying a local function as the <var>Average</var> method's <var class="term>method</var> parameter:
<p class="code">b
  b
class point
  class point
    public
      public
          constructor new(%x is float, %y is float)
          variable x is float
          variable y is float
      end public
       constructor new(%x is float, %y is float)
       constructor new(%x is float, %y is float)
          %this:x = %x
      variable x is float
          %this:y = %y
      variable y is float
      end constructor
    end public
  end class
   
   
  local function (point):distance is float
    constructor new(%x is float, %y is float)
      return (%this:x * %this:x + %this:y * %this:y):squareRoot
      %this:x = %x
  end function
      %this:y = %y
    end constructor
end class
   
   
   %al is arrayList of object point
local function (point):distance is float
   return (%this:x * %this:x + %this:y * %this:y):squareRoot
end function
   
   
  %al = new
%al is arrayList of object point
  %al:add(new(1,1))
  %al:add(new(3,4))
  %al:add(new(-5,12))
   
   
  print %al:average(distance)
%al = new
%al:add(new(1,1))
%al:add(new(3,4))
%al:add(new(-5,12))
   
   
  end
print %al:average(distance)
   
   
The result is <tt>6.47140452079103</tt>.
end
</p>
The result is <code>6.47140452079103</code>.
   
   
===The CountSubset method===
===The CountSubset method===
   
   
The CountSubset function returns the number of items in a collection that match a
The <var>CountSubset</var> function returns the number of items in a collection that match a
specified selection criterion. It is related to the SubsetNew collection mathod, which returns not the count but a collection of the matching items for a specified criterion.
specified selection criterion. It is related to the <var>SubsetNew</var> collection mathod, which returns not the count but a collection of the matching items for a specified criterion.
   
   
The syntax of the method is:
The syntax of the method is:
  %num = %collectionType:CountSubset( criterion )
<p class="syntax">%num = %collectionType:CountSubset( criterion )
</p>
Where:
Where:
<table class="syntaxTable">
''%num'' is a float variable to contain the numeric result.
<tr><th>%num</th>
<td>A float variable to contain the numeric result.</td></tr>
''%collectionType'' is an ArrayList, NamedArrayList, FloatNamedArrayList,or UnicodeNamedArrayList object variable.
<tr><th>%collectionType</th>
<td>An ArrayList, NamedArrayList, FloatNamedArrayList,or UnicodeNamedArrayList object variable.</td></tr>
''criterion'' is a [[SelectionCriterion]] object, which is a relational expression that is
<tr><th>criterion</th>
applied to each collection item value to determine whether the value satisfies the expression. This is a required parameter.
<td>A [[SelectionCriterion]] object, which is a relational expression that is applied to each collection item value to determine whether the value satisfies the expression. This is a required parameter.</td></tr>
</table>
As a simple example, for the ArrayList whose items are the odd integers between 0 and 10, and the selection criterion <tt>LT(this, 9))</tt>, CountSubset returns <tt>4</tt>.
As a simple example, for the <var>ArrayList</var> whose items are the odd integers between 0 and 10, and the selection criterion <code>LT(this, 9))</code>, CountSubset returns <code>4</code>.
   
   
===The MinItem and MaxItem methods===
===The MinItem and MaxItem methods===

Revision as of 00:42, 23 February 2011

{{#hierarchy-top:}}

The following sections describe changes in the Janus SOAPULI in this release.

New arguments for Record class ToXmlDoc method

The ToXmlDoc method in the Record class has the following new arguments:

CodepageTable= bool This Boolean argument, which defaults to False, specifies whether to use the base codepage translation table when creating the XmlDoc. For more details, see the description of the CodepageTable argument in LoadFromRecord.

Note that this argument was actually introduced in version 7.6 of the Sirius Mods.

AllowNull= bool The value of this Boolean argument, which defaults to False, is copied to the AllowNull property of the XmlDoc created by ToXmlDoc. The XmlDoc's AllowNull property, in turn, determines whether field values that contain the X'00' character are stored in the XmlDoc with base64 encoding. Such values are base64 encoded if AllowNull is False.

For more information, see the description of the AllowNull= argument in NewFromRecord.

Note that this argument was actually introduced in version 7.7 of the Sirius Mods.

Field references in Record class CurrentRecord methods

For methods declared with a CurrentRecord attribute, it was the case under Sirius Mods 7.7 that field references were an exception to the following rule:
Statements within the method definition, even a CurrentRecord method call, may reference the record without having to be wrapped inside a record For loop.

Under Sirius Mods 7.8, field references are no longer an exception to this rule. You may reference a record field from within a method declared with CurrentRecord without being inside a record For loop.

For example, for the field COLOR, the For Record currentRecord and End For statements containing the print COLOR statement in the method definition below may be discarded under Sirius Mods 7.8:

local subroutine (Record in file myproc):printField currentRecord in file myproc for record currentRecord print COLOR end for end subroutine

New exception class: BadJournal

The BadJournal exception class reports errors in CCAJRNL or CCAJLOG datasets or streams, including naming errors. The New method of the Journal system class is the system method that automatically throws a BadJournal exception.

The following example shows a Try and Catch of a Journal class, New method, exception. An invalid journal name is specified to generate the BadJournal exception:

    Begin
 
    %sl        is object stringlist
    %rc        is float
    %journal   is object journal
    %bdjrnl    is object BadJournal
 
    try printtext {~} is: {%journal = new('OLD~RNL')}
      catch BadJournal to %bdjrnl
      Print 'Failure!!! Reason code is: ' %bdjrnl:reasonCode
    end try
 
    %rc = %sl:appendJournalData( -
              Options='MAXIO=1000 WIDTH=138 ST AA USER', -
              Threads='*', Journal=%journal)
    Print %rc
    Print %sl:count
    %sl:print
 
    End

The Stringlist AppendJournalData method does not cancel if its Journal parameter is null. The request result shows the reason code (ReasonCode property value) stored in the exception object:

    %journal = new('OLD~RNL') is: Failure!!! Reason code is: 1
    0
    0

The methods of the BadJournal class are described in the following subsections.

New constructor

This constructor generates an instance of a BadJournal exception. As shown below, the optional argument of the New method is a setting of the ReasonCode property.

New constructor syntax

  [%bdJrnl =] [%(BadJournal):] New(ReasonCode=num)

ReasonCode property

This readOnly property returns a numeric reason code that indicates the cause of the BadJournal exception.

ReasonCode syntax

  %rc = %bdJrnl:ReasonCode

Possible reason codes are:

1 Either the dataset or stream name is invalid, or the journal is invalid.
2 The dataset or stream is empty.
3 The journal was created with a different Model 204 version than the current Online.
4 A merged journal is invalid.

Enhancement to exception handling: Success blocks

Exception Try/Catch support is enhanced in Version 7.8 by the addition of Success blocks. In cases where a Try block contains multiple statements, a Success block makes it clear in the code which statement is expected to produce the exceptions that are being caught. They also protect you from an inadvertent exception thrown in an unexpected context.

For example, consider the following scenario. You want to try statement <a> and, if no exceptions get Thrown, you want to do statements <b>, <c>, <d>, <e>, and <f>. Otherwise, if statement <a> throws an exception, you want to do statements <x>, <y>, or <z>, depending on the exception.

You code your Try/Catch block like this:

try <a> <b> <c> <d> <e> <f> catch foo <x> catch bar <y> catch whatever <z> end try

If statement <a> does indeed throw an exception, statements <b> through <f> do not run, and the appropriate Catch statement takes affect. However, if statement <a> does not throw an exception, there might be no way to know that statement <b>, <c>, <d>, <e>, or <f> might throw an exception that is one of the exceptions in the subsequent Catch statements. Or you might be aware of their capacity to do so, but you might not expect an exception from any of them in this context. Prior to Version 7.8 of the Sirius Mods, there was no good way of preventing the catches to also be in effect for these statements as well as for statement <a>.

As of Sirius Mods 7.8, a Success block inside the Try block resolves the problem by making it clear that the Catch statements do not apply to statements <b>, <c>, <d>, <e>,and <f>:

try <a> success <b> <c> <d> <e> <f> catch foo <x> catch bar <y> catch whatever <z> end try

A Success block may come before or after the Catch blocks:

try <a> catch foo <x> catch bar <y> catch whatever <z> success <b> <c> <d> <e> <f> end try

New SelectionCriterion methods: IsNull and IsNotNull

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 selects a collection item if the item is a Null object; an IsNotNull criterion selects an item object if it is not Null.

The syntax of the methods follows:

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

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

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 Arraylist class FindNextItem method, 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

New intrinsic Float methods: ToDegrees and ToRadians

ToDegrees

This Float function converts to angular degrees its floating point argument which is a number of radians.

The syntax of ToDegrees is:

%number = float:ToDegrees

Where:

%number A variable to contain the number of degrees of the method object.
float A Float (datatype) value that is the number of radians.

The following example shows the result of several ToDegrees calls:

begin printText {~} = {1:toDegrees} printText {~} = {0:toDegrees} printText {~} = {0.1:toDegrees} printText {~} = {-0.1:toDegrees} printText {~} = {3.1415926:toDegrees} printText {~} = {$pi:toDegrees} end

The result is:

1:toDegrees = 57.2957795130823 0:toDegrees = 0 0.1:toDegrees = 5.72957795130823 -0.1:toDegrees = -5.72957795130823 3.1415926:toDegrees = 179.999996929531 $pi:toDegrees = 180

ToRadians

This Float function converts to radians its floating point argument which is a number of angular degrees.

The syntax of ToRadians is:

%number = float:ToRadians

Where:

%number A variable to contain the number of radians of the method object.
float A Float value that is the number of degrees.

The following example shows the result of several ToRadians calls:

begin printText {~} = {57:toRadians} printText {~} = {0:toRadians} printText {~} = {120:toRadians} printText {~} = {-120:toRadians} printText {~} = {360:toRadians} end

The result is:

57:toRadians = 0.994837673636768 0:toRadians = 0 120:toRadians = 2.0943951023932 -120:toRadians = -2.0943951023932 360:toRadians = 6.28318530717959

New Collection methods

Seven new methods are added to each of the collection classes in Sirius Mods Version 7.8.

The Sum, Average, Variance, and StandardDeviation methods

These functions have the same syntax and perform mathematical operations:

Sum Returns the simple sum of the values of the items in the collection.
Average Returns the average of the values of the items in the collection.
Variance Returns the "mean standard deviation" of the values of the items in the collection. From statistics, this is the average of the squares of the deviations of the value of each item from the mean of all the items.
StandardDeviation Returns the standard deviation, the variation from the mean, of the values of the items in the collection. This is the square root of the collection's variance.

Here is an example:

b %al is arrayList of float %al = new %al:add(5) %al:add(3) %al:add(8) print %al:sum print %al:average print %al:variance print %al:standardDeviation end

The result is:

16 5.33333333333333 4.22222222222222 2.05480466765633

The syntax of the methods is:

%num = %collectionType:methodName( [method] )

Where:

%num A Float variable to contain the numeric result.
%collectionType An Arraylist, NamedArraylist, FloatNamedArraylist, or UnicodeNamedArraylist object variable.
method A function that operates on the type of the items in the collection. It may be a

local method or method variable or a class member (Variable, Property), and it must return an intrinsic (probably Float) value.

The default method value is the special identity function, This, which simply returns the item value.

The optional method parameter lets you further manipulate the collection item values before performing the requested method's operation. If your collection's items are not intrinsic values, you must specify a function that can map the item values to intrinsic values or the method will fail.

For example, for a collection that is a list of coordinates, you could return the average of their distance from the origin by first applying a local function as the Average method's method parameter:

b class point public constructor new(%x is float, %y is float) variable x is float variable y is float end public constructor new(%x is float, %y is float) %this:x = %x %this:y = %y end constructor end class local function (point):distance is float return (%this:x * %this:x + %this:y * %this:y):squareRoot end function %al is arrayList of object point %al = new %al:add(new(1,1)) %al:add(new(3,4)) %al:add(new(-5,12)) print %al:average(distance) end

The result is 6.47140452079103.

The CountSubset method

The CountSubset function returns the number of items in a collection that match a specified selection criterion. It is related to the SubsetNew collection mathod, which returns not the count but a collection of the matching items for a specified criterion.

The syntax of the method is:

%num = %collectionType:CountSubset( criterion )

Where:

%num A float variable to contain the numeric result.
%collectionType An ArrayList, NamedArrayList, FloatNamedArrayList,or UnicodeNamedArrayList object variable.
criterion A SelectionCriterion object, which is a relational expression that is applied to each collection item value to determine whether the value satisfies the expression. This is a required parameter.

As a simple example, for the ArrayList whose items are the odd integers between 0 and 10, and the selection criterion LT(this, 9)), CountSubset returns 4.

The MinItem and MaxItem methods

The MinItem and MaxItem functions return the minimum and maximum values in a collection. They are related to the Minimum and Maximum collection methods, which return the number or name of the item that has the minimum or maximum value in the collection.

The syntax of these methods is:

   %num = %collectionType:methodName( [function] )

Where:

%num is a float variable to contain the numeric result.

%collectionType is an ArrayList, NamedArrayList, FloatNamedArrayList,or UnicodeNamedArrayList object variable.

function is a function that operates on the type of the items in the collection. It may be a local method or method variable or a class member (variable, property), and it must return an intrinsic (probably float) value. The default function value is the special identity function, This, which simply returns the item value.

The optional function parameter lets you further manipulate the collection item values before performing the requested method's operation. If your collection's items are not intrinsic values, you must specify a function that can map the item values to intrinsic values or the method will fail.

For the ArrayList %al whose items are the odd integers between 0 and 10, %al:maxItem returns 9.

New StringTokenizer methods

Several new methods are added to the StringTokenizer class in Sirius Mods Version 7.8.

The Separators method

This readWrite property introduces another class of characters in the StringTokenizer to delimit, or separate, tokens. Prior to this version, only Spaces and TokenChars characters were available to separate tokens. The new Separators characters are similar to Spaces and TokenChars, but in addition to delimiting tokens, Separators characters:

  • do not compress to a single separator (like Spaces characters)
  • are not themselves tokens (like TokenChars characters), so are not returned by repeated NextToken calls that encounter consecutive Separators characters

The syntax of the method is:

%string = %tok:Separators %tok:Separators = %string

Where:

%string
A string variable to contain the returned value of the current separator characters or to be set as the new value(s). The default value for a new tokenizer instance is the null string. If you are setting Separators, each character in the separator string is a separator, and no character may repeat (except for apostrophe, which may be doubled).
%tok
A StringTokenizer object variable.

Separators provide a way to handle consecutive occurrences of the same token delimiter character, for example, in a comma-separated value (csv) file, where they indicate a missing value. As an example, the adjacent separators in the token string below are detected and returned as nulls by the NextToken method:

b %toke is object StringTokenizer %toke = new(separators=',;') %toke:string = '0,1,2,,4,;6' repeat while %toke:notAtEnd printtext {~} = '{%toke:nextToken}' end repeat end

The result is:

%toke:nextToken = '0' %toke:nextToken = '1' %toke:nextToken = '2' %toke:nextToken = '' %toke:nextToken = '4' %toke:nextToken = '' %toke:nextToken = '6'

Separators override default and explicitly defined Spaces characters. For example, if the only change to the example above is that the tokenizer string is "please, don't go", the result is:

%toke:nextToken = 'please' %toke:nextToken = 'don't go'

The blank after don't does not act as a token delimiter.

Note: Separators do not override explicitly defined TokenChars characters. If both separators and token characters are defined, all such characters act as token delimiters.

The CompressSpaces, FoldDoubledQuotes, and QuotesBreak methods

These readWrite properties all return or set a boolean value.

The CompressSpaces property

CompressSpaces compresses the intermediate spaces in a string of whitespace characters. For example, consider the following %toke StringTokenizer string, defined with a blank as the whitespace character and with comma as a non-token separator character:

this, is a compression , example

Without compression, repeated calls of %toke:NextToken strip the leading and trailing whitespace and select the following tokens:

this is a compression example

Without compression, that is, with CompressSpaces set to True, the result is:

this is a compression example

CompressSpaces compresses a token's intermediate whitespace to a single whitespace character. If multiple whitespace characters are defined, the first character in the Spaces string is the character to which intermediate whitespace is compressed. For example, if Spaces='X ', the token 'foot ball' will compress to 'footXball'.

The CompressSpaces default value is False.

Note: CompressSpaces affects processing only when one or more Separators characters are set, because otherwise a token cannot contain internal whitespace.

The FoldDoubledQuotes property

The practice of doubling an apostrophe ( ' ) to yield a single apostrophe is common in User Language Print statements. For example, the result of Print 'Please, don''t go' is:

Please, don't go

The doubled, or escaped, apostrophe is implicitly folded to a single apostrophe. Similarly, if double quotation marks instead of the apostrophes are used to indicate a quoted string (as is allowed as of Sirius Mods version 7.8): Print "Please, don""t go"

The result is

Please, don"t go

. The escaped double quotation mark is implicitly folded to one double quotation mark.

The StringTokenizer, however, does not perform this implicit folding if it encounters a doubled Quotes character within a quoted region. For example:

b %toke is object StringTokenizer %toke = new(quotes='"') %toke:string = '"Please, don""t go"' repeat while %toke:notAtEnd printtext {~} = '{%toke:nextToken}' end repeat end

The result of this request is:

%toke:nextToken = 'Please, don' %toke:nextToken = 't go'

To provide for cases where you might expect or want implicit folding of a doubled Quotes character, version 7.8 adds the FoldDoubledQuotes property to the StringTokenizer class. If the FoldDoubledQuotes property is set to True (this is not the default), the tokenizer considers two adjacent Quotes characters within a quoted region that is begun by the same Quotes character to be an escape sequence for a single quotation character, and the result of tokenizing %toke:string = '"Please, don""t go"' from the previous request is:

Please, don"t go

The syntax of the FoldDoubledQuotes method is:

%bool = %tok:FoldDoubledQuotes %tok:FoldDoubledQuotes = %bool

Where:

%bool
An enumeration object of type Boolean to contain or set the value of FoldDoubledQuotes. The default value for a new tokenizer instance is False.
%tok
A StringTokenizer object variable.

Aliases for class names

As of Sirius Mods Version 7.8, you can define an alias name for an existing user class. You do so by specifying an Alias parameter setting on the existing class declaration. For example, you are changing a naming convention for some code, and you want to refer to user-defined class Blue by another name, say Indigo. Your class declaration would be:

   class blue alias indigo

You can then use either the primary class name or the alias when declaring objects of the class:

    %foo     is object blue
    %bar     is object indigo

An object of the alias class is compiled as an object of the primary class, and the runtime class of an object variable that was defined using an alias is the primary class. Consequently, all system messages you receive will specify the primary class.

For example, given the declarations above, if you call method TouchUp for an object declared for the Indigo class:

    %bar:touchUp

And method TouchUp does not exist in the class, the error message you receive is:

    MSIR.0733: Member TOUCHUP not found in class Blue

While this might seem potentially confusing, aliases are intended primarily for migrating class names, so any confusion will be limited to this migration period. In addition, only the owner of a class can declare an alias, so aliases are not likely to proliferate in your site's code.

Should it ever be necessary, you may also specify multiple aliases:

   class blue alias indigo and ultramarine and navy

You may declare a user-defined class with an alias name that matches the name of a system class.

New common enumeration method: FromString

Sirius Mods Version 7.8 adds the FromString shared function as a method common to all system and user-defined enumerations. FromString converts a string argument into a value of the specified enumeration type. This is the opposite of an enumeration ToString method, which converts an enumeration value to its String representation.

As an example, consider the following user-defined enumeration:

  enumeration Animal
      public
        value cat
        value dog
        value gecko
        value parrot
      end public
  end enumeration

You can populate an Animal enumeration variable with one of the Animal enumeration values by making a call to FromString:

  %pet is enumeration animal
  %pet = fromString('gecko')

The result of a Print of %pet above is gecko. In the method call, fromString does not have to be preceded by %(Animal): to identify the type of enumeration, because the FromString method is automatically available for any User Language enumeration, system or user-defined.

Only strings that match a value of the particular enumeration type can be converted. If a string cannot be converted to an enumeration value, FromString throws an InvalidValue exception:

  %pet = fromString('alien')

  ***  1  CANCELLING REQUEST: MSIR.0750: Class Animal, function
  FromString: InvalidValue exception: ALIEN is not a valid enumeration
  value in line 84, procedure ENUM, file MYPROC

{{#hierarchy-bottom:}}