| # Section 8.11.2.1 BOOL |

###### immutable class BOOL < $IS_EQ, $IMMUTABLE, $INSTR, $ANCHORED_FMT

#### Formal Types

types
SAME = bool ;
BOOL = bool ;

This class provides the functionality of the basic Boolean logic domain. BOOL objects represent boolean values and either have the value `true' or the value `false'. The pervasive class BOOL bool defines only the three fundamental operations and, or and not. This library class defines several additional operators and conversion routines.

#### create

This feature provides a mechanism for creating a truth value from an octet. An implementation is free to use any bit-pattern to represent the truth value, provided that it is the identical bit-pattern to that produced when the binstr feature is applied (producing a single element binary string).

create | (
| val : OCTET
| ) : SAME

##### Formal Signature

create1(val : OCTET) res : SAME

##### Pre-condition

Note that the selector applied to the binstr operation result is accessing the first (and only) component.

pre val = binstr(res)(1)

##### Post-condition

post card(res) = OCTET.card(val)

This routine returns the truth value corresponding to the bit-pattern in the argument val.

#### create

This feature creates a truth value from the given binary string (which must have a length of one.

create | (
| str : BINSTR
| ) : SAME

##### Formal Signature

create2(str : BINSTR) res : SAME

##### Pre-condition

The string argument must have a length of exactly 1, otherwise there is some unwanted binary data after the required octet.

pre BINSTR.size(str) = 1

##### Post-condition

post res = create1(str(1))

This routine returns the truth value corresponding to the single octet binary string.

#### create

This final variant of the create operation creates a truth value from the encoding of a string representation in the executing environment repertoire and encoding. The 'word' to be converted is expected to be in the language of the local culture.

create | (
| str : STR
| ) : SAME

##### Formal Signature

create3(bool_str : STR) res : SAME

##### Pre-condition

pre is_bool(str)

##### Post-condition

The string method is_prefix is defined in the class STR.

post STR.is_prefix(str(res),bool_str)

This routine returns the truth value corresponding to the text string argument. The actual characters required (and their encoding) are determined by the current cultural environment.

NOTE | The internationally defined default characters for 'true' and 'false' are the digits '1' and '0' respectively in the local encoding. Most cultures will define pairs of values such as 'True/False' in English speaking cultures, 'Wahr/Falsch' in German speaking cultures, etc.

#### build

This feature, given a binary string cursor object as argument, will, depending on the value of the first/next octet, produce a truth value and move past that octet or, in the case that the octet bit-pattern is neither a representation for true nor for false will return false and the cursor will not be moved.

build | (
| cursor : BIN_CURSOR
| ) : SAME

##### Formal Signature

build1(cursor : BIN_CURSOR) res : SAME

##### Pre-condition

pre BIN_CURSOR.remaining(cursor) > 0

##### Post-condition

post res=create(BIN_CURSOR.item(cursor˜))
and BIN_CURSOR.remaining(cursor) + 1=BIN_CURSOR.remaining(cursor~)
or (BIN_CURSOR.remaining(cursor)=BIN_CURSOR.remaining(cursor~))

This routine builds a Boolean value from the first octet remaining in the cursor string. After the execution of this routine there is one octet less in the remainder of the cursor string.

#### build

This variant of build takes a text string cursor rather than a binary one, expecting to find the text string encoding form of a truth value at the first/next position in the text string associated with the cursor.

build | (
| cursor : STR_CURSOR
| ) : SAME

##### Formal Signature

build2(cursor : TEXT_CURSOR) res : SAME

##### Pre-condition

pre TEXT_CURSOR.remaining(cursor) > 0

##### Post-condition

post res=create(TEXT_CURSOR.item(cursor˜))
and TEXT_CURSOR.remaining(cursor) + 1=TEXT_CURSOR.remaining(cursor~)
or (TEXT_CURSOR.remaining(cursor)=TEXT_CURSOR.remaining(cursor~))

This routine builds a Boolean value from the text starting at the current cursor position in the cursor string. After the execution of this routine the cursor position will have moved one or more positions forward if the string represented a truth value. The cursor will not have moved if the string was not a truth value.

#### read

This feature provides a conditional conversion of the next octets in the binary string associated with the cursor. There are four possible outcomes -

- The next octet does not represent a truth value. This is an error condition, indicated upon return by the cursor not having moved.
- The next octet represents the truth value false. This is the condition indicating that there is no following truth value in the binary string. Only one octet has been moved over in the binary string. This is a successful outcome, the value false being returned, the cursor having only been moved by one position in the binary string.
- The next octet represents the value true and the next following octet does not represent a truth value. This is an error condition indicated by the cursor only having moved over one octet and the value false being returned.
- The next octet represents the value true and the next following octet is a truth value. This is also a successful result and the cursor will have moved past two octets.

NOTE | The complexity of this operation arises since the result can only be true or false - ie there are only two values possible. The number of characters moved over in the binary string is therefore used to disambiguate the result returned.

read | (
| cursor : BIN_CURSOR
| ) : SAME

##### Formal Signature

read(cursor : BIN_CURSOR) res : SAME

##### Pre-condition

pre BIN_CURSOR.remaining(cursor) > 0

##### Post-condition

Note that the post-condition, while being true in the absence of implementation error, does not reflect the four possible outcomes.

post let truth : bool=BIN_CURSOR.item(cursor) in
((BIN_CURSOR.remaining(cursor)=BIN_CURSOR.remaining(cursor~))
and not res)
or ((BIN_CURSOR.remaining(cursor) + 1=BIN_CURSOR.remaining(cursor~))

This routine takes the next octet in the binary string as representing a Boolean value. If it does not then the cursor is not moved and false is returned. If this value is true then the next following octet is converted to a Boolean value which is returned, otherwise false is returned and only one octet has been taken from the remainder of the cursor string.

#### not

This feature provides the standard Boolean inversion operation.

not | : SAME

##### Formal Signature

The name of the formal operation corresponding to 'not' has been modified since the word 'not' is a keyword in vdm-sl.

not_v(self : SAME) res : SAME

##### Post-condition

post res = not self

This feature returns the logical complement of self.

#### and

This feature provides the Boolean conjunction operation.

and | (
| other : SAME
| ) : SAME

##### Formal Signature

The name of the formal operation corresponding to 'and' has been modified since the word 'and' is a keyword in vdm-sl.

and_v(self : SAME, other : SAME) res : SAME

##### Post-condition

res = (self
and other)

This routine returns true if and only if self and other are both true, otherwise false.

or | (
| other : SAME
| ) : SAME

Formal Signature

or(self : SAME, other : SAME) res : SAME

Post-condition

res = (self

or other)

This routine returns true if and only if either self or other or both are true, otherwise false.

#### is_eq

This feature provides the logical equality operation for Boolean values. It may be used in infix logical expressions.

is_eq | (
| other : SAME
| ) : SAME

##### Formal Signature

is_eq(self : SAME, other : SAME) res : SAME

##### Post-condition

post res = (self
= other)

This routine returns true if and only if both self and other have the same value, otherwise false.

#### is_eq

This feature provides the logical equality operation for a logical value which may be 'hidden' in an abstract type and self. It may be used in infix logical expressions. Note, however, that object equality will be used if the argument is not of this type.

is_eq | (
| other : $OB
| ) : SAME

##### Formal Signature

The formal argument type is 'any object type', but an actual argument must, of course, be an instantiated object.

is_eq2(self : SAME, other : $OB) res : SAME

##### Post-condition

post res = (self = other)

This routine returns true if and only if both self and other have the same value, otherwise false. This version is provided for use where some abstract type object happens to derive from $IS_EQ. True can only be returned if the actual object is of this type.

#### is_bool

This feature returns a validity indicator if the string contained in the argument is a valid representation of either the value true or the value false. If empty then the corresponding indication is given, otherwise an out of range indication. The string does not have to be a complete 'word', rather it must be at least as long as needed to differentiate the two values - thus, in English where "True" and "False" are the two values, then the first character alone is all that is needed. If the rest of the word is there and does not correspond to 'rue' or 'alse' then, of course, out of range is returned.

is_bool | (
| str : STR
| ) : CONVERSION_RESULTS

##### Formal Signature

is_bool(str : STR) res : CONVERSION_RESULTS

##### Post-condition

post (res = All_Right
and (STR.is_prefix(str(true))
or STR.is_prefix(str(false))))
or (res = Empty
and STR.asize(str) = 0)
or (res = Out_of_Range)

This routine returns All_Right if str is a valid text representation of a truth value, Empty if the string was empty and Out_of_Range for any other string content.

#### xor

This is the first of those routines provided to complete the possible binary operations in the logical domain. They all have their usual mathematical meaning.

xor | (
| other : SAME
| ) : SAME

##### Formal Signature

xor(self : SAME, other : SAME) res : SAME

##### Post-condition

post res = ((self
and not other)
or (other
and not self))

This routine returns true if and only if only one of self and other is true, otherwise false. It is identical to a not equal predicate.

#### xnor

xnor | (
| other : SAME
| ) : SAME

##### Formal Signature

xnor(self : SAME, other : SAME) res : SAME

##### Post-condition

post res = ((self
and other)
or (not other
and not self))

This routine returns true if and only if self and other have the same logical value. It is identical to the is_eq predicate.

#### nand

nand | (
| other : SAME
| ) : SAME

##### Formal Signature

nand(self : SAME, other : SAME) res : SAME

##### Post-condition

post res = not (self
and other)

This routine returns the logical complement of the result of anding self and other.

#### nor

nor | (
| other : SAME
| ) : SAME

##### Formal Signature

nor(self : SAME, other : SAME) res : SAME

##### Post-condition

post res = not (self
or other)

This routine returns the logical complement of the result of oring self and other.

#### implies

implies | (
| other : SAME
| ) : SAME

##### Formal Signature

implies(self : SAME, other : SAME) res : SAME

##### Post-condition

post res = (not self
or other)

This routine returns if and only if self implies other. It is the same operation as nand_not.

#### and_rout

This routine is identical to the and operation built in to the language. It is provided for possible use as a bound routine.

and_rout | (
| other : SAME
| ) : SAME

##### Formal Signature

and_rout(self : SAME, other : SAME) res : SAME

##### Post-condition

post res = (self
and other)

This routine is the same as the and operation useful when making bound routines.

#### or_rout

This routine also corresponds to a built-in operator - or. It is provided for possible use as a bound routine.

or_rout | (
| other : SAME
| ) : SAME

##### Formal Signature

or_rout(self : SAME, other : SAME) res : SAME

##### Post-condition

post res = (self
or other)

This routine is the same as the or operation - provided for use when making bound routines.

#### and_not

and_not | (
| other : SAME
| ) : SAME

##### Formal Signature

and_not(self : SAME, other : SAME) res : SAME

##### Post-condition

post res = (self
and not other)

This routine returns the result of self and the complement of other.

#### or_not

or_not | (
| other : SAME
| ) : SAME

##### Formal Signature

or_not(self : SAME, other : SAME) res : SAME

##### Post-condition

post res = (self or not other)

This routine returns the result of self or the complement of other.

#### nand_not

nand_not | (
| other : SAME
| ) : SAME

##### Formal Signature

nand_not(self : SAME, other : SAME) res : SAME

##### Post-condition

post res = not (self and not other)

This routine returns the result of self nanded with the complement of other. It is the same as the complement of self or other.

#### nor_not

nor_not | (
| other : SAME
| ) : SAME

##### Formal Signature

nor_not(self : SAME, other : SAME) res : SAME

##### Post-condition

post res = not (self and other)

This routine returns the result of self nored with the complement of other. It is the same as the complement of self and other.

#### card

This operation is provided solely for backward compatibility with earlier versions of the library. It returns the value 1 when self is true and the value zero otherwise.

card | : CARD

##### Formal Signature

card(self : SAME) res : CARD

##### Post-condition

post (self and (res = 1))
or (not self and (res = 0))

This routine returns the value 1 if self is true, otherwise the value zero.

#### binstr

This routine converts the logical value into a single octet binary string. The bit-pattern used shall be such that creating a new value from the result shall have the same values as self.

binstr | : BINSTR

##### Formal Signature

binstr(self : SAME) res : BINSTR

##### Post-condition

Note that this post-condition cannot be converted into executable Sather post-condition as it is mutually recursive with the 'inverse' creation operation.

post create(res(1)) = self
and (BINSTR.size(res) = 1)

This routine returns a single element binary string which contains a bit pattern such that creation from an octet would produce the same value as self.

#### write

This routine appends the value of self as a single octet to the external binary file indicated by the argument.

write | (
| fyle : BIN_FILE
| )

##### Formal Signature

write(self : SAME, fyle : BIN_FILE)

##### Pre-condition

pre BIN_FILE.writable(fyle)

##### Post-condition

post fyle = BIN_FILE.plus(fyle,binstr(self))

This routine appends a binary representation of self to the given binary file.

str

This is the first of two text string representation creation routines. It returns a text string encoding in the given language and encoding. Note that this may not necessarily be representable on a local rendering engine.

str | (
| lib : LIBCHARS
| ) : STR

##### Formal Signature

str1(self : SAME, lib : LIBCHARS) res : STR

##### Post-condition

Although the post-condition below will be true if the local and given culture are the same, this may well not be the case when they are different!

post create(res) = self

This routine provides a string representation of self in the given repertoire and encoding. The rules for forming the actual representation are defined by the Sather system resources and library cultural definitions.

#### str

This version of the str operation produces a text string from the value of self in the execution environment culture and encoding. This should normally be representable by a local rendering engine.

str | : STR

##### Formal Signature

str2(self : SAME) res : STR

##### Post-condition

post create(res) = self

This routine provides a string representation of self in the default repertoire and encoding. The rules for forming the actual representation are defined by the Sather system resources and library cultural definitions.

#### fmt

This routine is provided for use by the formatting facilities of the Representation section of this library. It is included here since this class provides the string conversion facility. Note that this version of fmt makes use of a given culture in addition to the format descriptor. The format descriptor may be used directly, however, since it is produced as part of the formatting operation, this is not expected to be common usage.

fmt | (
| fmt : ANCHORED_DESCR ;
| lib : LIBCHARS
| ) : STR

##### Formal Signature

fmt1(self : SAME, format : ANCHORED_DESCR, lib : LIBCHARS) res : STR

##### Post-condition

The very nature of this operation, being dynamically determinable during executioin only provides for no realisable formal specification post-condition, rather the informal statement that a formatted representation of self shall be returned.

This routine returns the formatted string representation of self in accordance with the string format in the given repertoire and encoding. This provides special case treatment where the leading component is exactly one - it reduces the value string to the single leading character - which is therefore expected to differ for the two values!

#### fmt

This version of fmt creates the result in the culture and coding of the current execution environment.

fmt | (
| fmt : ANCHORED_DESCR ;
| ) : STR

##### Formal Signature

fmt2(self : SAME, format : ANCHORED_DESCR) res : STR

##### Post-condition

The very nature of this operation, being dynamically determinable during executioin only provides for no realisable formal specification post-condition, rather the informal statement that a formatted representation of self shall be returned.

This routine returns the formatted string representation of self in accordance with the string format in the default repertoire and encoding. This provides special case treatment where the leading component is exactly one - it reduces the value string to the single leading character - which is therefore expected to differ for the two values!

| Language Index |  | Library Index |  | Non-numeric Index

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