--=============================================================================
--|
--| PACKAGE NAME: timekeeper
--|
--| PURPOSE: To provide facilities for measuring and displaying elapsed time
--|    and current time.  Clients can get current time, reset timer,
--|    output elapsed time since timer was reset, compute elapsed time,
--|    and compare times for equality.
--|
--| PROGRAMMER: Lionel Deimel              DATE WRITTEN: 5/21/90
--| DATE OF LAST REVISION: 8/9/90          VERSION: 1.7
--| 
--| NOTES: Package intended to provide services without additional functions
--|    of standard package calendar.
--|
--=============================================================================

WITH calendar;

PACKAGE timekeeper IS

   -- Export type time from standard package calendar
   SUBTYPE time IS calendar.time;

   -- Export "-" function from standard package calendar
   FUNCTION "-" (x : time; y : time) RETURN duration RENAMES calendar."-";

   -- Export "=" function from standard package calendar
   FUNCTION "=" (x : time; y : time) RETURN Boolean RENAMES calendar."=";

   -- Provide special value of type time to indicate need for special
   -- function and to allow procedure calls without corresponding parameter
   uninitialized_time : CONSTANT time := calendar.time_of(1901, 1, 1);

   --==========================================================================
   --|
   --| PROCEDURE NAME: timekeeper.start_time
   --|
   --| PURPOSE: Reset timer and return current time.
   --|
   --| PROGRAMMER: Lionel Deimel              DATE WRITTEN: 5/21/90
   --| DATE OF LAST REVISION: 7/23/90         VERSION: 1.2
   --| 
   --| PARAMETERS:
   --|    t                          (out) current time
   --| 
   --| INPUT/OUTPUT: None.
   --|
   --| ASSUMPTIONS/LIMITATIONS: None.
   --|
   --| ERROR CHECKS/RESPONSES: None.
   --|
   --| NOTES: Procedure elapsed_time can be called to print the elapsed time 
   --|    since the timer was last reset.
   --|
   --==========================================================================

   PROCEDURE start_time (t : OUT time);

   --==========================================================================
   --|
   --| PROCEDURE NAME: timekeeper.time_stamp
   --|
   --| PURPOSE: Print time specified by input parameter or current time.
   --|
   --| PROGRAMMER: Lionel Deimel              DATE WRITTEN: 5/21/90
   --| DATE OF LAST REVISION: 7/23/90         VERSION: 1.1
   --| 
   --| PARAMETERS:
   --|    t                          (in) time to be printed or value of
   --|                                  of uninitialized_time
   --|
   --| INPUT: None.
   --|
   --| OUTPUT: (To default file) time of parameter t or, if 
   --|    t=uninitialized_time, current time.  Month, day, year, 
   --|    hours, minutes, and seconds are shown 
   --|    (example: "January 22, 1990 at 12:15:10.25").  Output is 
   --|    neither preceded nor followed by new lines.
   --|       
   --| ASSUMPTIONS/LIMITATIONS: It is assumed the output will fit on the 
   --|    current line.
   --|
   --| ERROR CHECKS/RESPONSES: None.
   --|
   --| NOTES: If parameter is omitted, procedure outputs current time.
   --|
   --==========================================================================

   PROCEDURE time_stamp (t : IN time := uninitialized_time);

   --==========================================================================
   --|
   --| PROCEDURE NAME: timekeeper.get_time
   --|
   --| PURPOSE: Get current time.
   --|
   --| PROGRAMMER: Lionel Deimel              DATE WRITTEN: 5/21/90
   --| DATE OF LAST REVISION: 7/23/90         VERSION: 1.1
   --| 
   --| PARAMETERS:
   --|    t                          (out) current time
   --| 
   --| INPUT/OUTPUT: None.
   --|
   --| ASSUMPTIONS/LIMITATIONS: None.
   --|
   --| ERROR CHECKS/RESPONSES: None.
   --|
   --| NOTES: None.
   --|
   --==========================================================================

   PROCEDURE get_time (t : OUT time);

   --==========================================================================
   --|
   --| PROCEDURE NAME: timekeeper.print_elapsed_time
   --|
   --| PURPOSE: Print interval expressed in days, hours, minutes, and seconds.
   --|
   --| PROGRAMMER: Lionel Deimel              DATE WRITTEN: 5/21/90
   --| DATE OF LAST REVISION: 8/9/90          VERSION: 1.2
   --| 
   --| PARAMETERS:
   --|    elapsed_in                 (in) interval to be printed
   --| 
   --| INPUT: None.
   --|
   --| OUTPUT: (To default file) value of elapsed_in, expressed in days, 
   --|    hours, minutes, and seconds.  Labeled output is a minimum of 12
   --|    characters long and is neither preceded nor followed by new
   --|    lines.  (Example: "1 day, 23 hours, 14 minutes, 26.1 seconds")
   --|       
   --| ASSUMPTIONS/LIMITATIONS: Parameter elapsed_in is assumed to have a 
   --|    positive value.
   --|
   --| ERROR CHECKS/RESPONSES: None.
   --|
   --| NOTES: None.
   --|
   --==========================================================================

   PROCEDURE print_elapsed_time (elapsed_in : IN duration);

   --==========================================================================
   --|
   --| PROCEDURE NAME: timekeeper.elapsed_time
   --|
   --| PURPOSE: Print elapsed time since timer was last reset (by start_time).
   --|
   --| PROGRAMMER: Lionel Deimel              DATE WRITTEN: 5/21/90
   --| DATE OF LAST REVISION: 7/22/90         VERSION: 1.1
   --| 
   --| PARAMETERS:
   --|    t                          (in) end of interval being timed or value
   --|                                  of uninitialized_time
   --| 
   --| INPUT: None.
   --|
   --| OUTPUT: (To default file) days, hours, minutes, seconds between time
   --|    timer was last reset, to time t,  or, if t=uninitialized_time, to
   --|    current time.  Format is same as that of print_elapsed_time.
   --|
   --| ASSUMPTIONS/LIMITATIONS: Parameter t assumed to be at least as late
   --|    as when timer was last reset.  Output is unpredictable if start_time
   --|    never called.
   --|
   --| ERROR CHECKS/RESPONSES: None.
   --|
   --| NOTES: Timer is reset by call to start_time.  If parameter omitted, 
   --|    elapsed time to current time is printed.
   --|
   --==========================================================================

   PROCEDURE elapsed_time (t : IN time := uninitialized_time);

END timekeeper;