# 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 `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 `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

### `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

### `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

### `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

### `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