Appendix 8--ISO Utility and Information Modules

A8.1 Characters and Strings

DEFINITION MODULE CharClass;

  (* Classification of values of the type CHAR *)

PROCEDURE IsNumeric (ch: CHAR): BOOLEAN;
  (* Returns TRUE if and only if ch is classified as a numeric character *)

PROCEDURE IsLetter (ch: CHAR): BOOLEAN;
  (* Returns TRUE if and only if ch is classified as a letter *)

PROCEDURE IsUpper (ch: CHAR): BOOLEAN;
  (* Returns TRUE if and only if ch is classified as an upper case letter *)

PROCEDURE IsLower (ch: CHAR): BOOLEAN;
  (* Returns TRUE if and only if ch is classified as a lower case letter *)

PROCEDURE IsControl (ch: CHAR): BOOLEAN;
  (* Returns TRUE if and only if ch represents a control function *)

PROCEDURE IsWhiteSpace (ch: CHAR): BOOLEAN;
  (* Returns TRUE if and only if ch represents a space character or a format effector *)

END CharClass.

DEFINITION MODULE Strings;

(* Facilities for manipulating strings *)

TYPE
  String1 = ARRAY [0..0] OF CHAR;
    (* String1 is provided for constructing a value of a single-character string type from a single character value in order to pass CHAR values to ARRAY OF CHAR parameters.
    *)

PROCEDURE Length (stringVal: ARRAY OF CHAR): CARDINAL;
  (* Returns the length of stringVal (the same value as would be returned by the  pervasive function LENGTH).
  *)

(* The following seven procedures construct a string value, and attempt to assign it to a variable parameter.  They all have the property that if the length of the constructed string value exceeds the capacity of the variable parameter, a truncated value is assigned, while if the length of the constructed string value is less than the capacity of the variable parameter, a string terminator is appended before assignment is performed. *)

PROCEDURE Assign (source: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR);
  (* Copies source to destination *)

PROCEDURE Extract (source: ARRAY OF CHAR; startIndex, numberToExtract: CARDINAL;  VAR destination: ARRAY OF CHAR);
  (* Copies at most numberToExtract characters from source to destination, starting at position startIndex in source. *)

PROCEDURE Delete (VAR stringVar: ARRAY OF CHAR; startIndex, numberToDelete: CARDINAL);
  (* Deletes at most numberToDelete characters from stringVar, starting at position startIndex. *)

PROCEDURE Insert (source: ARRAY OF CHAR; startIndex: CARDINAL;
                  VAR destination: ARRAY OF CHAR);
  (* Inserts source into destination at position startIndex *)

PROCEDURE Replace (source: ARRAY OF CHAR; startIndex: CARDINAL;
                     VAR destination: ARRAY OF CHAR);
  (* Copies source into destination, starting at position startIndex. Copying stops when all of source has been copied, or when the last character of the string value in destination has been replaced.  *)

PROCEDURE Append (source: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR);
  (* Appends source to destination. *)

PROCEDURE Concat (source1, source2: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR);
  (* Concatenates source2 onto source1 and copies the result into destination. *)

(* The following predicates provide for pre-testing of the operation-completion conditions for the procedures above. *)

PROCEDURE CanAssignAll (sourceLength: CARDINAL; VAR destination: ARRAY OF CHAR): BOOLEAN;
  (* Returns TRUE if a number of characters, indicated by sourceLength, will fit into destination; otherwise returns FALSE. *)

PROCEDURE CanExtractAll (sourceLength, startIndex, numberToExtract: CARDINAL; VAR destination: ARRAY OF CHAR): BOOLEAN;
  (* Returns TRUE if there are numberToExtract characters starting at startIndex and within the sourceLength of some string, and if the capacity of destination is sufficient to hold numberToExtract characters; otherwise returns FALSE. *)

PROCEDURE CanDeleteAll (stringLength, startIndex, numberToDelete: CARDINAL): BOOLEAN;
  (* Returns TRUE if there are numberToDelete characters starting at startIndex and within the stringLength of some string; otherwise returns FALSE. *)

PROCEDURE CanInsertAll (sourceLength, startIndex: CARDINAL;
                        VAR destination: ARRAY OF CHAR): BOOLEAN;
  (* Returns TRUE if there is room for the insertion of sourceLength characters from some string into destination starting at startIndex; otherwise returns FALSE. *)

PROCEDURE CanReplaceAll (sourceLength, startIndex: CARDINAL;
                         VAR destination: ARRAY OF CHAR): BOOLEAN;
  (* Returns TRUE if there is room for the replacement of sourceLength characters in destination starting at startIndex; otherwise returns FALSE.
  *)

PROCEDURE CanAppendAll (sourceLength: CARDINAL; VAR destination: ARRAY OF CHAR): BOOLEAN;
  (* Returns TRUE if there is sufficient room in destination to append a string of length sourceLength to the string in destination; otherwise returns FALSE. *)

PROCEDURE CanConcatAll (source1Length, source2Length: CARDINAL;
                        VAR destination: ARRAY OF CHAR): BOOLEAN;
  (* Returns TRUE if there is sufficient room in destination for a two strings of lengths source1Length and source2Length; otherwise returns FALSE. *)

(* The following type and procedures provide for the comparison of string values, and for the location of substrings within strings. *)

TYPE
  CompareResults = (less, equal, greater);

PROCEDURE Compare (stringVal1, stringVal2: ARRAY OF CHAR): CompareResults;
  (* Returns less, equal, or greater, according as stringVal1 is lexically less than, equal to, or greater than stringVal2. *)

PROCEDURE Equal (stringVal1, stringVal2: ARRAY OF CHAR): BOOLEAN;
  (* Returns Strings.Compare(stringVal1, stringVal2) = Strings.equal *)

PROCEDURE FindNext (pattern, stringToSearch: ARRAY OF CHAR; startIndex: CARDINAL; VAR patternFound: BOOLEAN; VAR posOfPattern: CARDINAL);
  (* Looks forward for next occurrence of pattern in stringToSearch, starting the search at position startIndex. If startIndex < LENGTH(stringToSearch) and pattern is found, patternFound is returned as TRUE, and posOfPattern contains the start position in stringToSearch of pattern. Otherwise patternFound is returned as FALSE, and posOfPattern is unchanged. *)

PROCEDURE FindPrev (pattern, stringToSearch: ARRAY OF CHAR; startIndex: CARDINAL; VAR patternFound: BOOLEAN; VAR posOfPattern: CARDINAL);
  (* Looks backward for the previous occurrence of pattern in stringToSearch and returns the position of the first character of the pattern if found. The search for the pattern begins at startIndex. If pattern is found, patternFound is returned as TRUE, and posOfPattern contains the start position in stringToSearch of pattern in the range [0..startIndex]. Otherwise patternFound is returned as FALSE, and posOfPattern is unchanged. *)

PROCEDURE FindDiff (stringVal1, stringVal2: ARRAY OF CHAR;
                    VAR differenceFound: BOOLEAN; VAR posOfDifference: CARDINAL);
  (* Compares the string values in stringVal1 and stringVal2 for differences. If they are equal, differenceFound is returned as FALSE, and TRUE otherwise. If differenceFound is TRUE, posOfDifference is set to the position of the first difference; otherwise posOfDifference is unchanged. *)

PROCEDURE Capitalize (VAR stringVar: ARRAY OF CHAR);
  (* Applies the function CAP to each character of the string value in stringVar. *)

END Strings.

A8.2 High Level String Conversion Modules

The modules in this section can be employed to convert strings into the corresponding numeric values. They may (but are not necessarily) be called by routines in WholeIO, RealIO and LongIO to return their values, after (presumed) calls to TextIO.ReadToken.

A8.2.1 WholeStr

DEFINITION MODULE WholeStr;

  (* Whole-number/string conversions *)

IMPORT
  ConvTypes;

TYPE
  ConvResults = ConvTypes.ConvResults; (* strAllRight, strOutOfRange, strWrongFormat, strEmpty *)

(* 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. *)

(* 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. *)

END WholeStr.

A8.2.2 RealStr

DEFINITION MODULE RealStr;

  (* REAL/string conversions *)

IMPORT
  ConvTypes;

TYPE
  ConvResults = ConvTypes.ConvResults; (* strAllRight, strOutOfRange, strWrongFormat, strEmpty *)

(* 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. *)

END RealStr.

A8.2.3 LongStr

DEFINITION MODULE LongStr;

  (* LONGREAL/string conversions *)

IMPORT
  ConvTypes;

TYPE
  ConvResults = ConvTypes.ConvResults; (* strAllRight, strOutOfRange,
strWrongFormat, strEmpty *)

(* 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 LongStr.

A8.3 Low Level String Conversion Modules

There is no requirement in the standard that the high level conversion modules above depend on the low level ones presented below. However, they are available for those who wish to write their own string conversion routines.

A8.3.1 ConvTypes

DEFINITION MODULE ConvTypes;

  (* Common types used in the string conversion modules *)

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); 

END ConvTypes.

A8.3.2 WholeConv

DEFINITION MODULE WholeConv;

  (* Low-level whole-number/string conversions *)

IMPORT
  ConvTypes;

TYPE
  ConvResults = ConvTypes.ConvResults; (* strAllRight, strOutOfRange,
strWrongFormat, strEmpty *)

PROCEDURE ScanInt (inputCh: CHAR; VAR chClass: ConvTypes.ScanClass;
                   VAR nextState: ConvTypes.ScanState);
  (* Represents the start state of a finite state scanner for signed whole numbers -assigns class of inputCh to chClass and a procedure representing the next state to nextState. *)

PROCEDURE FormatInt (str: ARRAY OF CHAR): ConvResults;
  (* Returns the format of the string value for conversion to INTEGER. *)

PROCEDURE ValueInt (str: ARRAY OF CHAR): INTEGER;
(* Returns the value corresponding to the signed whole number string value str if str is well-formed; otherwise raises the WholeConv exception. *)

PROCEDURE LengthInt (int: INTEGER): CARDINAL;
 (* Returns the number of characters in the string representation of int. *)

PROCEDURE ScanCard (inputCh: CHAR; VAR chClass: ConvTypes.ScanClass;
                    VAR nextState: ConvTypes.ScanState);
  (* Represents the start state of a finite state scanner for unsigned whole numbers -  assigns class of inputCh to chClass and a procedure representing the next state to nextState. *)

PROCEDURE FormatCard (str: ARRAY OF CHAR): ConvResults;
  (* Returns the format of the string value for conversion to CARDINAL. *)

PROCEDURE ValueCard (str: ARRAY OF CHAR): CARDINAL;
  (* Returns the value corresponding to the unsigned whole number string value str if str is well-formed; otherwise raises the WholeConv exception *)

PROCEDURE LengthCard (card: CARDINAL): CARDINAL;
  (* Returns the number of characters in the string representation of card. *)

PROCEDURE IsWholeConvException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional execution state because of the raising of an exception in a routine from this module; otherwise returns FALSE. *)

END WholeConv.

A8.3.3 RealConv

DEFINITION MODULE RealConv;

  (* Low-level REAL/string conversions *)

IMPORT
  ConvTypes;

TYPE
  ConvResults = ConvTypes.ConvResults; (* strAllRight, strOutOfRange,
strWrongFormat, strEmpty *)

PROCEDURE ScanReal (inputCh: CHAR; VAR chClass: ConvTypes.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. *)

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

PROCEDURE ValueReal (str: ARRAY OF CHAR): REAL;
  (* Returns the value corresponding to the real number string value str if str is well-formed; otherwise raises the RealConv exception.  *)

PROCEDURE LengthFloatReal (real: REAL; sigFigs: CARDINAL): CARDINAL;
  (* Returns the number of characters in the floating-point string
representation of real with sigFigs significant figures.  *)

PROCEDURE LengthEngReal (real: REAL; sigFigs: CARDINAL): CARDINAL;
  (* Returns the number of characters in the floating-point engineering string representation of real with sigFigs significant figures.  *)

PROCEDURE LengthFixedReal (real: REAL; place: INTEGER): CARDINAL;
  (* Returns the number of characters in the fixed-point string representation of real rounded to the given place relative to the decimal point.  *)

PROCEDURE IsRConvException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional execution state because of the raising of an exception in a routine from this module; otherwise returns FALSE.  *)

END RealConv.

A8.3.4 LongConv

DEFINITION MODULE LongConv;

  (* Low-level LONGREAL/string conversions *)

IMPORT
  ConvTypes;

TYPE
  ConvResults = ConvTypes.ConvResults; (* strAllRight, strOutOfRange,
strWrongFormat, strEmpty *)

PROCEDURE ScanReal (inputCh: CHAR; VAR chClass: ConvTypes.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. *)

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

PROCEDURE ValueReal (str: ARRAY OF CHAR): LONGREAL;
  (* Returns the value corresponding to the real number string value str if str is well-formed; otherwise raises the LongConv exception.  *)

PROCEDURE LengthFloatReal (real: LONGREAL; sigFigs: CARDINAL): CARDINAL;
  (* Returns the number of characters in the floating-point string
representation of real with sigFigs significant figures.  *)

PROCEDURE LengthEngReal (real: LONGREAL; sigFigs: CARDINAL): CARDINAL;
  (* Returns the number of characters in the floating-point engineering string representation of real with sigFigs significant figures.  *)

PROCEDURE LengthFixedReal (real: LONGREAL; place: INTEGER): CARDINAL;
  (* Returns the number of characters in the fixed-point string representation of real rounded to the given place relative to the decimal point.  *)

PROCEDURE IsRConvException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional execution state because of the raising of an exception in a routine from this module; otherwise returns FALSE. *)

END LongConv.

A8.4 SysClock--The Date and Time

DEFINITION MODULE SysClock;

(* =========================================
  Original specification and design of SysClock 
    Copyright  1990-1991 by R. Sutcliffe
    Assigned to the BSI for standards work
=========================================== *)

(* Facilities for accessing a system clock that records the date and time of day *)

CONST
  maxSecondParts = <implementation-defined integral value>;

TYPE
  Month    = [1 .. 12];
  Day      = [1 .. 31];
  Hour     = [0 .. 23];
  Min      = [0 .. 59];
  Sec      = [0 .. 59];
  Fraction = [0 .. maxSecondParts];
  UTCDiff  = [-780 .. 720];
  DateTime =
    RECORD
      year:      CARDINAL;
      month:     Month;
      day:       Day;
      hour:      Hour;
      minute:    Min;
      second:    Sec;
      fractions: Fraction;      (* parts of a second *)
      zone:      UTCDiff;       (* Time zone differential factor which is the number of minutes to add to local time to obtain UTC. *)
      summerTimeFlag: BOOLEAN;  (* Interpretation of flag depends on local usage. *)
    END;

PROCEDURE CanGetClock (): BOOLEAN;
  (* Returns TRUE if a system clock can be read; FALSE otherwise *)

PROCEDURE CanSetClock (): BOOLEAN;
  (* Returns TRUE if a system clock can be set; FALSE otherwise *)

PROCEDURE IsValidDateTime (userData: DateTime): BOOLEAN;
  (* Returns TRUE if the value of userData represents a valid date and time; FALSE otherwise *)

PROCEDURE GetClock (VAR userData: DateTime);
  (* If possible, assigns system date and time of day to userData *)

PROCEDURE SetClock (userData: DateTime);
  (* If possible, sets the system clock to the values of userData *)

END SysClock.

Contents