1.8	String conversion library 
Library: convert.lib
This library contains procedures for converting numeric values to strings and vice versa. String to numeric conversions return two results, the converted value and a boolean error indication. Numeric to string conversions return the converted string and an integer which represents the number of significant characters written into the string.
These routines are also described in appendix O of the occam 2 Reference Manual.

Procedure	Parameter Specifiers	
INTTOSTRING	INT len, []BYTE string, VAL INT n	
INT16TOSTRING	INT len, []BYTE string, VAL INT16 n	
INT32TOSTRING	INT len, []BYTE string, VAL INT32 n	
INT64TOSTRING	INT len, []BYTE string, VAL INT64 n	
HEXTOSTRING	INT len, []BYTE string, VAL INT n	
HEX16TOSTRING	INT len, []BYTE string, VAL INT16 n	
HEX32TOSTRING	INT len, []BYTE string, VAL INT32 n	
HEX64TOSTRING	INT len, []BYTE string, VAL INT64 n	
REAL32TOSTRING	INT len, []BYTE string, VAL REAL32 X, VAL INT Ip, Dp	
REAL64TOSTRING	INT len, []BYTE string, VAL REAL64 X, VAL INT Ip, Dp	
BOOLTOSTRING	INT len, []BYTE string, VAL BOOL b	
STRINGTOINT	BOOL Error, INT n, VAL []BYTE string	
STRINGTOINT16	BOOL Error, INT16 n, VAL []BYTE string	
STRINGTOINT32	BOOL Error, INT32 n, VAL []BYTE string	
STRINGTOINT64	BOOL Error, INT64 n, VAL []BYTE string	
STRINGTOHEX	BOOL Error, INT n, VAL []BYTE string	
STRINGTOHEX16	BOOL Error, INT16 n, VAL []BYTE string	
STRINGTOHEX32	BOOL Error, INT32 n, VAL []BYTE string	
STRINGTOHEX64	BOOL Error, INT64 n, VAL []BYTE string	
STRINGTOREAL32	BOOL Error, REAL32 X, VAL []BYTE string	
STRINGTOREAL64	BOOL Error, REAL64 X, VAL []BYTE string	
STRINGTOBOOL	BOOL Error, b, VAL []BYTE string	

Procedure definitions
INTTOSTRING 
PROC INTTOSTRING (INT len, []BYTE string, 
                  VAL INT n)
Converts an integer value to a string. The procedure returns the decimal representation of n in string and the number of characters in the representation, in len. If string is not long enough to hold the representation then this routine acts as an invalid process.
Similar procedures are provided for the types INT16, INT32, and INT64. 
INT16TOSTRING 
PROC INT16TOSTRING (INT len, []BYTE string, 
                    VAL INT16 n)
As INTTOSTRING but for 16bit integers. 
INT32TOSTRING 
PROC INT32TOSTRING (INT len, []BYTE string, 
                    VAL INT32 n)
As INTTOSTRING but for 32bit integers. 
INT64TOSTRING 
PROC INT64TOSTRING (INT len, []BYTE string, 
                    VAL INT64 n)
As INTTOSTRING but for 64bit integers. 
HEXTOSTRING 
PROC HEXTOSTRING (INT len, []BYTE string, 
                  VAL INT n)
The procedure returns the hexadecimal representation of n in string and the number of characters in the representation, in len. All the bits of n, (in 4bit wide word lengths) are output so that leading zeroes or `F's are included. The number of characters will be the number of bits in an INT divided by four. A `#' is not output by the HEXTOSTRING procedure. If string is not long enough to hold the representation then this routine acts as an invalid process.
Similar procedures are provided for the types HEX16, HEX32 and HEX64. 
HEX16TOSTRING 
PROC HEX16TOSTRING (INT len, []BYTE string, 
                    VAL INT16 n)
As HEXTOSTRING but for 16bit integers. 
HEX32TOSTRING 
PROC HEX32TOSTRING (INT len, []BYTE string, 
                    VAL INT32 n)
As HEXTOSTRING but for 32bit integers. 
HEX64TOSTRING 
PROC HEX64TOSTRING (INT len, []BYTE string,  
                    VAL INT64 n)
As HEXTOSTRING but for 64bit integers. 
REAL32TOSTRING 
PROC REAL32TOSTRING (INT len, []BYTE string, 
                     VAL REAL32 X, 
                     VAL INT Ip, Dp)       
Converts a 32bit real number (represented in single precision IEEE format) to a string of ASCII characters. len is the number of characters (BYTEs) of string used for the formatted decimal representation of the number. (The following description applies to and notes the differences between this procedure and REAL64TOSTRING). 
The string must match the format for occam real literals as defined in the occam 2 Reference Manual, p 123, for example, 1.2E+2.
Depending on the value of X and the two formatting variables Ip and Dp the procedure will use either a fixed or exponential format for the output string. These formats are defined as follows:

Fixed :	First, either a minus sign or space (an explicit plus sign is not used), followed by a fraction in the form <digits>.<digits>. Padding spaces are added to the left of the sign indicator, as necessary. (Ip gives the number of places before the point and Dp the number of places after the point).	
Exponential :	First, either a minus sign or space (again, an explicit plus sign is not used), followed by a fraction in the form <digit>.<digits>, the exponential symbol (E), the sign of the exponent (explicitly plus or minus), then the exponent, which is two digits for a REAL32 and three digits for a REAL64. (Dp gives the number of digits in the fraction (1 before the decimal point and the others after)).	

Possible combinations of Ip and Dp fall into three categories, described below. Note: the term `Free format' means that the procedure may adopt either fixed or exponential format, depending on the actual value of X. 
1	If Ip=0, Dp=0, then free format is adopted. Exponential format is used if the absolute value of X is less than 10-4, but nonzero, or greater than 109 (for REAL32), or greater than 1017 (for REAL64); otherwise fixed format is used. 
The value of len is dependent on the actual value of X with trailing zeroes suppressed. The maximum length of the result is 15 or 24, depending on whether it is REAL32 or REAL64 respectively. 
If X is `NotaNumber' or infinity then the string will contain one of the following: `Inf', `-Inf' or `NaN', (excluding the quotes). 
2	If Ip>0, Dp>0, fixed format is used, unless the value needs more than Ip significant digits before the decimal point, in which case, exponential format is used. If exponential does not fit either, then a signed string `Ov' is produced. The length is always Ip + Dp + 2 when Ip>0, Dp>0. 
If X is `NotaNumber' or infinity then the string will contain one of the following: `Inf', `-Inf' or `NaN', (excluding the quotes) and padded out by spaces on the right to fill the field width. 
3	If Ip=0, Dp>0, then exponential format is always used. The length of the result is Dp + 6 or Dp + 7, depending on whether X is a REAL32 or REAL64, respectively.
If Ip=0, Dp=1, then a special result is produced consisting of a sign, a blank, a digit and the exponent. The length is 7 or 8 depending on whether X is a REAL32 or REAL64. Note: this result does not conform to the occam format for a REAL.
If X is `NotaNumber' or infinity then the string will contain one of the following: `Inf', `-Inf' or `NaN', (excluding the quotes) and padded out by spaces on the right to fill the field width. 
All other combinations of Ip and Dp are errors.
If string is not long enough to hold the requested formatted real number as a string then these routines act as invalid processes.
REAL64TOSTRING 
PROC REAL64TOSTRING (INT len, []BYTE string, 
                     VAL REAL64 X, 
                     VAL INT Ip, Dp)
 As REAL32TOSTRING but for 64bit numbers. 
BOOLTOSTRING 
PROC BOOLTOSTRING (INT len, []BYTE string, 
                   VAL BOOL b)
Converts a boolean value to a string. The procedure returns `TRUE' in string if b is TRUE and `FALSE' otherwise. len contains the number of characters in the string returned. If string is not long enough to hold the representation then this routine acts as an invalid process.
STRINGTOINT 
PROC STRINGTOINT (BOOL Error, INT n, 
                  VAL []BYTE string) 
Converts a string to a decimal integer. The procedure returns in n the value represented in string. error is set to TRUE if a nonnumeric character is found in string or if string is empty. + or a  are allowed in the first character position. n will be the value of the portion of string up to any illegal characters, with the convention that the value of an empty string is 0. error is also set to TRUE if the value of string overflows the range of INT, in this case n will contain the low order bits of the binary representation of string. error is set to FALSE in all other cases. 
Similar procedures are provided for the types INT16, INT32, and INT64. 
STRINGTOINT16 
PROC STRINGTOINT16 (BOOL Error, INT16 n, 
                    VAL []BYTE string)
As STRINGTOINT but converts to a 16bit integer. 
STRINGTOINT32 
PROC STRINGTOINT32 (BOOL Error, INT32 n, 
                    VAL []BYTE string)

As STRINGTOINT but converts to a 32bit integer. 
STRINGTOINT64 
PROC STRINGTOINT64 (BOOL Error, INT64 n, 
                    VAL []BYTE string)
As STRINGTOINT but converts to a 64bit integer. 
STRINGTOHEX 
PROC STRINGTOHEX (BOOL Error, INT n, 
                  VAL []BYTE string)
The procedure returns in n the value represented by the hexadecimal string. No `#' is allowed in the input and hex digits must be in upper case (A to F) rather than lower case (a to f). error is set to TRUE if a nonhexadecimal character is found in string, or if string is empty. n will be the value of the portion of string up to any illegal character with the convention that the value of an empty string is 0. error is also set to TRUE if the value represented by string overflows the range of INT. In this case n will contain the low order bits of the binary representation of string. In all other cases error is set to FALSE. 
Similar procedures are provided for the types HEX16, HEX32, and HEX64. 
STRINGTOHEX16 
PROC STRINGTOHEX16 (BOOL Error, INT16 n, 
                    VAL []BYTE string)
As STRINGTOHEX but converts to a 16bit integer. 
STRINGTOHEX32 
PROC STRINGTOHEX32 (BOOL Error, INT32 n, 
                    VAL []BYTE string)
As STRINGTOHEX but converts to a 32bit integer. 
STRINGTOHEX64 
PROC STRINGTOHEX64 (BOOL Error, INT64 n, 
                    VAL []BYTE string) 
As STRINGTOHEX but converts to a 64bit integer. 
STRINGTOREAL32
PROC STRINGTOREAL32 (BOOL Error, REAL32 X,  
                     VAL []BYTE string)
Converts a string to a 32bit real number. This procedure takes a string containing a decimal representation of a real number and converts it into the corresponding real value. If the value represented by string overflows the range of the type then an appropriately signed infinity is returned. Errors in the syntax of string are signalled by a `NotaNumber' being returned and error being set to TRUE. The string is scanned from the left as far as possible while the syntax is still valid. If there are any characters after the end of the longest correct string then error is set to TRUE, otherwise it is FALSE. For example if string was ``12.34E+2+1.0'' then the value returned would be 12.34  102 with error set to TRUE. 
STRINGTOREAL64 
PROC STRINGTOREAL64 (BOOL Error, REAL64 X,
                     VAL []BYTE string)
As STRINGTOREAL32 but converts to a 64bit number. 
STRINGTOBOOL 
PROC STRINGTOBOOL (BOOL Error, b, 
                   VAL []BYTE string)
Converts a string to a boolean value. The procedure returns TRUE in b if the first four characters of string are `TRUE' and FALSE if the first five characters are `FALSE'; b is undefined in other cases. TRUE is returned in error if string is not exactly `TRUE' or `FALSE'.