Go to the first, previous, next, last section, table of contents.

Real/String Conversion

The OOC Library supplies various procedures to convert between string values and numeric representation (see section Integer/String Conversion) The modules described in this chapter have procedures to convert both REAL and LONGREAL values to and from string format.

The modules RealConv and LRealConv are both low-level and the average application programmer will most likely find modules RealStr and LRealStr more interesting and useful.

(Also see section Module ConvTypes)

Please note: When using the procedures described in this chapter, keep in mind that computer representations of REAL and LONGREAL values are of finite precision. That is, only a limited number of significant digits are stored.

Module RealConv

Module RealConv provides low-level REAL/string conversions.

Constant: SigFigs
A value representing the accuracy of REALs.
Data type: ConvResults
ConvResults is a local equivalent to ConvTypes.ConvResults. This type has associated constants with the same meanings as in module ConvTypes (see section Module ConvTypes)

Constants strAllRight, strOutOfRange, strWrongFormat, and strEmpty are all valid values for ConvResults.

Procedure: ScanReal (VAR inputCh: CHAR; VAR chClass: Conv.ScanClass; VAR nextState: ConvTypes.ScanState)
Represents the start state of a finite state scanner for real numbers--assigns class of inputCh to chClass and a procedure representing the next state to nextState (see section Module ConvTypes)

Function: FormatReal (VAR str: ARRAY OF CHAR): ConvResults
Returns the format of the string value for conversion to REAL.

Function: ValueReal (VAR str: ARRAY OF CHAR): REAL
If str is well-formed, returns the value corresponding to the real number represented by the string value str. Otherwise, its behavior is undefined.

Function: LengthFloatReal (VAR real: REAL; VAR sigFigs: INTEGER): INTEGER
Returns the number of characters in the floating-point string representation of real with sigFigs significant figures. This value corresponds to the capacity of an array str which is of the minimum capacity needed to avoid truncation of the result in the call

RealStr.RealToFloat(real,sigFigs,str)

Function: LengthEngReal (VAR real: REAL; VAR sigFigs: INTEGER): INTEGER
Returns the number of characters in the floating-point engineering string representation of real with sigFigs significant figures. This value corresponds to the capacity of an array str which is of the minimum capacity needed to avoid truncation of the result in the call

RealStr.RealToEng(real,sigFigs,str)

Function: LengthFixedReal (VAR real: REAL; VAR place: INTEGER): INTEGER
Returns the number of characters in the fixed-point string representation of real rounded to the given place relative to the decimal point. This value corresponds to the capacity of an array str which is of the minimum capacity needed to avoid truncation of the result in the call

RealStr.RealToFixed(real,sigFigs,str)

Function: IsRConvException (): BOOLEAN
This function returns TRUE if the current process is in the exceptional execution state because of the raising of the RealConv exception; otherwise, returns FALSE.

Module RealStr

Module RealStr provides real number/ string conversions for REAL values. Two text formats for real numbers are supported: signed fixed-point real and signed floating-point (see section Syntax of Text Tokens)

The valid string format of a signed fixed-point real number is

Data type: ConvResults
ConvResults is a local equivalent to ConvTypes.ConvResults. This type has associated constants with the same meanings as in module ConvTypes (see section Module ConvTypes)

Constants strAllRight, strOutOfRange, strWrongFormat, and strEmpty are all valid values for ConvResults.

Procedure: StrToReal (VAR str: ARRAY OF CHAR; VAR real: REAL; VAR res: ConvResults)
This procedure converts a string to a real value. StrToReal ignores any leading spaces in str and, depending on the subsequent characters in str, the values of real and res are set as follows:

If res = strAllRight, str represents a complete signed real number in the range of REAL. The value of this number is assigned to real.

If res = strOutOfRange, str represents a complete signed real number, but its value is out of the range of REAL. MAX(REAL) or MIN(REAL) is assigned to real depending on the sign of the number.

If res = strWrongFormat, str is not in the form of a complete signed real number. The value of real is undefined.

If res = strEmpty, there are no remaining characters in str. The value of real is undefined.

Example: 

VAR stringVar: ARRAY 36 OF CHAR; 
    realVar:   REAL;
    res:       RealStr.ConvResults;
    
stringVar := "   76.54321";
RealStr.StrToReal(stringVar, realVar, res);
   => realVar = 76.54321, res = strAllRight

stringVar := " 76.543E+100";
RealStr.StrToReal(stringVar, realVar, res);
   => realVar is undefined, res = strOutOfRange

stringVar := "76_54321";
RealStr.StrToReal(stringVar, realVar, res);
   => realVar is undefined, res = strWrongFormat

stringVar := "   ";
RealStr.StrToReal(stringVar, realVar, res);
   => realVar is undefined, res = strEmpty

Procedure: RealToFloat (VAR real: REAL; VAR sigFigs: INTEGER; VAR str: ARRAY OF CHAR)
RealToFloat converts the value of real to floating-point string format and copies the possibly truncated result to str.

If the value of sigFigs is greater than 0, that number of significant digits is included. Otherwise, an implementation-defined number of significant digits is included. The decimal point is not included if there are no significant digits in the fractional part.

The number is scaled with one digit in the whole number part. A sign is included only for negative values.

Example: 

VAR stringVar: ARRAY 32 OF CHAR; 
    realVar:   REAL;
    
realVar := 3923009;
RealStr.RealToFloat(realVar, 0, stringVar);
   => stringVar = "3.923009E+6"

RealStr.RealToFloat(realVar, -1, stringVar);
   => stringVar = "3.923009E+6"

RealStr.RealToFloat(realVar, 1, stringVar);
   => stringVar = "4E+6"
RealStr.RealToFloat(realVar, 2, stringVar);
   => stringVar = "3.9E+6"
RealStr.RealToFloat(realVar, 5, stringVar);
   => stringVar = "3.9230E+6"

realVar := -39.23009;
RealStr.RealToFloat(realVar, 1, stringVar);
   => stringVar = "-4E+1"
RealStr.RealToFloat(realVar, 2, stringVar);
   => stringVar = "-3.9E+1"
RealStr.RealToFloat(realVar, 5, stringVar);
   => stringVar = "-3.9230E+1"

realVar := 0.0003923009;
RealStr.RealToFloat(realVar, 1, stringVar);
   => stringVar = "4E-4"
RealStr.RealToFloat(realVar, 2, stringVar);
   => stringVar = "3.9E-4"
RealStr.RealToFloat(realVar, 5, stringVar);
   => stringVar = "3.9230E-4"

Procedure: RealToEng (VAR real: REAL; VAR sigFigs: INTEGER; VAR str: ARRAY OF CHAR)
RealToEng converts the value of real to floating-point string format and copies the possibly truncated result to str.

If the value of sigFigs is greater than 0, that number of significant digits is included. Otherwise, an implementation-defined number of significant digits is included. The decimal point is not included if there are no significant digits in the fractional part.

The number is scaled with one to three digits in the whole number part and with an exponent that is a multiple of three. A sign is included only for negative values.

Example: 

VAR stringVar: ARRAY 32 OF CHAR; 
    realVar:   REAL;
    
realVar := -3923009;
RealStr.RealToEng(realVar, 1, stringVar);
   => stringVar = "-4E+6"
RealStr.RealToEng(realVar, 2, stringVar);
   => stringVar = "-3.9E+6"
RealStr.RealToEng(realVar, 5, stringVar);
   => stringVar = "-3.9230E+6" 

realVar := 39.23009;
RealStr.RealToEng(realVar, 1, stringVar);
   => stringVar = "40"
RealStr.RealToEng(realVar, 2, stringVar);
   => stringVar = "39"
RealStr.RealToEng(realVar, 5, stringVar);
   => stringVar = "39.230" 

realVar := 0.0003923009;
RealStr.RealToEng(realVar, 1, stringVar);
   => stringVar = "400E-6"
RealStr.RealToEng(realVar, 2, stringVar);
   => stringVar = "390E-6"
RealStr.RealToEng(realVar, 5, stringVar);
   => stringVar = "392.30E-6"

Procedure: RealToFixed (VAR real: REAL; VAR place: INTEGER; VAR str: ARRAY OF CHAR)
RealToFixed converts the value of real to fixed-point string format and copies the possibly truncated result to str.

The value is rounded to the given value of place relative to the decimal point. The decimal point is suppressed if place is less than 0.

The number will have at least one digit in the whole number part. A sign is included only for negative values.

Example: 

VAR stringVar: ARRAY 32 OF CHAR; 
    realVar:   REAL;
   
realVar := 3923009;
RealStr.RealToFixed(realVar, -5, stringVar);
   => stringVar = "3920000"  (* rounded to the ten-thousands place *)
RealStr.RealToFixed(realVar, -2, stringVar);
   => stringVar = "3923010"  (* rounded to the tens place *)
RealStr.RealToFixed(realVar, 1, stringVar);
   => stringVar = "3923009.0"
RealStr.RealToFixed(realVar, 4, stringVar);
   => stringVar = "3923009.0000" 

realVar := 3923.5;
RealStr.RealToFixed(realVar, -1, stringVar);
   => stringVar = "3924"  (* rounded to the "ones" place *)
RealStr.RealToFixed(realVar, 0, stringVar);
   => stringVar = "3924."  (* same as above, 
                        but writes a decimal point *)

realVar := -39.23009;
RealStr.RealToFixed(realVar, 1, stringVar);
   => stringVar = "-39.2"
RealStr.RealToFixed(realVar, 4, stringVar);
   => stringVar = "-39.2301"

realVar := 0.0003923009;
RealStr.RealToFixed(realVar, 1, stringVar);
   => stringVar = "0.0"
RealStr.RealToFixed(realVar, 4, stringVar);
   => stringVar = "0.0004"

Procedure: RealToStr (VAR real: REAL; VAR str: ARRAY OF CHAR)
RealToStr converts the value of real to string format and copies the possibly truncated result to str.

If the sign and magnitude of real can be shown within the capacity of str, RealToStr behaves exactly the same as RealToFixed with a number of decimal places chosen to fill exactly the remainder of str.

Otherwise, RealToStr behaves as RealToFloat with at least one significant digit. The actual number of significant digits is limited to the number that can be included together with the sign and exponent part in str.

Example: 

VAR str32Var: ARRAY 32 OF CHAR;
    str10Var: ARRAY 10 OF CHAR;
    realVar:   REAL;
    
realVar := 3.0;
RealStr.RealToStr(realVar, str32Var);
   => str32Var = "3.00000000000000000000000000000"  
RealStr.RealToStr(realVar, str10Var);
   => str10Var = "3.0000000"

realVar := 3.1;
RealStr.RealToStr(realVar, str32Var);
   => str32Var = "3.10000000000000000000000000000"  
RealStr.RealToStr(realVar, str10Var);
   => str10Var = "3.1000000"

realVar := 32923009999.;
RealStr.RealToStr(realVar, str32Var);
   => str32Var = "3923010000.00000000000000000000"
RealStr.RealToStr(realVar, str10Var);
   => str10Var = "3.9230E+9"

realVar := -39.23009999E+30;  
RealStr.RealToStr(realVar, str32Var);
   => str32Var = "-3.923010000000000000000000E+31"
RealStr.RealToStr(realVar, str10Var);
   => str10Var = "-3.92E+31"

realVar := 0.00032923009999;
RealStr.RealToStr(realVar, str32Var);
   => str32Var = "0.00032923010000000000000000000"
RealStr.RealToStr(realVar, str10Var);
   => str10Var = "3.9230E-4"

Module LRealConv

Module LRealConv provides low-level LONGREAL/string conversions.

Constant: SigFigs
A value representing the accuracy of LONGREALs.
Data type: ConvResults
ConvResults is a local equivalent to ConvTypes.ConvResults. This type has associated constants with the same meanings as in module ConvTypes (see section Module ConvTypes)

Constants strAllRight, strOutOfRange, strWrongFormat, and strEmpty are all valid values for ConvResults.

Procedure: ScanReal (VAR inputCh: CHAR; VAR chClass: Conv.ScanClass; VAR nextState: ConvTypes.ScanState)
Represents the start state of a finite state scanner for real numbers--- assigns class of inputCh to chClass and a procedure representing the next state to nextState (see section Module ConvTypes)

Function: FormatReal (VAR str: ARRAY OF CHAR): ConvResults
Returns the format of the string value for conversion to LONGREAL.

Function: ValueReal (VAR str: ARRAY OF CHAR): LONGREAL
If str is well-formed, returns the value corresponding to the real number represented by the string value str. Otherwise, its behavior is undefined.

Function: LengthFloatReal (VAR real: LONGREAL; VAR sigFigs: INTEGER): INTEGER
Returns the number of characters in the floating-point string representation of real with sigFigs significant figures. This value corresponds to the capacity of an array str which is of the minimum capacity needed to avoid truncation of the result in the call

LRealStr.RealToFloat(real,sigFigs,str)

Function: LengthEngReal (VAR real: LONGREAL; VAR sigFigs: INTEGER): INTEGER
Returns the number of characters in the floating-point engineering string representation of real with sigFigs significant figures. This value corresponds to the capacity of an array str which is of the minimum capacity needed to avoid truncation of the result in the call

LRealStr.RealToEng(real,sigFigs,str)

Function: LengthFixedReal (VAR real: LONGREAL; VAR place: INTEGER): INTEGER
Returns the number of characters in the fixed-point string representation of real rounded to the given place relative to the decimal point. This value corresponds to the capacity of an array str which is of the minimum capacity needed to avoid truncation of the result in the call

LRealStr.RealToFixed(real,sigFigs,str)

Function: IsRConvException (): BOOLEAN
This function returns TRUE if the current process is in the exceptional execution state because of the raising of the LRealConv exception; otherwise, it returns FALSE.

Module LRealStr

Please note: Because module LRealStr is very similar to module RealStr and in order to avoid redundancy, full descriptions of procedures and examples of their use are not provided in this section. Refer back to module RealStr for more information (see section Module RealStr)

Module LRealStr provides real number/ string conversions for LONGREAL values. Two text formats for real numbers are supported: signed fixed-point real and signed floating-point (see section Syntax of Text Tokens)

Data type: ConvResults
ConvResults is a local equivalent to ConvTypes.ConvResults. This type has associated constants with the same meanings as in module ConvTypes (see section Module ConvTypes)

Constants strAllRight, strOutOfRange, strWrongFormat, and strEmpty are all valid values for ConvResults.

Procedure: StrToReal (VAR str: ARRAY OF CHAR; VAR real: LONGREAL; VAR res: ConvResults)
This procedure converts a string to a real value. StrToReal ignores any leading spaces in str and, if the subsequent characters in str are in the format of a signed real number, the value is assigned to real. res is assigned a value indicating the format of str.

Procedure: RealToFloat (VAR real: LONGREAL; VAR sigFigs: INTEGER; VAR str: ARRAY OF CHAR)
RealToFloat converts the value of real to floating-point string format, with sigFigs significant digits, and copies the possibly truncated result to str.

Procedure: RealToEng (VAR real: LONGREAL; VAR sigFigs: INTEGER; VAR str: ARRAY OF CHAR)
RealToEng converts the value of real to floating-point string format, with sigFigs significant digits, and copies the possibly truncated result to str.

The number is scaled with one to three digits in the whole number part and with an exponent that is a multiple of three.

Procedure: RealToFixed (VAR real: LONGREAL; VAR place: INTEGER; VAR str: ARRAY OF CHAR)
RealToFixed converts the value of real to fixed-point string format, rounded to the given value of place relative to the decimal point, and copies the possibly truncated result to str.

The number will have at least one digit in the whole number part.

Procedure: RealToStr (VAR real: LONGREAL; VAR str: ARRAY OF CHAR)
RealToStr converts the value of real to string format and copies the possibly truncated result to str.

If the sign and magnitude of real can be shown within the capacity of str, RealToStr behaves exactly the same as RealToFixed with a number of decimal places chosen to fill exactly the remainder of str.

Otherwise, RealToStr behaves as RealToFloat with at least one significant digit. The actual number of significant digits is limited to the number that can be included together with the sign and exponent part in str.

Go to the first, previous, next, last section, table of contents.