| # Examples 8.11.2.1: BOOL |

The features of the required library class BOOL are used in individual examples. None of the examples given is a complete class nor necessarily a 'complete' method.

In all of the examples it will be assumed that the code shown is in a class called, say, EXAMPLE.

### Value Creation/Conversion

OCTET), a binary string and from a text string. The latter two have 'build' variants taking data from a cursor buffer.

#### create

The principal conversion to a truth value is the one taking an octet as argument for conversion, thus

pred : BOOL := BOOL::create(some_octet)

If the least significant bit of the octet is set then the result will be true, otherwise false.

#### create

This second conversion operation takes a single element binary string as argument, thus

pred : BOOL := BOOL::create(some_binary_string)

If the implementation-dependent bits of the octet are set then the result will be true, otherwise false. This routine is provided generally for commonality of usage with those routines which need more than one octet for binary representation. In practice the above could have been written as

pred : BOOL := BOOL::create(some_binary_string[0])

which would, of course, use the variant with a single octet argument.

#### create

This last variant of create takes as argument a text string - such as "T", "tr" or even the full word "True". This will typically have been obtained from some user or text file input to the program. Note that the three suggestions given would only be sensible if the cultural definition of these was for English speakers using 'True' and 'False' as representation. The call

pred : BOOL := BOOL::create(some_text_string)

with any of the above suggestions would return the value true. Note, in particular that the matching is not case sensitive.

#### build

The required library provides cursor objects for scanning string buffers and the convention has been adopted in the required library that routines which produce values by conversion from some buffer are called 'build'. This first variant takes a binary string cursor as argument, so that it is possible to write

pred : BOOL := BOOL::build(some_binary_cursor)

Since a truth value is storable in a single octet, it would be possible to write the equivalent using the first create variant as -

pred : BOOL := BOOL::create(some_binary_cursor.item) ;
some_binary_cursor.advance

See the BIN_CURSOR class for details of the binary cursor buffer machanism.

#### build

Corresponding to the binary build operation there is a text one, taking a STR_CURSOR argument.

pred : BOOL := BOOL::build(some_text_cursor)

Note that in this very special case if the text in the buffer at the current position is not a valid truth value representation then false will be returned and the current position will not have changed. This special case arises because it is more confusing to return an 'OK' at the same time as a Boolean value. See, however, the is_bool predicate below.

#### read

The final 'creation' operation is provided for commonality with other classes reading from binary strings. The argument is again a binary cursor, but the operation is different to building. If the first octet in the remainder of the buffer is the truth value true then the second octet is used to give the desired truth value. It is thus a mechanism catering for optional components of some file, for example.

pred : BOOL := BOOL::read(some_binary_cursor)

On return from this routine there are two possibilities -

- if only one octet has been taken then the value returned can only be false, meaning that there is no logical value to be found at this place in the buffer.
- if two octets have been taken then the value returned is that of the truth value at that place in the buffer.

#### is_bool

This routine is provided so that a prior check on whether some string contains a text representation of a truth value can be tested in advance. Typical code might look like the following routine -

confirm : BOOL is
loop
issue_prompt ;
response : STR := get_reply ;
case BOOL::is_bool(response)
when CONVERSION_RESULTS::All_Right then
return BOOL::create(response)
when CONVERSION_RESULTS::Out_of_Range then
error_bad_value
when CONVERSION_RESULTS::Empty then
error_no_input
end
end
end

### Logical Operations

There are sixteen logical operations defined in this class, one unary and the remainder binary having the truth tables which follow. Note that some of the tables are identical to others. The reason for this is that the way in which using code may wish to handle some problem may view the operation in one way, not in some other.

Feature | self
--- | ---
| T | F
not | F | T

Binary operation truth tables are given below rather than giving an individual example code for each. Examples of the use of binary logical operations permeate example text for most other classes!

Feature |  | self
--- | --- | ---
| T | F
and | other | T | T | F
F | F | F
Feature |  | self
--- | --- | ---
| T | F
or | other | T | T | T
F | T | F
Feature |  | self
--- | --- | ---
| T | F
is_eq | other | T | T | F
F | F | T
Feature |  | self
--- | --- | ---
| T | F
is_eq | other | T | T | F
F | F | T
Feature |  | self
--- | --- | ---
| T | F
xor | other | T | F | T
F | T | F
Feature |  | self
--- | --- | ---
| T | F
xnor | other | T | T | F
F | F | T
Feature |  | self
--- | --- | ---
| T | F
nand | other | T | F | T
F | T | T
Feature |  | self
--- | --- | ---
| T | F
nor | other | T | F | F
F | F | T
Feature |  | self
--- | --- | ---
| T | F
implies | other | T | F | F
F | F | T
Feature |  | self
--- | --- | ---
| T | F
and_rout | other | T | T | F
F | F | F
Feature |  | self
--- | --- | ---
| T | F
or_rout | other | T | T | T
F | T | F
Feature |  | self
--- | --- | ---
| T | F
and_not | other | T | F | T
F | F | F
Feature |  | self
--- | --- | ---
| T | F
or_not | other | T | T | T
F | F | T
Feature |  | self
--- | --- | ---
| T | F
nand_not | other | T | F | F
F | F | T
Feature |  | self
--- | --- | ---
| T | F
nor_not | other | T | F | T
F | T | T

### Conversion Operations

The small group of conversion operations which follows are responsible for conversion from a truth value to either a numeric 'code', a bit-pattern or a text string.

#### card

This routine converts the Boolean value to a cardinal number, one corresponding to true and zero corresponding to false, thus -

if pred then ...

and

if pred.card = 1 then ...

are equivalent - although the former is much more efficient!

#### binstr

Where it is necessary to export a truth value then it needs conversion into a bit-pattern. This name of this operation is the one used throughout the required library for doing such a conversion. Thus the routine in the next example could have been written as

write( fyle : BIN_FILE
) is
fyle := fyle + binstr
end

NOTE | While the above source text could provide the implementation of the next example routine, the example is not intended to indicate that it is necessarily the implementation used by a provider of this required library!

#### write

As suggested by the above example, a simple call of this routine with a given BIN_FILE argument will append a binary representation of self to that file, thus -

write(out_file)

#### str

For a program which operates in several cultures at once (eg a conversion program from one to another) it is often necessary to provide a textual representation of a value suitably composed/encoded for such a culture - not being the local culture in the execution environment. This first form of the 'str' routine is provided with an argument which provides the conversion routine with all of the culture-dependent data it requires, thus -

converted_output_file := converted_output_file + str(target_culture)

would provide the necessary string representation to append to, say, the converted output.

#### str

This routine provides an output text representation of self in the current local culture, thus -

some_output_file := some_output_file + str

is identical in meaning to the use of the default culture lib with the first version of str, thus -

some_output_file := some_output_file + str(LIBCHARS::default)

### Text Formatting

In addition to the conversion of a value to some internationalised form, simple formatting layout to incorporate the resulting text string into some message is a most important function of the required library. Full details of this are given in the Representation section.

In order to permit formatting to operate it is necessary for each class inheriting from $FMT to provide the two routines fmt with a library argument and fmt without a library argument. Under normal circumstances these routines will not be invoked directly by a library user, rather by the library formatting engine.

| Specification Index |  | Language Index |  | Section 8 Index

Comments or enquiries should be made to Keith Hopper. Page last modified: Wednesday, 24 May 2000. |