CVS difference for ais/ai-00351.txt

Differences between 1.5 and version 1.6
Log of other versions for file ais/ai-00351.txt

--- ais/ai-00351.txt	2004/04/06 19:57:14	1.5
+++ ais/ai-00351.txt	2004/05/29 00:38:39	1.6
@@ -1,4 +1,4 @@
-!standard  9.06(11)                                     04-03-26  AI95-00351/04
+!standard  9.06(11)                                     04-05-27  AI95-00351/05
 !standard  9.06(24)
 !standard  9.06.01(01)
 !class amendment 03-09-22
@@ -16,22 +16,23 @@
 
 !problem
 
-Calendar.Time is missing a number of operations commonly needed by applications.
+The type Time in package Calendar is missing a number of operations commonly
+needed by applications.
 
 First, there is no day-of-the-week function. It is often necessary to do a task
 on a particular day of the week (maintenance tasks in servers often are
 executed on Sundays when the load is minimal). Determining the day of the week
 for an Ada.Calendar.Time value is complex.
 
-Second, determining the Hour:Minutes:Seconds representation of a time value is
+Second, determining the Hours:Minutes:Seconds representation of a time value is
 not trivial. This representation is needed for most output of time values.
 Similarly, values often need to be converted from Hours:Minutes:Seconds to
 time values.
 
 Third, determining elapsed time is difficult if more than Duration'Last seconds
 have elapsed. This makes it more likely that Ada programs and libraries will
-fail if they run longer than anticipated. We've had profilers, loggers, and
-other components fail due to this shortcoming.
+fail if they run longer than anticipated. There have been cases of profilers,
+loggers, and other components failing due to this shortcoming.
 
 Fourth, displaying a time value is complex. This is needed not only in
 carefully formatted output, but also in logs and debugging code.
@@ -43,7 +44,10 @@
 
 !proposal
 
-(See wording.)
+Three child packages of Ada.Calendar are proposed, namely
+Ada.Calendar.Time_Zones, Ada.Calendar.Arithmetic, and Ada.Calendar.Formatting.
+These provide types and operations to give greater control over the
+manipulation of time as outlined in the problem.
 
 !wording
 
@@ -52,6 +56,8 @@
 
     subtype Year_Number is Integer range 1901 .. 2399;
 
+Correct the spelling of "timezone" to "time zone" in 9.6(24).
+
 Add a new clause following 9.6:
 
 9.6.1 Formatting, Time Zones, and other operations for Time
@@ -66,7 +72,7 @@
 
     Unknown_Zone_Error : exception;
 
-    function UTC_Time_Offset (Date : in Time := Clock) return Time_Offset;
+    function UTC_Time_Offset (Date : Time := Clock) return Time_Offset;
 
 end Ada.Calendar.Time_Zones;
 
@@ -76,9 +82,9 @@
     -- Arithmetic on days:
 
     type Day_Count is range
-      -366*(1+Year_Number'last - Year_Number'first)
+      -366*(1+Year_Number'Last - Year_Number'First)
       ..
-      366*(1+Year_Number'last - Year_Number'first);
+      366*(1+Year_Number'Last - Year_Number'First);
 
     subtype Leap_Seconds_Count  is Integer range -999 .. 999;
 
@@ -97,7 +103,7 @@
 
 end Ada.Calendar.Arithmetic;
 
-with Ada.Calendar.Arithmetic, Ada.Calendar.Time_Zones;
+with Ada.Calendar.Time_Zones;
 package Ada.Calendar.Formatting is
 
     -- Day of the week:
@@ -114,26 +120,26 @@
     subtype Second_Number       is Natural range 0 .. 59;
     subtype Second_Duration     is Day_Duration range 0.0 .. 1.0;
 
-    function Hour       (Date : in Time;
-                         Time_Zone  : in Time_Zones.Time_Offset := 0)
+    function Hour       (Date : Time;
+                         Time_Zone  : Time_Zones.Time_Offset := 0)
                             return Hour_Number;
 
-    function Minute     (Date : in Time;
-                         Time_Zone  : in Time_Zones.Time_Offset := 0)
+    function Minute     (Date : Time;
+                         Time_Zone  : Time_Zones.Time_Offset := 0)
                             return Minute_Number;
 
-    function Second     (Date : in Time;
-                         Time_Zone  : in Time_Zones.Time_Offset := 0)
+    function Second     (Date : Time;
+                         Time_Zone  : Time_Zones.Time_Offset := 0)
                             return Second_Number;
 
-    function Sub_Second (Date : in Time;
-                         Time_Zone  : in Time_Zones.Time_Offset := 0)
+    function Sub_Second (Date : Time;
+                         Time_Zone  : Time_Zones.Time_Offset := 0)
                             return Second_Duration;
 
-    function Seconds_Of (Hour : in Hour_Number;
-                         Minute : in Minute_Number;
-                         Second : in Second_Number := 0;
-                         Sub_Second : in Second_Duration := 0.0)
+    function Seconds_Of (Hour   : Hour_Number;
+                         Minute : Minute_Number;
+                         Second : Second_Number := 0;
+                         Sub_Second : Second_Duration := 0.0)
         return Day_Duration;
 
     procedure Split (Seconds    : in Day_Duration;
@@ -192,9 +198,11 @@
 
     -- Simple image and value:
     function Image (Date : Time;
-                    Include_Time_Fraction : Boolean := False) return String;
+                    Include_Time_Fraction : Boolean := False;
+		    Time_Zone  : Time_Zones.Time_Offset := 0) return String;
 
-    function Value (Date : String) return Time;
+    function Value (Date : String;
+		    Time_Zone  : Time_Zones.Time_Offset := 0) return Time;
 
     function Image (Elapsed_Time : Duration;
                     Include_Time_Fraction : Boolean := False) return String;
@@ -206,7 +214,7 @@
 Type Time_Offset represents the number of minutes difference between the
 implementation-defined time zone used by Ada.Calendar and another time zone.
 
-function UTC_Time_Offset (Date : in Time := Clock) return Time_Offset;
+function UTC_Time_Offset (Date : Time := Clock) return Time_Offset;
     Returns, as a number of minutes, the difference between the
     implementation-defined time zone of Calendar, and UTC time,
     at the time Date. If the time zone of the Calendar implementation is
@@ -250,8 +258,7 @@
     If Left < Right, then Seconds <= 0.0, Days <= 0, and Leap_Seconds <= 0.
     Otherwise, all values are non-negative.
     For the returned values, if Days = 0, then
-    If Days = 0, then Seconds + Duration(Leap_Seconds) =
-    Calendar."-" (Left, Right).
+    Seconds + Duration(Leap_Seconds) = Calendar."-" (Left, Right).
 
     AARM Notes: The number of days is calculated midnight-to-midnight.
     Leap_Seconds, if any, are not included in Seconds.
@@ -261,15 +268,15 @@
 
 function "+" (Left : Time; Right : Day_Count) return Time;
 function "+" (Left : Day_Count; Right : Time) return Time;
-    Add a number of days to a time value. Time_Error is raised
+    Adds a number of days to a time value. Time_Error is raised
     if the result is not representable as a value of type Time.
 
 function "-" (Left : Time; Right : Day_Count) return Time;
-    Subtract a number of days from a time value. Time_Error is raised
+    Subtracts a number of days from a time value. Time_Error is raised
     if the result is not representable as a value of type Time.
 
 function "-" (Left, Right : Time) return Day_Count;
-    Subtract two time values, and return the number of days between them.
+    Subtracts two time values, and returns the number of days between them.
     This is the same value that Difference would return in Days.
 
 function Day_of_Week (Date : Time) return Day_Name;
@@ -277,34 +284,34 @@
     Returns the day of the week for Time. This is based on the Year, Month, and
     Day values of Time.
 
-function Hour       (Date : in Time;
-                     Time_Zone  : in Time_Zones.Time_Offset := 0)
+function Hour       (Date : Time;
+                     Time_Zone  : Time_Zones.Time_Offset := 0)
                         return Hour_Number;
     Returns the hour for Date, as appropriate for the specified time zone
     offset.
 
-function Minute     (Date : in Time;
-                     Time_Zone  : in Time_Zones.Time_Offset := 0)
+function Minute     (Date : Time;
+                     Time_Zone  : Time_Zones.Time_Offset := 0)
                         return Minute_Number;
     Returns the minute within the hour for Date, as appropriate for the
     specified time zone offset.
 
-function Second     (Date : in Time;
-                     Time_Zone  : in Time_Zones.Time_Offset := 0)
+function Second     (Date : Time;
+                     Time_Zone  : Time_Zones.Time_Offset := 0)
                         return Second_Number;
     Returns the second within the hour and minute for Date, as appropriate for
     the specified time zone offset.
 
-function Sub_Second (Date : in Time;
-                     Time_Zone  : in Time_Zones.Time_Offset := 0)
+function Sub_Second (Date : Time;
+                     Time_Zone  : Time_Zones.Time_Offset := 0)
                         return Second_Duration;
-    Returns the fraction of second for Date. (This has the same accuracy as
-    Day_Duration), as appropriate to the specified time zone offset.
+    Returns the fraction of second for Date (this has the same accuracy as
+    Day_Duration), as appropriate for the specified time zone offset.
 
-function Seconds_Of (Hour : in Hour_Number;
-                     Minute : in Minute_Number;
-                     Second : in Second_Number := 0;
-                     Sub_Second : in Second_Duration := 0.0)
+function Seconds_Of (Hour   : Hour_Number;
+                     Minute : Minute_Number;
+                     Second : Second_Number := 0;
+                     Sub_Second : Second_Duration := 0.0)
     return Day_Duration;
     Returns a Day_Duration value for the Hour:Minute:Second.Sub_Second.
     This value can be used in Calendar.Time_Of as well as the argument to
@@ -315,7 +322,7 @@
                  Minute : out Minute_Number;
                  Second : out Second_Number;
                  Sub_Second : out Second_Duration);
-    Split Seconds into Hour:Minute:Second.Sub_Second.
+    Splits Seconds into Hour:Minute:Second.Sub_Second.
 
 procedure Split (Date       : in Time;
                  Time_Zone  : in Time_Zones.Time_Offset := 0;
@@ -326,7 +333,7 @@
                  Minute     : out Minute_Number;
                  Second     : out Second_Number;
                  Sub_Second : out Second_Duration);
-    Split Date into its constituent parts (Year, Month, Day, Hour, Minute,
+    Splits Date into its constituent parts (Year, Month, Day, Hour, Minute,
     Second, Sub_Second), relative to the specified time zone offset.
 
 function Time_Of (Year       : Year_Number;
@@ -386,8 +393,9 @@
     a leap second.
 
 function Image (Date : Time;
-                Include_Time_Fraction : Boolean := False) return String;
-    Returns a string form of the Date.
+                Include_Time_Fraction : Boolean := False;
+	        Time_Zone  : Time_Zones.Time_Offset := 0) return String;
+    Returns a string form of the Date relative to the given Time_Zone.
     The format is "Year-Month-Day Hour:Minute:Second", where each value
     other than Year is a 2-digit form of the value of the functions
     defined in Calendar and Calendar.Formatting, including a leading '0',
@@ -403,24 +411,32 @@
     leap seconds. These are not allowed here (the routines mentioned above
     cannot produce those results).
 
-function Value (Date : String) return Time;
-    Returns a Time value for the image given as Date.
+function Value (Date : String;
+	        Time_Zone  : Time_Zones.Time_Offset := 0) return Time;
+    Returns a Time value for the image given as Date, relative to the given
+    time zone.
     Constraint_Error is raised if the string is not formatted as described for
     Image, or the function cannot interpret the given string as a Time value.
 
 function Image (Elapsed_Time : Duration;
                 Include_Time_Fraction : Boolean := False) return String;
     Returns a string form of the Elapsed_Time.
-    The format is "Hours:Minute:Second", where each value
+    The format is "Hour:Minute:Second", where each value
     is a 2-digit form of the value, including a leading '0', if needed.
     If Include_Time_Fraction is True, Sub_Seconds*100 is suffixed to the
     string as a 2-digit value following a '.'.
+    If Elapsed_Time < 0.0, the result is Image (abs Elapsed_Time,
+    Include_Time_Fraction) prefixed with "-". If Abs Elapsed_Time represents
+    100 hours or more, the result is implementation-defined.
 
-    AARM Note: This cannot be implemented (directly) by calling
+    AARM Notes: This cannot be implemented (directly) by calling
     Ada.Calendar.Formatting.Split, since it may be out of the range of
     Day_Duration, and thus the number of hours may be out of the range of
     Hour_Number.
 
+    If a Duration value can represent more then 100 hours, the implementation
+    will need to define a format for the return of Image.
+
 function Value (Elapsed_Time : String) return Duration;
     Returns a Duration value for the image given as Elapsed_Time.
     Constraint_Error is raised if the string is not formatted as described for
@@ -430,8 +446,9 @@
 Implementation Advice
 
 An implementation should support leap seconds if the target system supports
-them. If leap seconds are not supported, functions returning leap seconds
-should return zero, and Time_Of should raise Time_Error if Leap_Second is true.
+them. If leap seconds are not supported, Difference should return zero for
+Leap_Seconds, Split should return False for Leap_Second, and Time_Of should
+raise Time_Error if Leap_Second is True.
 
 !discussion
 
@@ -443,18 +460,18 @@
 ambiguities to many existing programs. (There are many new overloadings of
 Split and Time_Of.) In addition, while Ada.Calendar may be included in many
 programs, these operations are less likely to be needed and their overhead
-should not burden existing programs. The packages should be a child, and not
+should not burden existing programs. The packages are child packages, and not
 stand-alone packages, so that their implementation can take advantage of the
 internal representation of type Time.
 
 These operations are most valuable for wall clock time and date values. Thus,
 we have chosen not to provide similar operations for Ada.Real_Time.
 
-The rather vague descriptions of the Hour:Minute:Second:Sub_Second functions
+The rather vague descriptions of the Hour:Minute:Second.Sub_Second functions
 is similar to the existing description of Ada.Calendar.
 
 
-This package provides mechanisms to handle leap seconds. This is critical if
+These packages provide mechanisms to handle leap seconds. This is critical if
 the target is connected to a time-base. Otherwise, programs could potentially
 wait too long when a leap second is inserted.
 
@@ -493,15 +510,15 @@
 just with many more parameters. Claw.Time contains a function like this.
 However, experience with the Claw function shows that not only is the large
 number of parameters daunting (even to the designer!), but it still lacks
-in flexibility (limited number of orderings, no non-English words). Renamings
+flexibility (limited number of orderings, no non-English words). Renamings
 of the function help in ease of use, but nothing can help the flexibility.
 
-A second approach is the generic signature & generic package scheme. This
+A second approach is the generic signature and generic package scheme. This
 provides good localization, but at the cost of a generic signature package.
 The good news is that this package would not change often, and a predefined
 one could be provided for English and other common locales. But using it
 still requires an instantiation with many parameters. This is similar to the
-renaming, and it too lacks in flexibility in some cases.
+renaming, and it too lacks flexibility in some cases.
 
 A third approach is the format string approach. GNAT provides a package like
 this; Windows provides a function like this in its API. This provides a lot of
@@ -522,10 +539,10 @@
 parameters to Split and Time_Of so that a specified time zone can be used
 with those routines.
 
-(Research has shown the the use of "timezone" in the Ada 95 Standard is
+(Research has shown the use of "timezone" in the Ada 95 Standard is
 incorrect. For instance, see http://aa.usno.navy.mil/faq/docs/us_tzones.html,
 a page of the US Naval Observatory, which is charged with timekeeping in the
-US. Therefore, we've use "time zone" for this AI and also correct 9.6(24).)
+US. Therefore, we've used "time zone" for this AI and also correct 9.6(24).)
 
 Supporting more time zones other than local and UTC is much more difficult. An
 implementation can add such support with child packages.
@@ -591,7 +608,7 @@
 
     Unknown_Zone_Error : @b<exception>;
 
-    @b<function> UTC_Time_Offset (Date : @b<in> Time := Clock) @b<return> Time_Offset;
+    @b<function> UTC_Time_Offset (Date : Time := Clock) @b<return> Time_Offset;
 
 @b<end> Ada.Calendar.Time_Zones;
 
@@ -601,9 +618,9 @@
     -- @ft<@i<Arithmetic on days:>>
 
     @b<type> Day_Count @b<is range>
-      -366*(1+Year_Number'last - Year_Number'first)
+      -366*(1+Year_Number'Last - Year_Number'First)
       ..
-      366*(1+Year_Number'last - Year_Number'first);
+      366*(1+Year_Number'Last - Year_Number'First);
 
     @b<subtype> Leap_Seconds_Count @b<is> Integer @b<range> -999 .. 999;
 
@@ -622,7 +639,7 @@
 
 @b<end> Ada.Calendar.Arithmetic;
 
-@b<with> Ada.Calendar.Arithmetic, Ada.Calendar.Time_Zones;
+@b<with> Ada.Calendar.Time_Zones;
 @b<package> Ada.Calendar.Formatting @b<is>
 
     -- @ft<@i<Day of the week:>>
@@ -639,26 +656,26 @@
     @b<subtype> Second_Number       @b<is> Natural @b<range> 0 .. 59;
     @b<subtype> Second_Duration     @b<is> Day_Duration @b<range> 0.0 .. 1.0;
 
-    @b<function> Hour       (Date : @b<in> Time;
-                         Time_Zone  : @b<in> Time_Zones.Time_Offset := 0)
+    @b<function> Hour       (Date : Time;
+                         Time_Zone  : Time_Zones.Time_Offset := 0)
                             @b<return> Hour_Number;
 
-    @b<function> Minute     (Date : @b<in> Time;
-                         Time_Zone  : @b<in> Time_Zones.Time_Offset := 0)
+    @b<function> Minute     (Date : Time;
+                         Time_Zone  : Time_Zones.Time_Offset := 0)
                             @b<return> Minute_Number;
 
-    @b<function> Second     (Date : @b<in> Time;
-                         Time_Zone  : @b<in> Time_Zones.Time_Offset := 0)
+    @b<function> Second     (Date : Time;
+                         Time_Zone  : Time_Zones.Time_Offset := 0)
                             @b<return> Second_Number;
 
-    @b<function> Sub_Second (Date : @b<in> Time;
-                         Time_Zone  : @b<in> Time_Zones.Time_Offset := 0)
+    @b<function> Sub_Second (Date : Time;
+                         Time_Zone  : Time_Zones.Time_Offset := 0)
                             @b<return> Second_Duration;
 
-    @b<function> Seconds_Of (Hour : @b<in> Hour_Number;
-                         Minute : @b<in> Minute_Number;
-                         Second : @b<in> Second_Number := 0;
-                         Sub_Second : @b<in> Second_Duration := 0.0)
+    @b<function> Seconds_Of (Hour   :  Hour_Number;
+                         Minute : Minute_Number;
+                         Second : Second_Number := 0;
+                         Sub_Second : Second_Duration := 0.0)
         @b<return> Day_Duration;
 
     @b<procedure> Split (Seconds    : @b<in> Day_Duration;
@@ -717,9 +734,11 @@
 
     -- @ft<@i<Simple image and value:>>
     @b<function> Image (Date : Time;
-                    Include_Time_Fraction : Boolean := False) @b<return> String;
+                    Include_Time_Fraction : Boolean := False;
+                    Time_Zone  : Time_Zones.Time_Offset := 0) @b<return> String;
 
-    @b<function> Value (Date : String) @b<return> Time;
+    @b<function> Value (Date : String;
+                    Time_Zone  : Time_Zones.Time_Offset := 0) @b<return> Time;
 
     @b<function> Image (Elapsed_Time : Duration;
                     Include_Time_Fraction : Boolean := False) @b<return> String;
@@ -731,7 +750,7 @@
 Type Time_Offset represents the number of minutes difference between the
 implementation-defined time zone used by Ada.Calendar and another time zone.
 
-@xcode<@b<function> UTC_Time_Offset (Date : @b<in> Time := Clock) @b<return> Time_Offset;>
+@xcode<@b<function> UTC_Time_Offset (Date : Time := Clock) @b<return> Time_Offset;>
 @xindent<Returns, as a number of minutes, the difference between the
 implementation-defined time zone of Calendar, and UTC time,
 at the time Date. If the time zone of the Calendar implementation is
@@ -743,62 +762,59 @@
                       Leap_Seconds : @b<out> Leap_Seconds_Count);>
 @xindent<Returns the difference between Left and Right.
 Days is the number of days of difference, Seconds is the
-remainder seconds of difference, and Leap_Seconds is the number
-of leap seconds.
-If Left < Right, then Seconds <= 0.0, Days <= 0, and Leap_Seconds <= 0.
-Otherwise, all values are non-negative.
-For the returned values, if Days = 0, then
-If Days = 0, then Seconds + Duration(Leap_Seconds) =
-Calendar."-" (Left, Right).>
+remainder seconds of difference, and Leap_Seconds is the number of leap
+seconds. If Left < Right, then Seconds <= 0.0, Days <= 0, and Leap_Seconds <=
+0. Otherwise, all values are non-negative. For the returned values, if Days =
+0, then Seconds + Duration(Leap_Seconds) = Calendar."-" (Left, Right).>
 
 @xcode<@b<function> "+" (Left : Time; Right : Day_Count) @b<return> Time;
 @b<function> "+" (Left : Day_Count; Right : Time) @b<return> Time;>
-@xindent<Add a number of days to a time value. Time_Error is raised
+@xindent<Adds a number of days to a time value. Time_Error is raised
 if the result is not representable as a value of type Time.>
 
 @xcode<@b<function> "-" (Left : Time; Right : Day_Count) @b<return> Time;>
-@xindent<Subtract a number of days from a time value. Time_Error is raised
+@xindent<Subtracts a number of days from a time value. Time_Error is raised
 if the result is not representable as a value of type Time.>
 
 @xcode<@b<function> "-" (Left, Right : Time) @b<return> Day_Count;>
-@xindent<Subtract two time values, and @b<return> the number of days between
+@xindent<Subtracts two time values, and returns the number of days between
 them. This is the same value that Difference would return in Days.>
 
 @xcode<@b<function> Day_of_Week (Date : Time) @b<return> Day_Name;>
 @xindent<Returns the day of the week for Time. This is based on the Year,
 Month, and Day values of Time.>
 
-@xcode<@b<function> Hour       (Date : @b<in> Time;
-                     Time_Zone  : @b<in> Time_Zones.Time_Offset := 0)
+@xcode<@b<function> Hour       (Date : Time;
+                     Time_Zone  : Time_Zones.Time_Offset := 0)
                         @b<return> Hour_Number;>
 @xindent<Returns the hour for Date, as appropriate for the specified time zone
 offset.>
 
-@xcode<@b<function> Minute     (Date : @b<in> Time;
-                     Time_Zone  : @b<in> Time_Zones.Time_Offset := 0)
+@xcode<@b<function> Minute     (Date : Time;
+                     Time_Zone  : Time_Zones.Time_Offset := 0)
                         @b<return> Minute_Number;>
 @xindent<Returns the minute within the hour for Date, as appropriate for the
 specified time zone offset.>
 
-@xcode<@b<function> Second     (Date : @b<in> Time;
-                     Time_Zone  : @b<in> Time_Zones.Time_Offset := 0)
+@xcode<@b<function> Second     (Date : Time;
+                     Time_Zone  : Time_Zones.Time_Offset := 0)
                         @b<return> Second_Number;>
 @xindent<Returns the second within the hour and minute for Date, as appropriate
 for the specified time zone offset.>
 
-@xcode<@b<function> Sub_Second (Date : @b<in> Time;
-                     Time_Zone  : @b<in> Time_Zones.Time_Offset := 0)
+@xcode<@b<function> Sub_Second (Date : Time;
+                     Time_Zone  : Time_Zones.Time_Offset := 0)
                         @b<return> Second_Duration;>
-@xindent<Returns the fraction of second for Date. (This has the same accuracy
-as Day_Duration), as appropriate to the specified time zone offset.>
+@xindent<Returns the fraction of second for Date (this has the same accuracy
+as Day_Duration), as appropriate for the specified time zone offset.>
 
-@xcode<@b<function> Seconds_Of (Hour : @b<in> Hour_Number;
-                     Minute : @b<in> Minute_Number;
-                     Second : @b<in> Second_Number := 0;
-                     Sub_Second : @b<in> Second_Duration := 0.0)
+@xcode<@b<function> Seconds_Of (Hour   : Hour_Number;
+                     Minute : Minute_Number;
+                     Second : Second_Number := 0;
+                     Sub_Second : Second_Duration := 0.0)
     @b<return> Day_Duration;>
 @xindent<Returns a Day_Duration value for the Hour:Minute:Second.Sub_Second.
-This value can be used @b<in> Calendar.Time_Of as well as the argument to
+This value can be used in Calendar.Time_Of as well as the argument to
 Calendar."+" and Calendar."-".>
 
 @xcode<@b<procedure> Split (Seconds : @b<in> Day_Duration;
@@ -806,7 +822,7 @@
                  Minute : @b<out> Minute_Number;
                  Second : @b<out> Second_Number;
                  Sub_Second : @b<out> Second_Duration);>
-@xindent<Split Seconds into Hour:Minute:Second.Sub_Second.>
+@xindent<Splits Seconds into Hour:Minute:Second.Sub_Second.>
 
 @xcode<@b<procedure> Split (Date       : @b<in> Time;
                  Time_Zone  : @b<in> Time_Zones.Time_Offset := 0;
@@ -817,7 +833,7 @@
                  Minute     : @b<out> Minute_Number;
                  Second     : @b<out> Second_Number;
                  Sub_Second : @b<out> Second_Duration);>
-@xindent<Split Date into its constituent parts (Year, Month, Day, Hour, Minute,
+@xindent<Splits Date into its constituent parts (Year, Month, Day, Hour, Minute,
 Second, Sub_Second), relative to the specified time zone offset.>
 
 @xcode<@b<function> Time_Of (Year       : Year_Number;
@@ -871,8 +887,9 @@
 identifies a leap second.>
 
 @xcode<@b<function> Image (Date : Time;
-                Include_Time_Fraction : Boolean := False) @b<return> String;>
-@xindent<Returns a string form of the Date.
+                Include_Time_Fraction : Boolean := False;
+	        Time_Zone  : Time_Zones.Time_Offset := 0) @b<return> String;>
+@xindent<Returns a string form of the Date relative to the given Time_Zone.
 The format is "Year-Month-Day Hour:Minute:Second", where each value
 other than Year is a 2-digit form of the value of the functions
 defined in Calendar and Calendar.Formatting, including a leading '0',
@@ -880,18 +897,23 @@
 If Include_Time_Fraction is True, Sub_Seconds*100 is suffixed to the
 string as a 2-digit value following a '.'.>
 
-@xcode<@b<function> Value (Date : String) @b<return> Time;>
-@xindent<Returns a Time value for the image given as Date.
-Constraint_Error is raised if the string is not formatted as described for
-Image, or the function cannot interpret the given string as a Time value.>
+@xcode<@b<function> Value (Date : String)
+	        Time_Zone  : Time_Zones.Time_Offset := 0) @b<return> Time;>
+@xindent<Returns a Time value for the image given as Date, relative to the
+given time zone. Constraint_Error is raised if the string is not formatted as
+described for Image, or the function cannot interpret the given string as a
+Time value.>
 
 @xcode<@b<function> Image (Elapsed_Time : Duration;
                 Include_Time_Fraction : Boolean := False) @b<return> String;>
 @xindent<Returns a string form of the Elapsed_Time.
-The format is "Hours:Minute:Second", where each value
+The format is "Hour:Minute:Second", where each value
 is a 2-digit form of the value, including a leading '0', if needed.
 If Include_Time_Fraction is True, Sub_Seconds*100 is suffixed to the
-string as a 2-digit value following a '.'.>
+string as a 2-digit value following a '.'.
+If Elapsed_Time < 0.0, the result is Image (@b<abs> Elapsed_Time,
+Include_Time_Fraction) prefixed with "-". If @b<abs> Elapsed_Time represents
+100 hours or more, the result is implementation-defined.>
 
 @xcode<@b<function> Value (Elapsed_Time : String) @b<return> Duration;>
 @xindent<Returns a Duration value for the image given as Elapsed_Time.
@@ -902,8 +924,10 @@
 @i<@s8<Implementation Advice>>
 
 An implementation should support leap seconds if the target system supports
-them. If leap seconds are not supported, functions returning leap seconds
-should return zero, and Time_Of should raise Time_Error if Leap_Second is true.
+them. If leap seconds are not supported, Difference should return zero for
+Leap_Seconds, Split should return False for Leap_Second, and Time_Of should
+raise Time_Error if Leap_Second is True.
+
 
 @xindent<@s9<NOTES@hr
 36 The time in the time zone known as Greenwich Mean Time (GMT)

Questions? Ask the ACAA Technical Agent