DEFINITION MODULE IOFormat;

CONST
    maxFormatStrSize = 12;

(* The EBNF of a format string is as follows:
    formatStr : wholeNumFmtStr | realNumFmtStr ;
    wholeNumFmtStr : '"' wholeNumFmtChr ( ':' leading ( ':' padding fieldWidth )? )? '"' ;
    wholeNumFmtChr : 'N' | '*' | 'x' | 'H' ;
    realNumFmtStr  : '"' realNumFmtChr ( ':' leading  ( ':' trailing ( ':' padding fieldWidth )? )? )? '"' ;
    realNumFmtChr : 'N' | '*' | 'E' ;
    leading : digit digit? ;
    trailing : digit  digit? ;
    padding : 'L' | 'R' ;
    fieldWidth : digit digit? digit? ; *)

PROCEDURE SetFormatStr( VAR s : ARRAY OF CHAR; fmt : CHAR; leading, trailing : CARDINAL; width : INTEGER );
 (* Composes a format string from the specified parameters and assigns it to s.
    A negative value for width means left padding, a positive value means right padding.
    fmt must be any of 'N', '*', 'x' or 'H'. leading and trailing must be a value between 0 and 99.
    width must greater than -999 and less than 999.
    An empty string is assigned to s if any argument is out of range or if the size of s is insufficient. *)

PROCEDURE FormatChr( s : ARRAY OF CHAR ) : CHAR;
 (* Returns the format char in format string s.
    Returns ASCII.NUL if no valid format char is contained in s. *)

PROCEDURE LeadingDigits( s : ARRAY OF CHAR ) : CARDINAL;
 (* Returns the value of field leading in format string s.
    Returns zero if no valid leading value is contained in s. *)

PROCEDURE TrailingDigits( s : ARRAY OF CHAR ) : CARDINAL;
 (* Returns the value of field trailing in format string s.
    Returns zero if no valid trailing value is contained in s. *)

PROCEDURE Padding( s : ARRAY OF CHAR ) : CHAR;
 (* Returns the padding sense field in format string s.
    Returns ASCII.NUL if no padding sense is contained in s. *)

PROCEDURE FieldWidth( s : ARRAY OF CHAR ) : INTEGER;
 (* Returns the value of field width in format string s.
    Returns zero if no valid width value is contained in s.
    A negative value for width means left padding, a positive value means right padding. *)

END IOFormat.