Super Prev Next

String Conversions

The string conversions library allows the conversion of the values of numeric data types to and from character string representations. The modules WholeStr, RealStr, and LongStr provide simple high-level facilities for converting to and from strings and whole number and real number data types. Low-level facilities are provided by the corresponding modules WholeConv, RealConv, and LongConv. Common data types and values that are used in the definition modules are defined by the module ConvTypes.

The formats for string conversions correspond to those for numeric input and output, except that the numeric output routines provide for (right) alignment in a specified field width | see 9.2.2.2 and 9.2.2.3.


Super Prev Next

Common Data Types

The module ConvTypes defines types and values that are used in the high-level and low-level string conversion definition modules. Where appropriate, the conversion modules define types in terms of those defined in ConvTypes. Direct import from this module is not normally necessary in modules that are clients of the high-level conversion modules.


Super Prev Next

Module ConvTypes

The module ConvTypes defines the enumeration type ConvResults with values for expressing the format of strings that are interpreted as representing values of numeric data types. The module also defines the types ScanClass and ScanState, which the low-level conversion modules use in the definition of procedures that control lexical scanning.

TYPE
  ConvResults =     (* Values of this type are used
                       to express the format of a string: *)
  (
    strAllRight,    (* the string format is correct
                       for the corresponding conversion *)
    strOutOfRange,  (* the string is well-formed but the value
                       cannot be represented *)
    strWrongFormat, (* the string is in the wrong format
                       for the conversion *)
    strEmpty        (* the given string is empty *)
  );

  ScanClass =  (* Values of this type are used to classify input
                  to finite state scanners: *)
  (
    padding,   (* a leading or padding character at this point
                  in the scan - ignore it *)
    valid,     (* a valid character at this point
                  in the scan - accept it *)
    invalid,   (* an invalid character at this point
                  in the scan - reject it *)
    terminator (* a terminating character at this point
                  in the scan (not part of token) *)
  );

  ScanState = (* The type of lexical scanning
                 control procedures *)
   PROCEDURE (CHAR, VAR ScanClass, VAR ScanState);


Super Prev Next

High-Level String Conversion Modules

Separate high-level string conversion modules are defined for the whole number types (INTEGER and CARDINAL), and for the real number types (REAL and LONGREAL). These all use decimal notation.

In calls of procedures converting from strings, the source parameter str is assumed to contain a string value (which is terminated by the string terminator character if the length of the string is less than the capacity of the array). While leading spaces are ignored, the entire remainder of the string has to be in the correct format for the conversion to take place.

In calls of procedures converting to strings, the destination parameter str is assigned a string value (which is terminated by the string terminator character if the length of the string is less than the capacity of the array). If the destination parameter is of insufficient capacity, the string is truncated. Users may determine whether truncation will occur by using procedures such as LengthCard from the low-level string conversion modules | see 9.5.3.1.2.

NOTE:

The string conversion procedures may be used with strings read by STextIO.ReadToken or TextIO.ReadToken, if it is required that entire space-character delimited tokens are in the correct format | see 9.2.2.1.2.


Super Prev Next

EXAMPLE - Conversion of strings read by ReadToken

This example shows how space-character delimited tokens that cannot be converted to values of type CARDINAL can be replaced by descriptive text:

firstOnLine := TRUE;
STextIO.ReadToken(inStr);
WHILE SIOResult.ReadResult() <> SIOResult.endOfInput DO
  WholeStr.StrToCard(inStr, inCard, inRes);
  CASE inRes OF
  | ConvTypes.strAllRight .. ConvTypes.strWrongFormat:
     IF firstOnLine THEN
        firstOnLine := FALSE
     ELSE
        STextIO.WriteString(" ")
     END
  | ConvTypes.strEmpty:
  firstOnLine := TRUE;
  STextIO.SkipLine
  END;
  CASE inRes OF
  | ConvTypes.strAllRight:
     STextIO.WriteString(inStr)
  | ConvTypes.strOutOfRange:
     STextIO.WriteString("out-of-range")
  | ConvTypes.strWrongFormat:
     STextIO.WriteString("wrong-format")
  | ConvTypes.strEmpty:
     STextIO.WriteLn
  END;
  STextIO.ReadToken(inStr)
END;

It is assumed here that the capacity of the character array variable inStr is sufficient to accommodate the longest token in the input stream.


Super Prev Next

Module WholeStr

The module WholeStr provides procedures for the conversion of values of the type INTEGER and the type CARDINAL to and from strings.

The string form of a signed whole number is

["+" | "-"], decimal digit, {decimal digit}

The string form of an unsigned whole number is

decimal digit, {decimal digit}


Super Prev Next

StrToInt - Convert string to INTEGER

PROCEDURE StrToInt (str: ARRAY OF CHAR;
                    VAR int: INTEGER;
                    VAR res: ConvResults);

Module WholeStr

The procedure StrToInt ignores leading spaces in str and assigns values to int and res as follows:

strAllRight
if the remainder of str represents a complete signed whole number in the range of the type INTEGER; the value of this number is assigned to int;

strOutOfRange
if the remainder of str represents a complete signed whole number but its value is out of the range of the type INTEGER; the value MAX(INTEGER) or MIN(INTEGER) is assigned to int according to the sign of the number;

strWrongFormat
if there are remaining characters in str but these are not in the form of a complete signed whole number; the value of int is not defined;

strEmpty
if there are no remaining characters in str | the value of int is not defined.


Super Prev Next

IntToStr - Convert INTEGER to string

PROCEDURE IntToStr (int: INTEGER; VAR str: ARRAY OF CHAR);

Module WholeStr

The procedure IntToStr assigns to str the possibly truncated string corresponding to the value of int. A sign is included only for negative values.


Super Prev Next

StrToCard - Convert string to CARDINAL

PROCEDURE StrToCard (str: ARRAY OF CHAR;
                     VAR card: CARDINAL;
                     VAR res: ConvResults);

Module WholeStr

The procedure StrToCard ignores leading spaces in str and assigns values to card and res as follows:

strAllRight
if the remainder of str represents a complete unsigned whole number in the range of the type CARDINAL; the value of this number is assigned to card;

strOutOfRange
if the remainder of str represents a complete unsigned whole number but its value is out of the range of the type CARDINAL; the value MAX(CARDINAL) is assigned to card;

strWrongFormat
if there are remaining characters in str but these are not in the form of a complete unsigned whole number; the value of card is not defined;

strEmpty
if there are no remaining characters in str; the value of card is not defined.


Super Prev Next

CardToStr - Convert CARDINAL to string

PROCEDURE CardToStr (card: CARDINAL; VAR str: ARRAY OF CHAR);

Module WholeStr

The procedure CardToStr assigns to str the possibly truncated string corresponding to the value of card.


Super Prev Next

Modules RealStr and LongStr

The modules RealStr and LongStr provide procedures for the conversion of real numbers to and from strings. In the case of RealStr, real number parameters are of the type REAL. In the case of LongStr, real number parameters are of the type LONGREAL.

The semantics of the two modules is the same, except that when module RealStr refers to the pervasive type REAL, the corresponding procedure in LongStr refers to the pervasive type LONGREAL.

NOTE:

The above statement is merely to avoid needless repetition of the semantics for LongStr.

The string form of a signed fixed-point real number is

["+" | "-"], decimal digit, {decimal digit},
[".", {decimal digit}]

The string form of a signed floating-point real number is

signed fixed-point real number,
"E"|"e", ["+" | "-"], decimal digit, {decimal digit}


Super Prev Next

StrToReal - Convert string to real

PROCEDURE StrToReal (str: ARRAY OF CHAR;
                     VAR real: REAL;
                     VAR res: ConvResults);
PROCEDURE StrToReal (str: ARRAY OF CHAR;
                     VAR real: LONGREAL;
                     VAR res: ConvResults);

Modules: RealStr, LongStr

The procedure StrToReal ignores leading spaces in str and assigns values to res and real as follows:

strAllRight
if the remainder of str represents a complete signed real number in the range of the type of real; the value of this number is assigned to real;

strOutOfRange
if the remainder of str represents a complete signed real number but its value is out of the range of the type of real; the maximum or minimum value of the type of real is assigned to real according to the sign of the number;

strWrongFormat
if there are remaining characters in str but these are not in the form of a complete signed real number; the value of real is not defined;

strEmpty
if there are no remaining characters in str; the value of real is not defined.


Super Prev Next

RealToFloat - Convert real to string (float notation)

PROCEDURE RealToFloat (real: REAL;
                       sigFigs: CARDINAL;
                       VAR str: ARRAY OF CHAR);
PROCEDURE RealToFloat (real: LONGREAL;
                       sigFigs: CARDINAL;
                       VAR str: ARRAY OF CHAR);

Modules: RealStr, LongStr

The procedure RealToFloat assigns to str the possibly truncated string corresponding to the value of real in floating-point form. A sign is included only for negative values. One significant digit is included in the whole number part. The signed exponent part is included only if the exponent value is not 0. 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.


Super Prev Next

RealToEng - Convert real to string (eng. notation)

PROCEDURE RealToEng (real: REAL;
                     sigFigs: CARDINAL;
                     VAR str: ARRAY OF CHAR);
PROCEDURE RealToEng (real: LONGREAL;
                     sigFigs: CARDINAL;
                     VAR str: ARRAY OF CHAR);

Modules: RealStr, LongStr

The procedure RealToEng behaves like the procedure RealToFloat except that the number is scaled with one to three digits in the whole number part and with an exponent that is a multiple of three.


Super Prev Next

RealToFixed - Convert real to string (fixed notation)

PROCEDURE RealToFixed (real: REAL;
                       place: INTEGER;
                       VAR str: ARRAY OF CHAR);
PROCEDURE RealToFixed (real: LONGREAL;
                       place: INTEGER;
                       VAR str: ARRAY OF CHAR);

Modules: RealStr, LongStr

The procedure RealToFixed assigns to str the possibly truncated string corresponding to the value of real in fixed-point form. A sign is included only for negative values. At least one digit is included in the whole number part. 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.


Super Prev Next

RealToStr - Convert real to string (auto notation)

PROCEDURE RealToStr (real: REAL; VAR str: ARRAY OF CHAR);
PROCEDURE RealToStr (real: LONGREAL; VAR str: ARRAY OF CHAR);

Modules: RealStr, LongStr

If the sign and magnitude of real can be shown within the capacity of str, the call RealToStr(real,str) behaves like the call RealToFixed(real,place,str), with a value of place chosen to fill exactly the remainder of str. Otherwise, the call behaves as the call RealToFloat(real,sigFigs,str), with a value of sigFigs of at least one, but otherwise limited to the number of significant digits that can be included together with the sign and exponent part in str.


Super Prev Next

Low-Level String Conversion Modules

Separate low-level string conversion modules are defined for the whole number types (INTEGER and CARDINAL), and for the real number types (REAL and LONGREAL). These all use decimal notation.

Procedures are defined to return the length of the string that is required to represent a given value, to return the format of a given string, to return the value of a string known to be in the correct format for conversion, and to allow control of lexical scanning of character sequences.

NOTE:

The types designated by ConvTypes.ScanClass and ConvTypes.ScanState are not given aliases in the low-level conversion modules. This is because clients of a separate finite state interpreter module need to refer only to procedures such as WholeConv.ScanInt, which represent the start state, and not to the types themselves.


Super Prev Next

EXAMPLE - Use of ScanInt

The following procedure uses WholeConv.ScanInt to locate the position of the first character in a string that follows any leading spaces and to locate the position of the first character that is not part of an integer. These positions will coincide if the string does not contain an integer after any leading spaces, and will be equal to the string length if no such character is contained in the string.

PROCEDURE FindInt(str: ARRAY OF CHAR; VAR first, next: CARDINAL);
VAR
  ch: CHAR;
  len, index: CARDINAL;
  state: ConvTypes.ConvState;
  class: ConvTypes.ConvClass;
BEGIN
  len := LENGTH(str);
  index := 0;
  first := len;
  state := WholeConv.ScanInt;
  LOOP
    IF index = len THEN EXIT END;
    state(str[index], class, state);
    CASE class OF
    | ConvTypes.padding:
    | ConvTypes.valid:
      IF index < first THEN first := index END;
    | ConvTypes.invalid, ConvTypes.terminator:
      EXIT
    END;
    INC(index)
  END;
  next := index
END FindInt;


Super Prev Next

Module WholeConv

The module WholeConv provides low-level string conversion procedures for values of the type INTEGER and values of the type CARDINAL.


Super Prev Next

ScanInt - Scan one character of INTEGER

PROCEDURE ScanInt (inputCh: CHAR;
                   VAR chClass: ConvTypes.ScanClass;
                   VAR nextState: ConvTypes.ScanState);

Module WholeConv

The procedure ScanInt assigns values to chClass and nextState depending upon the value of inputCh as shown in the following table:

Procedure inputCh chClass nextState
a procedure with
behaviour of
ScanInt space padding ScanInt
sign valid S
decimal digit valid W
other invalid ScanInt
S decimal digit valid W
other invalid S
W decimal digit valid W
other terminator |

NOTE:

The procedure ScanInt corresponds to the start state of a finite state machine to scan for a character sequence that forms a signed whole number. Like ScanCard and the corresponding procedures in the other low-level string conversion modules, it may be used to control the actions of a finite state interpreter. As long as the value of chClass is other than terminator or invalid, the interpreter should call the procedure whose value is assigned to nextState by the previous call, supplying the next character from the sequence to be scanned. It may be appropriate for the interpreter to ignore characters classified as invalid, and proceed with the scan. This would be the case, for example, with interactive input, if only valid characters are being echoed in order to give interactive users an immediate indication of badly-formed data. If the character sequence ends before one is classified as terminator, the string-terminator character should be supplied as input to the finite state scanner. If the preceding character sequence formed a complete number, the string-terminator is classified as terminator, otherwise it is classified as invalid.


Super Prev Next

FormatInt - Query INTEGER format

PROCEDURE FormatInt (str: ARRAY OF CHAR): ConvResults;

Module WholeConv

The function procedure FormatInt queries the format of str and returns:

strAllRight
if str has a value representing a complete signed whole number that is in the range of the type INTEGER;

strOutOfRange
if str has a value representing a complete signed whole number that is not in the range of INTEGER;

strWrongFormat
if str has a value with remaining characters that do not form a complete signed whole number;

strEmpty
if str has a value with no remaining characters;

FormatInt ignores any leading space characters in str.


Super Prev Next

ValueInt - Query INTEGER value

PROCEDURE ValueInt (str: ARRAY OF CHAR): INTEGER;

Module WholeConv

If str has a value representing a signed whole number, the function procedure ValueInt returns the INTEGER value that corresponds to that number. Otherwise, the WholeConv exception is raised.


Super Prev Next

LengthInt - Query INTEGER length

PROCEDURE LengthInt (int: INTEGER): CARDINAL;

Module WholeConv

The function procedure LengthInt returns the number of characters in the string representation of the value of int.

NOTE:

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 WholeStr.IntToStr(int,str).


Super Prev Next

ScanCard - Scan one character of CARDINAL

PROCEDURE ScanCard (inputCh: CHAR;
                    VAR chClass: ConvTypes.ScanClass;
                    VAR nextState: ConvTypes.ScanState);

Module WholeConv

The procedure ScanCard assigns values to chClass and nextState depending upon the value of inputCh as shown in the following table:

Procedure inputCh chClass nextState
a procedure with
behaviour of
ScanCard space padding ScanCard
decimal digit valid W
other invalid ScanCard
W decimal digit valid W
other terminator |


Super Prev Next

FormatCard - Query CARDINAL format

PROCEDURE FormatCard (str: ARRAY OF CHAR): ConvResults;

Module WholeConv

The function procedure FormatCard queries the format of str and returns:

strAllRight
if str has a value representing a complete unsigned whole number that is in the range of the type CARDINAL;

strOutOfRange
if str has a value representing a complete unsigned whole number that is not in the range of CARDINAL;

strWrongFormat
if str has a value with remaining characters that do not form a complete unsigned whole number;

strEmpty
if str has a value with no remaining characters;

FormatCard ignores any leading space characters in str.


Super Prev Next

ValueCard - Query CARDINAL value

PROCEDURE ValueCard (str: ARRAY OF CHAR): CARDINAL;

Module WholeConv

If str has a value representing an unsigned whole number, the function procedure ValueCard returns the CARDINAL value that corresponds to that number. Otherwise, the WholeConv exception is raised.


Super Prev Next

LengthCard - Query CARDINAL length

PROCEDURE LengthCard (card: CARDINAL): CARDINAL;

Module WholeConv

The function procedure LengthCard returns the number of characters in the string representation of the value of card.

NOTE:

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 WholeStr.CardToStr(card,str).


Super Prev Next

IsWholeConvException - Query exceptional state

PROCEDURE IsWholeConvException (): BOOLEAN;

Module WholeConv

The function procedure IsWholeConvException returns TRUE if the calling coroutine is in the state of exceptional execution because of the raising of the WholeConv exception, and FALSE otherwise.


Super Prev Next

Modules RealConv and LongConv

The modules RealConv and LongConv provide low-level string conversion procedures for values of the type REAL and values of the type LONGREAL. In the case of RealConv, real number parameters are of the type REAL. In the case of LongConv, real number parameters are of the type LONGREAL.

The semantics of the two modules are the same, except that when module RealConv refers to the pervasive type REAL, the corresponding procedure in LongConv refers to the pervasive type LONGREAL.

NOTE:

The above statement is merely to avoid needless repetition of the semantics for LongConv.


Super Prev Next

ScanReal - Scan one character of real

PROCEDURE ScanReal (inputCh: CHAR;
                    VAR chClass: ConvTypes.ScanClass;
                    VAR nextState: ConvTypes.ScanState);
PROCEDURE ScanReal (inputCh: CHAR;
                    VAR chClass: ConvTypes.ScanClass;
                    VAR nextState: ConvTypes.ScanState);

Modules: RealConv, LongConv

The procedure ScanReal assigns values to chClass and nextState depending upon the value of inputCh as shown in the following table:

Procedure inputCh chClass nextState
a procedure with
behaviour of
ScanReal space padding ScanReal
sign valid RS
decimal digit valid P
other invalid ScanReal
RS decimal digit valid P
other invalid RS
P decimal digit valid P
"." valid F
"E" valid E
other terminator |
F decimal digit valid F
"E" valid E
other terminator |
E sign valid SE
decimal digit valid WE
other invalid E
SE decimal digit valid WE
other invalid SE
WE decimal digit valid WE
other terminator |


Super Prev Next

FormatReal - Query real format

PROCEDURE FormatReal (str: ARRAY OF CHAR): ConvResults;
PROCEDURE FormatReal (str: ARRAY OF CHAR): ConvResults;

Modules: RealConv, LongConv

The function procedure FormatReal queries the format of str and returns:

strAllRight
if str has a value representing a complete signed real number that is in the range of the real number type corresponding to the module;

strOutOfRange
if str has a value representing a complete signed real number that is not in the range of the real number type corresponding to the module;

strWrongFormat
if str has a value with remaining characters that do not form a complete signed real number;

strEmpty
if str has a value with no remaining characters;

FormatReal ignores any leading space characters in str.


Super Prev Next

ValueReal - Query real value

PROCEDURE ValueReal (str: ARRAY OF CHAR): REAL;
PROCEDURE ValueReal (str: ARRAY OF CHAR): LONGREAL;

Modules: RealConv, LongConv

If str has a value representing a real number, the function procedure ValueReal(str) returns the REAL (or LONGREAL) value that corresponds most closely to that number. Otherwise, an exception is raised.


Super Prev Next

LengthFloatReal - Query float length

PROCEDURE LengthFloatReal (real: REAL;
                           sigFigs: CARDINAL): CARDINAL;
PROCEDURE LengthFloatReal (real: LONGREAL;
                           sigFigs: CARDINAL): CARDINAL;

Modules: RealConv, LongConv

The function procedure LengthFloatReal returns the number of characters in the floating-point string representation of the value of real when using sigFigs significant figures.

NOTE:

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) (in the case of RealConv.LengthFloatReal) or the call LongStr.RealToFloat(real,sigFigs,str) (in the case of LongConv.LengthFloatReal).


Super Prev Next

LengthEngReal - Query engineering length

PROCEDURE LengthEngReal (real: REAL;
                         sigFigs: CARDINAL): CARDINAL;
PROCEDURE LengthEngReal (real: LONGREAL;
                         sigFigs: CARDINAL): CARDINAL;

Modules: RealConv, LongConv

The function procedure LengthEngReal returns the number of characters in the floating-point engineering string representation of the value of real when using sigFigs significant figures.

NOTE:

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) (in the case of RealConv.LengthEngReal) or the call LongStr.RealToEng(real,sigFigs,str) (in the case of LongConv.LengthEngReal).


Super Prev Next

LengthFixedReal - Query fixed length

PROCEDURE LengthFixedReal (real: REAL;
                           place: INTEGER): CARDINAL;
PROCEDURE LengthFixedReal (real: LONGREAL;
                           place: INTEGER): CARDINAL;

Modules: RealConv, LongConv

The function procedure LengthFixedReal returns the number of characters in the fixed-point string representation of the value of real when rounded to the place relative to the decimal point given by the value of place.

NOTE:

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,place,str) (in the case of RealConv.LengthFixedReal) or the call LongStr.RealToFixed(real,place,str) (in the case of LongConv.LengthFixedReal).


Super Prev Next

IsRConvException - Query exceptional state

PROCEDURE IsRConvException (): BOOLEAN;
PROCEDURE IsRConvException (): BOOLEAN;

Modules: RealConv, LongConv

If the calling coroutine is in the state of exceptional execution because of the raising of the RealConv exception, the function procedure RealConv.IsRConvException returns TRUE; otherwise it returns FALSE.

If the calling coroutine is in the state of exceptional execution because of the raising of the LongConv exception, the function procedure LongConv.IsRConvException returns TRUE; otherwise it returns FALSE.