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.
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.
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);
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.
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.
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}
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:
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.
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:
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.
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}
PROCEDURE StrToReal (str: ARRAY OF CHAR; VAR real: REAL; VAR res: ConvResults); PROCEDURE StrToReal (str: ARRAY OF CHAR; VAR real: LONGREAL; VAR res: ConvResults);
The procedure StrToReal ignores leading spaces in str and assigns values to res and real as follows:
PROCEDURE RealToFloat (real: REAL; sigFigs: CARDINAL; VAR str: ARRAY OF CHAR); PROCEDURE RealToFloat (real: LONGREAL; sigFigs: CARDINAL; VAR str: ARRAY OF CHAR);
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.
PROCEDURE RealToEng (real: REAL; sigFigs: CARDINAL; VAR str: ARRAY OF CHAR); PROCEDURE RealToEng (real: LONGREAL; sigFigs: CARDINAL; VAR str: ARRAY OF CHAR);
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.
PROCEDURE RealToFixed (real: REAL; place: INTEGER; VAR str: ARRAY OF CHAR); PROCEDURE RealToFixed (real: LONGREAL; place: INTEGER; VAR str: ARRAY OF CHAR);
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.
PROCEDURE RealToStr (real: REAL; VAR str: ARRAY OF CHAR); PROCEDURE RealToStr (real: LONGREAL; VAR str: ARRAY OF CHAR);
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.
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.
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;
The module WholeConv provides low-level string conversion procedures for values of the type INTEGER and values of the type CARDINAL.
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.
PROCEDURE FormatInt (str: ARRAY OF CHAR): ConvResults;
Module WholeConv
The function procedure FormatInt queries the format of str and returns:
FormatInt ignores any leading space characters in str.
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.
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).
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 | | |
PROCEDURE FormatCard (str: ARRAY OF CHAR): ConvResults;
Module WholeConv
The function procedure FormatCard queries the format of str and returns:
FormatCard ignores any leading space characters in str.
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.
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).
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.
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.
PROCEDURE ScanReal (inputCh: CHAR; VAR chClass: ConvTypes.ScanClass; VAR nextState: ConvTypes.ScanState); PROCEDURE ScanReal (inputCh: CHAR; VAR chClass: ConvTypes.ScanClass; VAR nextState: ConvTypes.ScanState);
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 | | |
PROCEDURE FormatReal (str: ARRAY OF CHAR): ConvResults; PROCEDURE FormatReal (str: ARRAY OF CHAR): ConvResults;
The function procedure FormatReal queries the format of str and returns:
FormatReal ignores any leading space characters in str.
PROCEDURE ValueReal (str: ARRAY OF CHAR): REAL; PROCEDURE ValueReal (str: ARRAY OF CHAR): LONGREAL;
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.
PROCEDURE LengthFloatReal (real: REAL; sigFigs: CARDINAL): CARDINAL; PROCEDURE LengthFloatReal (real: LONGREAL; sigFigs: CARDINAL): CARDINAL;
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).
PROCEDURE LengthEngReal (real: REAL; sigFigs: CARDINAL): CARDINAL; PROCEDURE LengthEngReal (real: LONGREAL; sigFigs: CARDINAL): CARDINAL;
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).
PROCEDURE LengthFixedReal (real: REAL; place: INTEGER): CARDINAL; PROCEDURE LengthFixedReal (real: LONGREAL; place: INTEGER): CARDINAL;
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).
PROCEDURE IsRConvException (): BOOLEAN; PROCEDURE IsRConvException (): BOOLEAN;
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.