DEFINITION MODULE Conversion;

(* Conversions between pervasive numeric types and strings *)

TYPE
  ConvResults = ( strAllRight, strOutOfRange, strWrongFormat, strEmpty );

(* Conversions between INTEGER and strings *)

(* the string form of a signed whole number is ["+" | "-"], decimal digit, {decimal digit} *)

PROCEDURE StrToInt (str: ARRAY OF CHAR; VAR int: INTEGER; VAR res: ConvResults);
  (* Ignores any leading spaces in str. If the subsequent characters in str are in the format
     of a signed whole number, assigns a corresponding value to int. Assigns a value indicating
     the format of str to res. *)

PROCEDURE IntToStr (int: INTEGER; VAR str: ARRAY OF CHAR);
  (* Converts the value of int to string form and copies the possibly truncated result to str. *)

(* Conversions between CARDINAL and strings *)

(* the string form of an unsigned whole number is decimal digit, {decimal digit} *)

PROCEDURE StrToCard (str: ARRAY OF CHAR; VAR card: CARDINAL; VAR res: ConvResults);
  (* Ignores any leading spaces in str. If the subsequent characters in str are in the format of an
     unsigned whole number, assigns a corresponding value to card. Assigns a value indicating
     the format of str to res.  *)

PROCEDURE CardToStr (card: CARDINAL; VAR str: ARRAY OF CHAR);
  (* Converts the value of card to string form and copies the possibly truncated result to str. *)

(* Conversions between REAL and strings *)

(* 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", ["+" | "-"], decimal digit, {decimal digit} *)

PROCEDURE StrToReal (str: ARRAY OF CHAR; VAR real: REAL; VAR res: ConvResults);
  (* Ignores any leading spaces in str. If the subsequent characters in str are in the format of
     a signed real number, assigns a corresponding value to real. Assigns a value indicating
     the format of str to res.  *)

PROCEDURE RealToFloat (real: REAL; sigFigs: CARDINAL; VAR str: ARRAY OF CHAR);
  (* Converts the value of real to floating-point string form, with sigFigs significant figures,
     and copies the possibly truncated result to str. *)

PROCEDURE RealToEng (real: REAL; sigFigs: CARDINAL; VAR str: ARRAY OF CHAR);
  (* Converts the value of real to floating-point string form, with sigFigs significant figures,
     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 (real: REAL; place: INTEGER; VAR str: ARRAY OF CHAR);
  (* Converts the value of real to fixed-point string form, rounded to the given place relative to
     the decimal point, and copies the possibly truncated result to str. *)

PROCEDURE RealToStr (real: REAL; VAR str: ARRAY OF CHAR);
  (* Converts the value of real as RealToFixed if the sign and magnitude can be shown within the
     capacity of str, or otherwise as RealToFloat, and copies the possibly truncated result to str.
     The number of places or significant digits are implementation-defined. *)

(* Conversions between LONGREAL and strings *)

(* 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", ["+" | "-"], decimal digit, {decimal digit} *)

PROCEDURE StrToReal (str: ARRAY OF CHAR; VAR real: LONGREAL; VAR res: ConvResults);
  (* Ignores any leading spaces in str. If the subsequent characters in str are in the format
     of a signed real number, assigns a corresponding value to real. Assigns a value indicating
     the format of str to res. *)

PROCEDURE RealToFloat (real: LONGREAL; sigFigs: CARDINAL; VAR str: ARRAY OF CHAR);
  (* Converts the value of real to floating-point string form, with sigFigs significant figures,
     and copies the possibly truncated result to str. *)

PROCEDURE RealToEng (real: LONGREAL; sigFigs: CARDINAL; VAR str: ARRAY OF CHAR);
  (* Converts the value of real to floating-point string form, with sigFigs significant figures,
     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 (real: LONGREAL; place: INTEGER; VAR str: ARRAY OF CHAR);
  (* Converts the value of real to fixed-point string form, rounded to the given place relative to
     the decimal point, and copies the possibly truncated result to str. *)

PROCEDURE RealToStr (real: LONGREAL; VAR str: ARRAY OF CHAR);
  (* Converts the value of real as RealToFixed if the sign and magnitude can be shown within the
     capacity of str, or otherwise as RealToFloat, and copies the possibly truncated result to str.
     The number of places or significant digits depend on the capacity of str. *)

END Conversion.