String conversion library - <tt>convert.lib</tt>

1.8: String conversion library

These files have been made freely available by SGS-Thomson and may not be used to generate commercial products without explicit permission and agreed licensing terms OR placed in a public archive or given to third parties without explicit written permission from SGS-Thomson in Bristol.
Tony Debling, SGS-Thomson Microelectronics Ltd, 1000 Aztec West, Almondsbury, Bristol BS12 4SQ, England. June 7, 1995.
Converted to HTML via RTFtoHTML, PERL5 and by hand by Dave Beckett <D.J.Beckett@ukc.ac.uk>.

WARNING: This has been converted from RTF format and may have mistakes compared to the printed version. If you find any in this file, please send them to me, and I will update it.

Dave Beckett <D.J.Beckett@ukc.ac.uk>

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 16-bit integers.

INT32TOSTRING

PROC INT32TOSTRING (INT len, []BYTE string, VAL INT32 n)

As INTTOSTRING but for 32-bit integers.

INT64TOSTRING

PROC INT64TOSTRING (INT len, []BYTE string, VAL INT64 n)

As INTTOSTRING but for 64-bit 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 4-bit 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 16-bit integers.

HEX32TOSTRING

PROC HEX32TOSTRING (INT len, []BYTE string, VAL INT32 n)

As HEXTOSTRING but for 32-bit integers.

HEX64TOSTRING

PROC HEX64TOSTRING (INT len, []BYTE string, VAL INT64 n)

As HEXTOSTRING but for 64-bit integers.

REAL32TOSTRING

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

Converts a 32-bit 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.

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 non-zero, or greater than 10^(9) (for REAL32), or greater than 10^(17) (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 `Not-a-Number' or infinity then the string will contain one of the following: `Inf', `-Inf' or `NaN', (excluding the quotes).

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 `Not-a-Number' 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.

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 `Not-a-Number' 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 64-bit 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 non-numeric 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 16-bit integer.

STRINGTOINT32

PROC STRINGTOINT32 (BOOL Error, INT32 n, VAL []BYTE string)

As STRINGTOINT but converts to a 32-bit integer.

STRINGTOINT64

PROC STRINGTOINT64 (BOOL Error, INT64 n, VAL []BYTE string)

As STRINGTOINT but converts to a 64-bit 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 non-hexadecimal 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 16-bit integer.

STRINGTOHEX32

PROC STRINGTOHEX32 (BOOL Error, INT32 n, VAL []BYTE string)

As STRINGTOHEX but converts to a 32-bit integer.

STRINGTOHEX64

PROC STRINGTOHEX64 (BOOL Error, INT64 n, VAL []BYTE string)

As STRINGTOHEX but converts to a 64-bit integer.

STRINGTOREAL32

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

Converts a string to a 32-bit 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 `Not-a-Number' 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 10^(2 )with error^( )set to^( )TRUE^(. )

STRINGTOREAL64

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

As STRINGTOREAL32 but converts to a 64-bit 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'.

1.8: String conversion library

Library: convert.lib

Procedure definitions

Library: `convert.lib`