DEFINITION MODULE Unsigned24 [ZTYPE];

(* Unsigned Integer Subrange Type With Values from 0 to 23 *) 


FROM FileIO IMPORT File; (* required for IO *)


(* Unsigned24 type *)

TYPE
    Unsigned24 = OPAQUE RECORD
        value : OCTET; (* 8 bits *)
    END; (* Unsigned24 *)


(* Z-Type bindings to operators, pervasives and primitives: *)


(* Range *) 

CONST [TMIN] minValue = 0;
(* Smallest value of type Unsigned24.
   This value is bound to TMIN for type Unsigned24. *) 

CONST [TMAX] maxValue = 23;
(* Largest value of type Unsigned24.
   This value is bound to TMAX for type Unsigned24. *)


(* Literal assignment *)

PROCEDURE [:=] assign ( VAR assignTo : Unsigned24; literal : ARRAY OF CHAR );
(* Converts string literal to a Unsigned24 value and assigns it to assignTo.
   This procedure is bound to the := operator for literal assignment. *)


(* Type conversions *)

PROCEDURE [::] toCARD  ( n : Unsigned24 ) : CARDINAL;
(* Converts Unsigned24 value n to a CARDINAL value and returns it.
   This function is bound to the :: operator for Unsigned24 to CARDINAL
   conversion. *)

PROCEDURE [::] toINT ( n : Unsigned24 ) : INTEGER; 
(* Converts Unsigned24 value n to an INTEGER value and returns it.
   This function is bound to the :: operator for Unsigned24 to INTEGER
   conversion. *)

PROCEDURE [::] fromCARD  ( n : CARDINAL ) : Unsigned24;
(* Converts CARDINAL value n to a Unsigned24 value and returns it.
   This function is bound to the :: operator for CARDINAL to Unsigned24
   conversion. *)

PROCEDURE [::] fromINT  ( n : INTEGER ) : Unsigned24;
(* Converts INTEGER value n to a Unsigned24 value and returns it.
   This function is bound to the :: operator for INTEGER to Unsigned24
   conversion. *)


(* Monadic arithmetic operations *) 

PROCEDURE [ODD] odd ( n : Unsigned24 ) : BOOLEAN;
(* Returns TRUE if Unsigned24 value n is odd, otherwise FALSE.
   This function is bound to pervasive function ODD for type Unsigned24. *)


(* Dyadic arithmetic operations *) 

PROCEDURE [+] add ( n1, n2 : Unsigned24 ) : Unsigned24;
(* Adds Unsigned24 values n1 and n2 and returns the result.
   This function is bound to the + operator for type Unsigned24. *)

PROCEDURE [-] sub ( n1, n2 : Unsigned24 ) : Unsigned24;
(* Subtracts Unsigned24 value n2 from n1 and returns the result.
   This function is bound to the - operator for type Unsigned24. *)

PROCEDURE [*] multiply ( n1, n2 : Unsigned24 ) : Unsigned24;
(* Multiplies Unsigned24 values n1 and n2 and returns the result.
   This function it bound to the * operator for type Unsigned24. *)

PROCEDURE [/] divide ( n1, n2 : Unsigned24 ) : Unsigned24;
(* Divives Unsigned24 value n1 by n2 and returns the result.
   This function is bound to the / operator for type Unsigned24. *)


(* Relational operations *) 

PROCEDURE [=] isEqual ( n1, n2 : Unsigned24 ) : BOOLEAN;
(* Returns TRUE if Unsigned24 values n1 and n2 are equal, otherwise FALSE.
   This function is bound to operators = and # for type Unsigned24. *)

PROCEDURE [<] isLess ( n1, n2 : Unsigned24 ) : BOOLEAN;
(* Returns TRUE if Unsigned24 value n1 is less than n2, otherwise FASLE.
   This function is bound to operators < and >= for type Unsigned24. *)

PROCEDURE [>] isGreater ( n1, n2 : Unsigned24 ) : BOOLEAN;
(* Returns TRUE if Unsigned24 value n1 is greater than n2, otherwise FALSE.
   This function is bound to operators > and <= for type Unsigned24. *)


(* Scalar conversion primitives *)

CONST digitCapacity = 2; (* maximum digits in native format *)

PROCEDURE [TO] toSXF ( n : Unsigned24; VAR s : ARRAY OF CHAR );
(* Converts Unsigned24 value n to a string in scalar exchange format.
   This procedure is used to synthesise conversions to other scalar types
   when no direct conversion path exists. *)

PROCEDURE [FROM] fromSXF ( VAR n : Unsigned24; CONST s : ARRAY OF CHAR );
(* Converts a string in scalar exchange format to a Unsigned24 value.
   This procedure is used to synthesise conversions from other scalar types
   when no direct conversion path exists. *)


(* IO operations *)

PROCEDURE Read( infile : File; VAR n : Unsigned24 );
(* Reads the textual representation of a Unsigned24 value from stream infile
   - any leading whitespace is skipped
   - any remaining characters that are part of the numeral being read are
     removed from infile
   - the numeric value of the numeral string read is assigned to the variable
     passed in for n
   - the file status is set to any of:
     success, outOfRange, wrongFormat, endOfLine, or endOfInput.
   This procedure is substituted for invocations of READ with a Unsigned24
   argument. *)

PROCEDURE Write( outfile : File; n : Unsigned24 );
(* Writes the textual representation of value n to stream outfile.
   This procedure is substituted for invocations of WRITE with a Unsigned24
   argument. *)

PROCEDURE WriteF ( outfile      : File;
                   CONST fmtStr : ARRAY OF CHAR;
                   items        : VARIADIC OF Unsigned24 );
(* Writes a formatted textual representation of one or more Unsigned24 values
   to output stream outfile. The output format is determined by fmtStr. This
   procedure is substituted for invocations of WRITEF with one or more
   Unsigned24 arguments. *)

END Unsigned24.