Boolean enumeration: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (add "See also" section)
 
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
The '''Boolean''' enumeration implements the standard logical paradigm of "true" and "false".
The '''Boolean''' enumeration implements the standard logical paradigm of "true" and "false".


While, in some sense, it is just like any other enumeration, because the concept of true and false is so basic to programming, <var>Boolean</var> variables are treated specially by User Language.   
While, in some sense, it is just like any other enumeration, because the concept of true and false is so basic to programming, <var>Boolean</var> variables are treated specially by <var class="product">User Language</var>.   
 
==Boolean enumeration values==
==Boolean enumeration values==
The system <var>Boolean</var> enumeration values are:
The system <var>Boolean</var> enumeration values are:
Line 8: Line 9:
<li><b>False</b>
<li><b>False</b>
</ul>
</ul>
However, like all other enumerations, a <var>Boolean</var> variable can also be unset so have a null value. While this can be useful in detecting references to unset variables, it can also be problematic in certain sitiuations. Use of the <var>Initial</var> clause on variable declarations and the <var>Default</var> clause on method parameter declarations can mitigate most of these issues, nevertheless it is important to keep in mind the possibility of a <var>Boolean</var> variable being null.   
However, like all other [[Enumerations|enumerations]], a <var>Boolean</var> variable can also be unset so have a null value. While this can be useful in detecting references to unset variables, it can also be problematic in certain sitiuations. Use of the <var>Initial</var> clause on variable declarations and the <var>Default</var> clause on method parameter declarations can mitigate most of these issues, nevertheless it is important to keep in mind the possibility of a <var>Boolean</var> variable being null.   
 
==Declaring boolean variables==
==Declaring boolean variables==
Boolean variables can be declared the same way any enumeration variables are declared, with the keyword <var>Enumeration</var> followed by the class name:
<var>Boolean</var> variables can be declared the same way any enumeration variables are declared, with the keyword <var>Enumeration</var> followed by the class name:
<p class="code>%truth    is enumeration boolean
<p class="code">%truth    is enumeration boolean
</p>
</p>
However, because boolean processing is such a basic part of any programming language, <var>Boolean</var> variables can be declared without the <var>Enumeration</var> keyword:   
However, because boolean processing is such a basic part of any programming language, <var>Boolean</var> variables can be declared without the <var>Enumeration</var> keyword:   
<p class="code>%truth    is boolean
<p class="code">%truth    is boolean
</p>
</p>
This is also true for method variables and results. For example, then following:
This is also true for method variables and results. For example, the following:
<p class="code">function foo(%n is float, %test is enumeration boolean) -
<p class="code">function foo(%n is float, %test is enumeration boolean) is enumeration boolean
            is enumeration boolean
</p>
</p>
is identical to
is identical to:
<p class="code">function foo(%n is float, %test is boolean) is boolean
<p class="code">function foo(%n is float, %test is boolean) is boolean
</p>
</p>
==Using booleans in If conditions==
 
The whole point of <var>Boolean</var> variables is to be able to test them for truth and, depending on the result, perform some processing. For example, if <var>%bool</var> is a <var>Boolean</var> variable, the following performs the contents of the <var>If</var> block if <var>%bool</var> is set to <var>True</var>:
==Using Booleans in If conditions==
The whole point of <var>Boolean</var> variables is to be able to test them for truth and, depending on the result, perform some processing. For example, if <code>%bool</code> is a <var>Boolean</var> variable, the following statement performs the contents of the <var>If</var> block if <code>%bool</code> is set to <code>True</code>:
<p class="code">if %bool then
<p class="code">if %bool then
</p>
</p>
Note that in this example, if <var>%bool</var> is not set (null), then the request would be canceled with a null object reference error.
Note that in this example, if <code>%bool</code> is not set (null), then the request would be canceled with a null object reference error.
==Using logical operators with booleans==
 
User language has three logical operators:
==Using logical operators with Booleans==
<var class="product">User Language</var> has three logical operators:
<ul>
<ul>
<li>Not</li>
<li><var>Not</var></li>
<li>And</li>
<li><var>And</var></li>
<li>Or</li>
<li><var>Or</var></li>
</ul>
</ul>
Strictly speaking, in User Language these operators actually operate on numeric values where 0 is treated as <var>False</var> and any non-zero value is treated as <var>True</var>. However, because of the importance of boolean logic in programming, <var>Boolean</var> variables or values can be used instead of numbers for these operators. A boolean <var>True</var> is treated as 1 and a <var>False</var> value is treated as 0. As such, boolean variables can be used in logical operations as in:
Strictly speaking, in <var class="product">User Language</var> these operators actually operate on numeric values where <code>0</code> is treated as <code>False</code> and any non-zero value is treated as <code>True</code>. However, because of the importance of boolean logic in programming, <var>Boolean</var> variables or values can be used instead of numbers for these operators. A <var>Boolean</var> <var>True</var> is treated as <code>1</code> and a <var>False</var> is treated as <code>0</code>. As such, <var>Boolean</var> variables can be used in logical operations as in:
<p class="code">if not %bool then
<p class="code">if not %bool then
</p>
</p>
Line 41: Line 44:
<p class="code">if %bool and (%y gt %x) Then
<p class="code">if %bool and (%y gt %x) Then
</p>
</p>
==Automatic conversion of numbers to Boolean==
==Automatic conversion of numbers to Boolean==
In <var class="product">Sirius Mods 8.1</var> and later, it is also possible to assign a number to a <var>Boolean</var> variable. When this is done, the number 0 is converted to <var>False</var> and every other value is converted to <var>True</var>. This is especially useful for assigning the result of a comparison to a boolean:
In <var class="product">Sirius Mods 8.1</var> and later, it is also possible to assign a number to a <var>Boolean</var> variable. When this is done, the number 0 is converted to <var>False</var> and every other value is converted to <var>True</var>. This is especially useful for assigning the result of a comparison to a <var>Boolean</var>:
<p class="code">%bool = %x gt %y
<p class="code">%bool = %x gt %y
</p>
</p>
Line 51: Line 55:
</p>
</p>
Of course, some methods or $functions return a 0 indicating success and a non-zero value indicating an error. So, just as one can do:
Of course, some methods or $functions return a 0 indicating success and a non-zero value indicating an error. So, just as one can do:
<p class="code">if $setg(''NAME', %name) then
<p class="code">if $setg('NAME', %name) then
</p>
</p>
one can also assign the result of a method or $function to a <var>Boolean</var>:
one can also assign the result of a method or $function to a <var>Boolean</var>:
<p class="code">%setgSuccess is boolean
<p class="code">%setgSuccess is boolean
...
...
%setgSuccess = $setg(''NAME', %name)
%setgSuccess = $setg('NAME', %name)
</p>
</p>
One note of caution. Numbers are [[Intrinsic classes|intrinsic variables]] and, as such, string values are automatically converted to numbers. Any string that can't be converted to a number is treated as 0. So, if <code>%n</code> is declared as <var>Float</var>, the following:
One note of caution: Numbers are [[Intrinsic classes|intrinsic variables]] and, as such, string values are automatically converted to numbers. Any string that can't be converted to a number is treated as 0. So, if <code>%n</code> is declared as <code>Float</code>, the following:
<p class="code">%n = '1234.56'
<p class="code">%n = '1234.56'
</p>
</p>
Line 73: Line 77:
<p class="code">%bool = 'true'
<p class="code">%bool = 'true'
</p>
</p>
would result in <code>%bool</code> containing <code>False</code> because when <var>boolean</var>s are set from intrinsic variables, the intrinsic values are treated as numbers so 'true' was converted to the number <code>0</code> before being assigned to <code>%bool</code>.
would result in <code>%bool</code> containing <code>False</code> because when <var>boolean</var>s are set from intrinsic variables, the intrinsic values are treated as numbers, so <var>true</var> was converted to the number <code>0</code> before being assigned to <code>%bool</code>.


Of course, there really be no good reason to assign a string (or numeric) literal to a boolean. If one wanted to set a boolean variable to a literal value, one should simply specify the unquoted literal value as one does when setting any enumeration value:
Of course, there really be no good reason to assign a string (or numeric) literal to a <var>Boolean</var>. If you want to set a <var>Boolean</var> variable to a literal value, simply specify the unquoted literal value as you do when setting any enumeration value:
<p class="code">%bool = true
<p class="code">%bool = true
...
...
%bool = false
%bool = false
</p>
</p>
In the case where one has a string that contains either "True" or "False", on can use the standard enumeration <var>FromString</var> method to set the <var>Boolean</var> variable:
In the case where you have a string that contains either <code>True</code> or <code>False</code>, you can use the standard enumeration <var>FromString</var> method to set the <var>Boolean</var> variable:
<p class="code">%bool = %(boolean):fromString(%string)
<p class="code">%bool = %(boolean):fromString(%string)
</p>
</p>
If <code>%string</code> does not contain "True" or "False" (case independent) then an <var>InvalidValue</var> exception is thrown by <var>FromString</var>.
If <code>%string</code> does not contain "True" or "False" (case independent), <var>FromString</var> throws an <var>[[InvalidValue class|InvalidValue]]</var> exception.


===Limitations===
===Limitations===
Even in <var class="product">Sirius Mods 8.1</var> and later there are a few places where numbers are not automatically converted to booleans:
Even in <var class="product">Sirius Mods 8.1</var> and later, there are a few places where numbers are not automatically converted to booleans:
<ul>
<ul>
<li>As inputs to <var>Boolean</var> parameters to complex subroutines. Since complex subroutine can be called before they are declared, doing such automatic conversion would be very complex so is currently not supported. If the automatic conversion of numeric inputs to <var>Boolean</var> parameters is required for a complex subroutine, one option might be to try to convert the complex subroutine to a [[Local and Common entities|Common subroutine]].
<li>As inputs to <var>Boolean</var> parameters to complex subroutines.  
<li>As method objects to enhancement methods for the <var>Boolean</var> class. For example, if one had
<p>
Since complex subroutine can be called before they are declared, doing such automatic conversion would be very complex so is currently not supported. If the automatic conversion of numeric inputs to <var>Boolean</var> parameters is required for a complex subroutine, one option might be to try to convert the complex subroutine to a [[Local and Common entities|Common subroutine]].</p>
 
<li>As method objects to enhancement methods for the <var>Boolean</var> class.  
<p>
For example, given this declaration:</p>
<p class="code">local function (boolean):xor(%what is boolean) is boolean
<p class="code">local function (boolean):xor(%what is boolean) is boolean
</p>
</p>
the following would result in a compilation error because (%x gt %y) results in a numeric result but the enhancement method is defined as operating on booleans:
The following produces a compilation error, because <code>(%x gt %y)</code> results in a numeric result but the enhancement method is defined as operating on <var>Booleans</var>:
<p class="code">%bool = (%x gt %y):xor(%y gt %z)
<p class="code">%bool = (%x gt %y):xor(%y gt %z)
</p>
</p>
Fortunately, <var>Boolean</var> enhancement methods are few and far between, so this restriction is not likely to be a major problem.
Fortunately, <var>Boolean</var> enhancement methods are few and far between, so this restriction is not likely to be a major problem.
</ul>
</ul>
===Booleans not automatically converted to numbers===
===Booleans not automatically converted to numbers===
Finally, while in <var class="product">Sirius Mods 8.1</var> and later numeric values are automatically converted when assigned to a <var>Boolean</var> variable, the inverse is not true. For example, if <code>%number</code> is a <var>Float</var> variable and <code>%bool</code> is <var>Boolean</var>, the following will result in a compilation error:
While in <var class="product">Sirius Mods 8.1</var> and later, numeric values are automatically converted when assigned to a <var>Boolean</var> variable, the inverse is not true. For example, if <code>%number</code> is a <var>Float</var> variable and <code>%bool</code> is a <var>Boolean</var>, the following will result in a compilation error:
<p class="code">%number = %bool
<p class="code">%number = %bool
</p>
</p>
This also means that using arithmetic or string operators on boolean values is not allowed. So the following two statements would both result in compilation errors:
This also means that using arithmetic or string operators on <var>Boolean</var> values is not allowed. So the following two statements both result in compilation errors:
<p class="code">%number = %bool * %bool
<p class="code">%number = %bool * %bool
%string = %bool with %bool
%string = %bool with %bool
</p>
</p>
Fortunately, one would rarely need to do this and, if one does need to do this for some reason, the <var>IsTrue</var> and <var>ToString</var> methods provide a work-around:
Fortunately, one would rarely need to do this, and if one does need to do this for some reason, the <var>[[#IsTrue function|IsTrue]]</var> and <var>[[Enumerations#ToString_property|ToString]]</var> methods provide a workaround:
<p class="code">%number = %bool:isTrue * %bool:isTrue
<p class="code">%number = %bool:isTrue * %bool:isTrue
%string = %bool:toString with %bool:toString
%string = %bool:toString with %bool:toString
</p>
</p>
Because of this, to convert existing methods with <var>Float</var> parameter switches to use boolean switches, the migration should start by converting the parameter declaration to <var>Boolean</var>. This might require changing some of the code inside the method, but it is also likely that no code changes would be required. Once this is done, code that invokes the method can be modified to pass <var>Boolean</var> rather than <var>Float</var> values.
Because of this, to convert existing methods with <var>Float</var> parameter switches to use <var>Boolean</var> switches, the migration should start by converting the parameter declaration to <var>Boolean</var>. This might require changing some of the code inside the method, but it is also likely that no code changes would be required. Once this is done, code that invokes the method can be modified to pass <var>Boolean</var> rather than <var>Float</var> values.


For example, if one currently has a method defined as:
For example, if one currently has a method defined as:
Line 125: Line 135:
<p class="code">subroutine doSomething(%goAllOut is boolean nameRequired)
<p class="code">subroutine doSomething(%goAllOut is boolean nameRequired)
</p>
</p>
and everything should magically work (under <var class="product">Sirius Mods 8.1</var> and later). For example, the following method invocation would work because the numbers being passed for <code>goAllOut</code> would be automatically converted to boolean:
and everything works (under <var class="product">Sirius Mods 8.1</var> and later). For example, the following method invocation works because the numbers being passed for <code>goAllOut</code> are automatically converted to boolean:
<p class="code">%object:doSomething(goAllOut=1)
<p class="code">%object:doSomething(goAllOut=1)
...
...
%object:doSomething(goAllout=(%all eq 'Y'))
%object:doSomething(goAllout=(%all eq 'Y'))
</p>
</p>
Of course, once the change is made to the method definition, the first invocation above could be changed to:
Of course, once the change is made to the method definition, the first invocation above could be changed for better clarity to:
<p class="code">%object:doSomething(goAllOut=true)
<p class="code">%object:doSomething(goAllOut=true)
</p>
</p>
which is arguably clearer.


==Using booleans==  
==Using booleans==  
As stated at the outset of this page, <var>Boolean</var> enumeration values, unlike other <var class="product">Janus SOAP ULI</var> enumerations,  
As stated at the outset of this page, <var>Boolean</var> enumeration values, unlike other <var class="product">Janus SOAP ULI</var> enumerations,  
are usable as the condition in an <var>If</var> statement:
are usable as the condition in an <var>If</var> statement:
<p class="code"> %recset  is object recordSet in file sirfiled
<p class="code">%recset  is object recordSet in file sirfiled
  ...
...
find records to %recset
find records to %recset
    rectype = 'FILE'
  rectype = 'FILE'
end find
end find
  ...
...
if %recset:isEmpty then
if %recset:isEmpty then
    print 'No records found!'
  print 'No records found!'
end if
end if
</p>
</p>
   
   
Line 165: Line 174:
completely qualified as <var>Booleans</var>: otherwise there is a syntactic
completely qualified as <var>Booleans</var>: otherwise there is a syntactic
ambiguity between the values <var>True</var> or <var>False</var> and
ambiguity between the values <var>True</var> or <var>False</var> and
fields by the name of <tt>True</tt> or <tt>False</tt>.
fields by the name of "True" or "False".
The following is syntactically valid:
The following is syntactically valid:
<p class="code"> if %(boolean):true then
<p class="code">if %(boolean):true then
    print 'Truth be told'
  print 'Truth be told'
end if
end if
</p>
</p>


==Enumeration methods==
==Enumeration methods==
Besides the [[#Common Enumeration methods|common enumeration methods]], the
Besides the [[Enumerations#Common enumeration methods|common enumeration methods]], the
system <var>Boolean</var> enumeration has additional methods available, which are
system <var>Boolean</var> enumeration has additional methods available, which are described here.
described here.
 
===IsFalse function===
===IsFalse function===
This function examines a <var>Boolean</var> enumeration and returns an integer (0 or 1)
This function examines a <var>Boolean</var> enumeration and returns an integer (0 or 1)
Line 181: Line 190:


====IsFalse syntax====
====IsFalse syntax====
<p class="syntax"> <span class="term">%num</span> <span class="literal">= </span><span class="term">bool</span><span class="literal">:IsFalse</span>
<p class="syntax"><span class="term">%num</span> <span class="literal">= </span><span class="term">bool</span><span class="literal">:IsFalse</span>
</p>
</p>


With automatic conversion of <var>Boolean</var> values to numbers in version 8.1 of the <var class="product">Sirius Mods</var>, use of this function would be rare;
With automatic conversion of numbers to <var>Boolean</var> targets in version 8.1 of the <var class="product">Sirius Mods</var>, assignment of a <var>Boolean</var> value to a numeric target can be rare.
one purpose might be to obtain a numeric value when a <var>Boolean</var> is used in a string context.
See the examples in [[#Booleans not automatically converted to numbers|Booleans not automatically converted to numbers]] and in [[#IsTrue function|IsTrue function]].
Such an example is described in the [[#IsTrue function|IsTrue section]].  
 
====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%num</th>
<tr><th>%num</th>
<td>If specified, a number variable that is assigned the value <code>0</code> if the value of <var class="term">bool</var> is<var>True</var>, and <code>1</code> if <var class="term">bool</var> is <var>False</var>.
<td>If specified, a number variable that is assigned the value <code>0</code> if the value of <var class="term">bool</var> is<var>True</var>, and <code>1</code> if <var class="term">bool</var> is <var>False</var>.</td></tr>
</td></tr>
 
<tr><th>bool</th>
<tr><th>bool</th>
<td>A <var>Boolean</var> enumeration variable or an expression that results in a <var>Boolean</var> enumeration.
<td>A <var>Boolean</var> enumeration variable or an expression that results in a <var>Boolean</var> enumeration.</td></tr>
</td></tr></table>
</table>
 
===IsTrue function===
===IsTrue function===
This function examines a <var>Boolean</var> enumeration and returns an integer (1 or 0)
This function examines a <var>Boolean</var> enumeration and returns an integer (1 or 0)
according to the <var>Boolean</var> value (<var>True</var> or <var>False</var>).
according to the <var>Boolean</var> value (<var>True</var> or <var>False</var>).


With automatic conversion of <var>Boolean</var> values to numbers in version 8.1 of the <var class="product">Sirius Mods</var>, use of this function would be rare;
With automatic conversion of numbers to <var>Boolean</var> targets in version 8.1 of the <var class="product">Sirius Mods</var>, assignment of a <var>Boolean</var> value to a numeric target can be rare.
one purpose might be to obtain a numeric value when a <var>Boolean</var> is used in a string context,
 
for example, to generate some C code:
In addition to the example in [[#Booleans not automatically converted to numbers|Booleans not automatically converted to numbers]], here is an example which generates some C code, using a <var>Boolean</var> in a string context:
<p class="code">%bool is boolean
<p class="code">%bool is boolean
...
...
Line 209: Line 219:
end text
end text
</p>
</p>
====IsTrue syntax====
====IsTrue syntax====
<p class="syntax"> <span class="term">%num</span> <span class="literal">= </span><span class="term">bool</span><span class="literal">:IsTrue</span>
<p class="syntax"><span class="term">%num</span> <span class="literal">= </span><span class="term">bool</span><span class="literal">:IsTrue</span>
</p>
</p>
   
   
Line 216: Line 227:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%num</th>
<tr><th>%num</th>
<td>If specified, a number variable that is assigned the value <code>1</code> if the value of <var class="term">bool</var> is<var>True</var>, and <code>0</code> if <var class="term">bool</var> is <var>False</var>.
<td>If specified, a number variable that is assigned the value <code>1</code> if the value of <var class="term">bool</var> is<var>True</var>, and <code>0</code> if <var class="term">bool</var> is <var>False</var>.</td></tr>
</td></tr>
 
<tr><th>bool</th>
<tr><th>bool</th>
<td>A <var>Boolean</var> enumeration variable or an expression that results in a <var>Boolean</var> enumeration.
<td>A <var>Boolean</var> enumeration variable or an expression that results in a <var>Boolean</var> enumeration.</td></tr>
</td></tr></table>
</table>
 
==See also==
<ul>
<li>[[Lists of classes and methods#Enumerations|List of system enumerations]] </li>
<li>[[Object oriented programming in SOUL]] </li>
</ul>

Latest revision as of 16:35, 23 April 2018

The Boolean enumeration implements the standard logical paradigm of "true" and "false".

While, in some sense, it is just like any other enumeration, because the concept of true and false is so basic to programming, Boolean variables are treated specially by User Language.

Boolean enumeration values

The system Boolean enumeration values are:

  • True
  • False

However, like all other enumerations, a Boolean variable can also be unset so have a null value. While this can be useful in detecting references to unset variables, it can also be problematic in certain sitiuations. Use of the Initial clause on variable declarations and the Default clause on method parameter declarations can mitigate most of these issues, nevertheless it is important to keep in mind the possibility of a Boolean variable being null.

Declaring boolean variables

Boolean variables can be declared the same way any enumeration variables are declared, with the keyword Enumeration followed by the class name:

%truth is enumeration boolean

However, because boolean processing is such a basic part of any programming language, Boolean variables can be declared without the Enumeration keyword:

%truth is boolean

This is also true for method variables and results. For example, the following:

function foo(%n is float, %test is enumeration boolean) is enumeration boolean

is identical to:

function foo(%n is float, %test is boolean) is boolean

Using Booleans in If conditions

The whole point of Boolean variables is to be able to test them for truth and, depending on the result, perform some processing. For example, if %bool is a Boolean variable, the following statement performs the contents of the If block if %bool is set to True:

if %bool then

Note that in this example, if %bool is not set (null), then the request would be canceled with a null object reference error.

Using logical operators with Booleans

User Language has three logical operators:

  • Not
  • And
  • Or

Strictly speaking, in User Language these operators actually operate on numeric values where 0 is treated as False and any non-zero value is treated as True. However, because of the importance of boolean logic in programming, Boolean variables or values can be used instead of numbers for these operators. A Boolean True is treated as 1 and a False is treated as 0. As such, Boolean variables can be used in logical operations as in:

if not %bool then

or

if %bool and (%y gt %x) Then

Automatic conversion of numbers to Boolean

In Sirius Mods 8.1 and later, it is also possible to assign a number to a Boolean variable. When this is done, the number 0 is converted to False and every other value is converted to True. This is especially useful for assigning the result of a comparison to a Boolean:

%bool = %x gt %y

This assignment can, of course, be implicit when a method has a Boolean parameter:

local subroutine foo(%ok is boolean) ... %(local):foo(%x gt %y)

Of course, some methods or $functions return a 0 indicating success and a non-zero value indicating an error. So, just as one can do:

if $setg('NAME', %name) then

one can also assign the result of a method or $function to a Boolean:

%setgSuccess is boolean ... %setgSuccess = $setg('NAME', %name)

One note of caution: Numbers are intrinsic variables and, as such, string values are automatically converted to numbers. Any string that can't be converted to a number is treated as 0. So, if %n is declared as Float, the following:

%n = '1234.56'

would result in %n containing the number 1234.56. The following:

%n = 'Not a number'

would result in %n containing the number 0. The following:

%n = 'ten'

would also result in %n containing the number 0. Hopefully, this is not too surprising. In addition, it should not be surprising that the following:

%n = 'true'

would also result in %n containing the number 0. However, if %bool is a boolean,

%bool = 'true'

would result in %bool containing False because when booleans are set from intrinsic variables, the intrinsic values are treated as numbers, so true was converted to the number 0 before being assigned to %bool.

Of course, there really be no good reason to assign a string (or numeric) literal to a Boolean. If you want to set a Boolean variable to a literal value, simply specify the unquoted literal value as you do when setting any enumeration value:

%bool = true ... %bool = false

In the case where you have a string that contains either True or False, you can use the standard enumeration FromString method to set the Boolean variable:

%bool = %(boolean):fromString(%string)

If %string does not contain "True" or "False" (case independent), FromString throws an InvalidValue exception.

Limitations

Even in Sirius Mods 8.1 and later, there are a few places where numbers are not automatically converted to booleans:

  • As inputs to Boolean parameters to complex subroutines.

    Since complex subroutine can be called before they are declared, doing such automatic conversion would be very complex so is currently not supported. If the automatic conversion of numeric inputs to Boolean parameters is required for a complex subroutine, one option might be to try to convert the complex subroutine to a Common subroutine.

  • As method objects to enhancement methods for the Boolean class.

    For example, given this declaration:

    local function (boolean):xor(%what is boolean) is boolean

    The following produces a compilation error, because (%x gt %y) results in a numeric result but the enhancement method is defined as operating on Booleans:

    %bool = (%x gt %y):xor(%y gt %z)

    Fortunately, Boolean enhancement methods are few and far between, so this restriction is not likely to be a major problem.

Booleans not automatically converted to numbers

While in Sirius Mods 8.1 and later, numeric values are automatically converted when assigned to a Boolean variable, the inverse is not true. For example, if %number is a Float variable and %bool is a Boolean, the following will result in a compilation error:

%number = %bool

This also means that using arithmetic or string operators on Boolean values is not allowed. So the following two statements both result in compilation errors:

%number = %bool * %bool %string = %bool with %bool

Fortunately, one would rarely need to do this, and if one does need to do this for some reason, the IsTrue and ToString methods provide a workaround:

%number = %bool:isTrue * %bool:isTrue %string = %bool:toString with %bool:toString

Because of this, to convert existing methods with Float parameter switches to use Boolean switches, the migration should start by converting the parameter declaration to Boolean. This might require changing some of the code inside the method, but it is also likely that no code changes would be required. Once this is done, code that invokes the method can be modified to pass Boolean rather than Float values.

For example, if one currently has a method defined as:

subroutine doSomething(%goAllOut is float nameRequired) ... if %goAllOut then ... end if ... if (%x le 10) or %goAllout then ... end if

where %goAllOut is used as a boolean switch, one can simply change the method definition to:

subroutine doSomething(%goAllOut is boolean nameRequired)

and everything works (under Sirius Mods 8.1 and later). For example, the following method invocation works because the numbers being passed for goAllOut are automatically converted to boolean:

%object:doSomething(goAllOut=1) ... %object:doSomething(goAllout=(%all eq 'Y'))

Of course, once the change is made to the method definition, the first invocation above could be changed for better clarity to:

%object:doSomething(goAllOut=true)

Using booleans

As stated at the outset of this page, Boolean enumeration values, unlike other Janus SOAP ULI enumerations, are usable as the condition in an If statement:

%recset is object recordSet in file sirfiled ... find records to %recset rectype = 'FILE' end find ... if %recset:isEmpty then print 'No records found!' end if

In the above example, the IsEmpty method returns a Boolean enumeration value. Strictly speaking, the If clause expects a numeric zero or non-zero value as its operand, but in this context Janus SOAP ULI automatically converts a True to a 1 and a False to a 0.

Other places where a Boolean value can be used, that is, where it is automatically converted to the 0 or 1 that User Language expects are:

  • As a Repeat statement operand.
  • As an operand for a logical operator such as Not, And, or Or. This would usually be in an If or Repeat statement.

You can also use Boolean literals in these contexts, but they must be completely qualified as Booleans: otherwise there is a syntactic ambiguity between the values True or False and fields by the name of "True" or "False". The following is syntactically valid:

if %(boolean):true then print 'Truth be told' end if

Enumeration methods

Besides the common enumeration methods, the system Boolean enumeration has additional methods available, which are described here.

IsFalse function

This function examines a Boolean enumeration and returns an integer (0 or 1) according to the Boolean value (True or False).

IsFalse syntax

%num = bool:IsFalse

With automatic conversion of numbers to Boolean targets in version 8.1 of the Sirius Mods, assignment of a Boolean value to a numeric target can be rare. See the examples in Booleans not automatically converted to numbers and in IsTrue function.

Syntax terms

%num If specified, a number variable that is assigned the value 0 if the value of bool isTrue, and 1 if bool is False.
bool A Boolean enumeration variable or an expression that results in a Boolean enumeration.

IsTrue function

This function examines a Boolean enumeration and returns an integer (1 or 0) according to the Boolean value (True or False).

With automatic conversion of numbers to Boolean targets in version 8.1 of the Sirius Mods, assignment of a Boolean value to a numeric target can be rare.

In addition to the example in Booleans not automatically converted to numbers, here is an example which generates some C code, using a Boolean in a string context:

%bool is boolean ... text short i i = {%bool:isTrue} end text

IsTrue syntax

%num = bool:IsTrue

Syntax terms

%num If specified, a number variable that is assigned the value 1 if the value of bool isTrue, and 0 if bool is False.
bool A Boolean enumeration variable or an expression that results in a Boolean enumeration.

See also