# Module `convert`

## Index

- Process `REAL32TOSTRING` - Take a binary representation of a real number and convert it into a string of characters that is the decimal representation of that number, formatted according to given rules ( see Notes below )
  - Process `Round` - Round a real number to the nearest integer
  - Process `WriteDec` - Take an unsigned integer and convert it to the corresponding ASCII string, with the caveat that trailing zeros are not written
  - Process `restrict` - Round a number that is given in the form of a character string
- Process `REAL64TOSTRING` - Take a binary representation of a real number and convert it into a string of characters that is the decimal representation of that number, formatted according to given rules ( see Notes below )
  - Process `Round` - Round a real number to the nearest integer
  - Process `WriteDec` - Take an unsigned integer and convert it to the corresponding ASCII string, with the caveat that trailing zeros are not written
  - Process `restrict` - Round a number that is given in the form of a character string
- Process `STRINGTOINT16` - Convert to an INT16 the value represented by string
- Process `STRINGTOREAL32` - Converts BYTE array string into a REAL32 number X
- Process `STRINGTOREAL64` - Converts BYTE array string into a REAL64 number X

## Declarations

### `strr32ta.occ`:44Process `STRINGTOREAL32`

`PROC STRINGTOREAL32 (BOOL Error, REAL32 X, VAL []BYTE string)`

Converts BYTE array string into a REAL32 number X

If the value represented by string overflows the REAL32 range then an appropriately signed infinity is returned in X. If the absolute value represented by string is in the range 2^-149 to just less than 2^-126, then a denormalised number is returned. If the absolute value represented by string is less than 2^-149 then zero is returned. If the syntax of string is incorrect then not only is Error set to TRUE, but a Not-a-Number ( NaN ) is returned for X. If there remain characters after the end of the longest correct string, although Error is set to TRUE, X is returned with the value of the correct part of string

#### Parameters:

`BOOL` | `Error` | TRUE if the syntax of string is not correct occam, or if there are any characters after the end of the longest correct string; otherwise it is FALSE
`REAL32` | `X` | the binary representation in IEEE single precision format of the real decimal in string
`VAL []BYTE` | `string` | a sequence of ASCII characters

### `int16ta.occ`:51Process `STRINGTOINT16`

`PROC STRINGTOINT16 (BOOL Error, INT16 n, VAL []BYTE string)`

Convert to an INT16 the value represented by string.

A plus ( + ) or a minus ( - ) sign is allowed in the first position of string. An illegal character is any non-numeric character, other than + or - in the first position.

#### Parameters:

`BOOL` | `Error` | TRUE if the value of string overflows the INT16 range; TRUE if there are any illegal characters in string; FALSE otherwise

`INT16`

`n`

if the value that string represents does not overflow the INT16 range then n is the INT16 that string represents, with the convention that n is zero if string is empty; otherwise n will be the value of the portion of string up to any illegal character, where n is zero if an illegal character is in the first position of string, or if the INT16 range overflows n will contain the low order bits of the binary representation of string

`VAL []BYTE` | `string` | the characters that are to be converted to an INT16

### `strr64ta.occ`:49Process `STRINGTOREAL64`

`PROC STRINGTOREAL64 (BOOL Error, REAL64 X, VAL []BYTE string)`

Converts BYTE array string into a REAL64 number X

A sign may start string. If the value represented by string overflows the REAL64 range then an appropriately signed infinity is returned in X. If the absolute value represented by string is in the range 2^-1074 to just less than 2^-1022, then a denormalised number is returned. If the absolute value represented by string is less than 2^-1074 then zero is returned. If the syntax of string is incorrect then not only is Error set to TRUE, but a Not-a-Number ( NaN ) is returned for X. If there remain characters after the end of the longest correct string, although Error is set to TRUE, X is returned with the value of the correct part of string

#### Parameters:

`BOOL` | `Error` | TRUE if the syntax of string is not correct occam, or if there are any characters after the end of the longest correct string; otherwise it is FALSE
`REAL64` | `X` | the binary representation in IEEE double precision format of the real decimal in string
`VAL []BYTE` | `string` | a sequence of ASCII characters

### `r64strta.occ`:93Process `REAL64TOSTRING`

`PROC REAL64TOSTRING (INT len, []BYTE string, VAL REAL64 X, VAL INT Ip, Dp)`

Take a binary representation of a real number and convert it into a string of characters that is the decimal representation of that number, formatted according to given rules ( see Notes below ).

Rounding mode is round to nearest. Which format is used depends on the combination of values of Ip, Dp and X. In all cases, any digits beyond the 9th significant digit for single precision or 17th significant digit for double precision will be given as 0 and cannot be considered accurate. If string overflows this routine acts as an invalid process.

Case (i): Ip = 0, Dp = 0 => free format Where possible a fixed point representation is used. If it is not used then exponential form is used. It is not used if more than 9 | 17 significant digits of accuracy ( single | double ) would be required before the decimal point, or if there are more than 3 zeroes after the decimal point before the first significant digit. In any case, the maximum number of characters returned in string is 15 for a single precision X, and 24 for a double precision X. string is left justified. If X is infinity or a NaN, then the string will contain one of "Inf", "-Inf" or "NaN", but not the quotes.

Case (ii): Ip = 0, Dp > 0 => exponential format The form of exponential format is, firstly either a minus sign or a space ( this latter instead of an explicit plus sign ), a fraction in the form <digit>.<digits>, the exponential symbol ( E ), the sign of the exponent ( + or - ), then the exponent, which is two digits for a single precision X, three digits for a double precision X. Dp gives the number of digits in the fraction ( 1 before the point, and the others after, but not counting the point ). The total number of characters in string is ( Dp + 6 ) for a single precision X, and ( Dp + 7 ) for a double precision X. If Dp = 1 then the fraction is of the form <space>digit ( which, note, will not result in occam syntax for the real ). If X is infinity or a NaN, then the string will contain one of " Inf", "-Inf" or " NaN", but not the quotes, padded on the right to fill the field width.

Case (iii): Ip > 0, Dp > 0 => fixed point if possible Ip gives the number of places before the point, not counting the sign place; Dp the number of places after the point. Padding spaces are added on the left as necessary. If the number will not fit the format, then an exponential format is used with the same field width as the fixed point representation would have had. If Ip and Dp are very small then an exponential representation may not fit in the field width so the special value "Ov" with a sign is returned. There are always ( Ip + Dp + 2 ) characters in string, the 2 being the decimal point and the sign ( - or space ). If X is infinity or a NaN, then the string will contain one of " Inf", "-Inf" or " NaN", but not the quotes, padded on the right to fill the field width.

All other combinations of Ip and Dp are meaningless and will cause an error.

#### Parameters:

`INT` | `len` | the number of characters ( BYTEs ) of string occupied by the formatted decimal representation of the real number
`[]BYTE` | `string` | an array containing the formatted decimal representation of the real number in the first len bytes, the remaining bytes being undefined
`VAL REAL64` | `X` | the real number, in IEEE format, to be converted
`VAL INT` | `Ip` | the first of two formatting values
`VAL INT` | `Dp` | the second of two formatting values

### `r64strta.occ`:373Process `Round`

`PROC Round (INT Xexp, [2]INT Xfrac, Xint, INT direction)`

Round a real number to the nearest integer.

( Xexp on entry ) < ( 2 * the number of bits per word ) is assumed. This procedure only caters for non-negative numbers.

#### Parameters:

`INT` | `Xexp` | actual exponent, not biased one: on entry, of the number to round; on exit, of the rounded number
`[2]INT` | `Xfrac` | the fractional part of the real with implicit bit explicit: on entry, of the number to round; on exit, of the rounded number
`[2]INT` | `Xint` | the nearest integer that the combination of Xexp and Xfrac on entry give
`INT` | `direction` | this parameter is applicable only for numbers ending in 5: equal to -1 if the exact value was rounded down; equal to 0 if the value on entry is exact; equal to +1 if the exact value was rounded up

### `r64strta.occ`:488Process `WriteDec`

`PROC WriteDec ([]BYTE Buf, INT Length, VAL []INT Num)`

Take an unsigned integer and convert it to the corresponding ASCII string, with the caveat that trailing zeros are not written.

An example of what is meant by not writing trailing zeros to Buf: if Num = 30, Length will be 1 and Buf[ 0 ] = '3' will be the only defined character in Buf.

#### Parameters:

`[]BYTE` | `Buf` | contains the ASCII string representing the integer ( Num ) ( apart from trailing zeros ); the string is [ Buf FROM 0 FOR Length ]
`INT` | `Length` | the number of meaningful characters in Buf
`VAL []INT` | `Num` | the integer to be converted, assumed unsigned: numbers from 0 to 4,294,967,295 inclusive, for 32-bit processors, or 0 to 65535 inclusive, for 16-bit processors

### `r64strta.occ`:542Process `restrict`

`PROC restrict ([]BYTE Buf, INT Places, LogX, VAL INT digits, INT direction)`

Round a number that is given in the form of a character string.

"... if the two nearest representable values are equally near, the one with its least significant bit zero shall be delivered." IEEE 754-1985, Sec 4.1. LSB zero <=> last digit is even. Any resultant trailing zeroes in Buf are elided.

#### Parameters:

`[]BYTE` | `Buf` | the character string holding the number, assumed not to have trailing zeroes
`INT` | `Places` | the actual number of characters in the string
`INT` | `LogX` | floor( log10( number in Buf ) )
`VAL INT` | `digits` | the number of digits wanted in the rounded number; assumed greater than or equal to zero
`INT` | `direction` | this parameter is applicable only for numbers in Buf ending in 5: equal to -1 if the exact value was rounded down; equal to 0 if the value in Buf is exact; equal to +1 if the exact value was rounded up

### `r32strta.occ`:90Process `REAL32TOSTRING`

`PROC REAL32TOSTRING (INT len, []BYTE string, VAL REAL32 X, VAL INT Ip, Dp)`

Take a binary representation of a real number and convert it into a string of characters that is the decimal representation of that number, formatted according to given rules ( see Notes below ).

Rounding mode is round to nearest. Which format is used depends on the combination of values of Ip, Dp and X. In all cases, any digits beyond the 9th significant digit for single precision or 17th significant digit for double precision will be given as 0 and cannot be considered accurate. If string overflows this routine acts as an invalid process.

Case (i): Ip = 0, Dp = 0 => free format Where possible a fixed point representation is used. If it is not used then exponential form is used. It is not used if more than 9 | 17 significant digits of accuracy ( single | double ) would be required before the decimal point, or if there are more than 3 zeroes after the decimal point before the first significant digit. In any case, the maximum number of characters returned in string is 15 for a single precision X, and 24 for a double precision X. string is left justified. If X is infinity or a NaN, then the string will contain one of "Inf", "-Inf" or "NaN", but not the quotes.

Case (ii): Ip = 0, Dp > 0 => exponential format The form of exponential format is, firstly either a minus sign or a space ( this latter instead of an explicit plus sign ), a fraction in the form <digit>.<digits>, the exponential symbol ( E ), the sign of the exponent ( + or - ), then the exponent, which is two digits for a single precision X, three digits for a double precision X. Dp gives the number of digits in the fraction ( 1 before the point, and the others after, but not counting the point ). The total number of characters in string is ( Dp + 6 ) for a single precision X, and ( Dp + 7 ) for a double precision X.

If Dp = 1 then the fraction is of the form <space>digit ( which, note, will not result in occam syntax for the real ). If X is infinity or a NaN, then the string will contain one of " Inf", "-Inf" or " NaN", but not the quotes, padded on the right to fill the field width.

Case (iii): Ip > 0, Dp > 0 => fixed point if possible Ip gives the number of places before the point, not counting the sign place; Dp the number of places after the point. Padding spaces are added on the left as necessary. If the number will not fit the format, then an exponential format is used with the same field width as the fixed point representation would have had. If Ip and Dp are very small then an exponential representation may not fit in the field width so the special value "Ov" with a sign is returned. There are always ( Ip + Dp + 2 ) characters in string, the 2 being the decimal point and the sign ( - or space ). If X is infinity or a NaN, then the string will contain one of " Inf", "-Inf" or " NaN", but not the quotes, padded on the right to fill the field width.

All other combinations of Ip and Dp are meaningless and will cause an error.

#### Parameters:

`INT` | `len` | the number of characters ( BYTEs ) of string occupied by the formatted decimal representation of the real number
`[]BYTE` | `string` | an array containing the formatted decimal representation of the real number in the first len bytes, the remaining bytes being undefined
`VAL REAL32` | `X` | the real number, in IEEE format, to be converted
`VAL INT` | `Ip` | the first of two formatting values
`VAL INT` | `Dp` | the second of two formatting values

### `r32strta.occ`:349Process `Round`

`PROC Round (INT Xexp, Xfrac, Xint, direction)`

Round a real number to the nearest integer.

( Xexp on entry ) < ( number of bits per word ) is assumed. This procedure only caters for non-negative numbers.

#### Parameters:

`INT` | `Xexp` | actual exponent, not biased one: on entry, of the number to round; on exit, of the rounded number
`INT` | `Xfrac` | the fractional part of the real with implicit bit explicit: on entry, of the number to round; on exit, of the rounded number
`INT` | `Xint` | the nearest integer that the combination of Xexp and Xfrac on entry give
`INT` | `direction` | this parameter is applicable only for numbers ending in 5: equal to -1 if the exact value was rounded down; equal to 0 if the value on entry is exact; equal to +1 if the exact value was rounded up

### `r32strta.occ`:404Process `WriteDec`

`PROC WriteDec ( []BYTE Buf, INT Length, VAL INT Num )`

Take an unsigned integer and convert it to the corresponding ASCII string, with the caveat that trailing zeros are not written.

An example of what is meant by not writing trailing zeros to Buf: if Num = 30, Length will be 1 and Buf[ 0 ] = '3' will be the only defined character in Buf.

#### Parameters:

`[]BYTE` | `Buf` | contains the ASCII string representing the integer ( Num ) ( apart from trailing zeros ); the string is [ Buf FROM 0 FOR Length ]
`INT` | `Length` | the number of meaningful characters in Buf
`VAL INT` | `Num` | the integer to be converted, assumed unsigned: numbers from 0 to 4,294,967,295 inclusive, for 32-bit processors, or 0 to 65535 inclusive, for 16-bit processors

### `r32strta.occ`:453Process `restrict`

`PROC restrict ([]BYTE Buf, INT Places, LogX, VAL INT digits, INT direction)`

Round a number that is given in the form of a character string.

"... if the two nearest representable values are equally near, the one with its least significant bit zero shall be delivered." IEEE 754-1985, Sec 4.1. LSB zero <=> last digit is even. Any resultant trailing zeroes in Buf are elided.

#### Parameters:

`[]BYTE` | `Buf` | the character string holding the number, assumed not to have trailing zeroes
`INT` | `Places` | the actual number of characters in the string
`INT` | `LogX` | floor( log10( number in Buf ) )
`VAL INT` | `digits` | the number of digits wanted in the rounded number; assumed greater than or equal to zero
`INT` | `direction` | this parameter is applicable only for numbers in Buf ending in 5: equal to -1 if the exact value was rounded down; equal to 0 if the value in Buf is exact; equal to +1 if the exact value was rounded up