Boolean enumeration

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

• List of system enumerations
• Object oriented programming in SOUL