9.6.1 Formatting, Time Zones, and other operations for Time
Static Semantics
The following language-defined library packages exist:
package Ada.Calendar.Time_Zones
with Nonblocking, Global =>
in out synchronized is
-- Time zone manipulation:
type Time_Offset
is range -28*60 .. 28*60;
Unknown_Zone_Error :
exception;
function Local_Time_Offset (Date : Time := Clock)
return Time_Offset;
function UTC_Time_Offset (Date : Time := Clock)
return Time_Offset
renames Local_Time_Offset;
end Ada.Calendar.Time_Zones;
package Ada.Calendar.Arithmetic
with Nonblocking, Global =>
in out synchronized is
-- Arithmetic on days:
type Day_Count
is range
-366*(1+Year_Number'Last - Year_Number'First)
..
366*(1+Year_Number'Last - Year_Number'First);
subtype Leap_Seconds_Count
is Integer
range -2047 .. 2047;
procedure Difference (Left, Right :
in Time;
Days :
out Day_Count;
Seconds :
out Duration;
Leap_Seconds :
out Leap_Seconds_Count);
function "+" (Left : Time; Right : Day_Count) return Time;
function "+" (Left : Day_Count; Right : Time) return Time;
function "-" (Left : Time; Right : Day_Count) return Time;
function "-" (Left, Right : Time) return Day_Count;
end Ada.Calendar.Arithmetic;
with Ada.Calendar.Time_Zones;
package Ada.Calendar.Formatting
with Nonblocking, Global =>
in out synchronized is
-- Day of the week:
type Day_Name
is (
Monday,
Tuesday,
Wednesday,
Thursday,
Friday,
Saturday,
Sunday);
function Day_of_Week (Date : Time)
return Day_Name;
-- Hours:Minutes:Seconds access:
subtype Hour_Number
is Natural
range 0 .. 23;
subtype Minute_Number
is Natural
range 0 .. 59;
subtype Second_Number
is Natural
range 0 .. 59;
subtype Second_Duration
is Day_Duration
range 0.0 .. 1.0;
function Year (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Year_Number;
function Month (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Month_Number;
function Day (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Day_Number;
function Hour (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Hour_Number;
function Minute (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Minute_Number;
function Second (Date : Time)
return Second_Number;
function Sub_Second (Date : Time)
return Second_Duration;
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;
Hour :
out Hour_Number;
Minute :
out Minute_Number;
Second :
out Second_Number;
Sub_Second :
out Second_Duration);
function Time_Of (Year : Year_Number;
Month : Month_Number;
Day : Day_Number;
Hour : Hour_Number;
Minute : Minute_Number;
Second : Second_Number;
Sub_Second : Second_Duration := 0.0;
Leap_Second: Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0)
return Time;
function Time_Of (Year : Year_Number;
Month : Month_Number;
Day : Day_Number;
Seconds : Day_Duration := 0.0;
Leap_Second: Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0)
return Time;
procedure Split (Date :
in Time;
Year :
out Year_Number;
Month :
out Month_Number;
Day :
out Day_Number;
Hour :
out Hour_Number;
Minute :
out Minute_Number;
Second :
out Second_Number;
Sub_Second :
out Second_Duration;
Time_Zone :
in Time_Zones.Time_Offset := 0);
procedure Split (Date :
in Time;
Year :
out Year_Number;
Month :
out Month_Number;
Day :
out Day_Number;
Hour :
out Hour_Number;
Minute :
out Minute_Number;
Second :
out Second_Number;
Sub_Second :
out Second_Duration;
Leap_Second:
out Boolean;
Time_Zone :
in Time_Zones.Time_Offset := 0);
procedure Split (Date :
in Time;
Year :
out Year_Number;
Month :
out Month_Number;
Day :
out Day_Number;
Seconds :
out Day_Duration;
Leap_Second:
out Boolean;
Time_Zone :
in Time_Zones.Time_Offset := 0);
--
Simple image and value:
function Image (Date : Time;
Include_Time_Fraction : Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0)
return String;
function Local_Image (Date : Time;
Include_Time_Fraction : Boolean := False)
return String
is
(Image (Date, Include_Time_Fraction,
Time_Zones.Local_Time_Offset (Date)));
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;
function Value (Elapsed_Time : String)
return Duration;
end Ada.Calendar.Formatting;
Type Time_Offset represents for a given locality
at a given moment the number of minutes the local time is, at that moment,
ahead (+) or behind (-) Coordinated Universal Time (abbreviated UTC).
The Time_Offset for UTC is zero.
function Local_Time_Offset (Date : Time := Clock) return Time_Offset;
Returns, as a number
of minutes, the Time_Offset of the implementation-defined time zone of
Calendar, at the time Date. If the time zone of the Calendar implementation
is unknown, then Unknown_Zone_Error is raised.
procedure Difference (Left, Right : in Time;
Days : out Day_Count;
Seconds : out Duration;
Leap_Seconds : out Leap_Seconds_Count);
Returns the difference
between Left and Right. Days is the number of days of difference, Seconds
is the remainder seconds of difference excluding leap seconds, 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
nonnegative. The absolute value of Seconds is always less than 86_400.0.
For the returned values, if Days = 0, then Seconds + Duration(Leap_Seconds)
= Calendar."–" (Left, Right).
function "+" (Left : Time; Right : Day_Count) return Time;
function "+" (Left : Day_Count; Right : Time) return Time;
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;
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;
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;
Returns the day
of the week for Time. This is based on the Year, Month, and Day values
of Time.
function Year (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Year_Number;
Returns the year
for Date, as appropriate for the specified time zone offset.
function Month (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Month_Number;
Returns the month
for Date, as appropriate for the specified time zone offset.
function Day (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Day_Number;
Returns the day
number for Date, as appropriate for the specified time zone offset.
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 : 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 : Time)
return Second_Number;
Returns the second
within the hour and minute for Date.
function Sub_Second (Date : Time)
return Second_Duration;
Returns the fraction
of second for Date (this has the same accuracy as Day_Duration). The
value returned is always less than 1.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 combination of the given Hour, Minute, Second, and Sub_Second.
This value can be used in Calendar.Time_Of as well as the argument to
Calendar."+" and Calendar."–". If Seconds_Of
is called with a Sub_Second value of 1.0, the value returned is equal
to the value of Seconds_Of for the next second with a Sub_Second value
of 0.0.
procedure Split (Seconds : in Day_Duration;
Hour : out Hour_Number;
Minute : out Minute_Number;
Second : out Second_Number;
Sub_Second : out Second_Duration);
Splits Seconds into
Hour, Minute, Second and Sub_Second in such a way that the resulting
values all belong to their respective subtypes. The value returned in
the Sub_Second parameter is always less than 1.0. If Seconds = 86400.0,
Split propagates Time_Error.
function Time_Of (Year : Year_Number;
Month : Month_Number;
Day : Day_Number;
Hour : Hour_Number;
Minute : Minute_Number;
Second : Second_Number;
Sub_Second : Second_Duration := 0.0;
Leap_Second: Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0)
return Time;
If Leap_Second is
False, returns a Time built from the date and time values, relative to
the specified time zone offset. If Leap_Second is True, returns the Time
that represents the time within the leap second that is one second later
than the time specified by the other parameters. Time_Error is raised
if the parameters do not form a proper date or time. If Time_Of is called
with a Sub_Second value of 1.0, the value returned is equal to the value
of Time_Of for the next second with a Sub_Second value of 0.0.
function Time_Of (Year : Year_Number;
Month : Month_Number;
Day : Day_Number;
Seconds : Day_Duration := 0.0;
Leap_Second: Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0)
return Time;
If Leap_Second is
False, returns a Time built from the date and time values, relative to
the specified time zone offset. If Leap_Second is True, returns the Time
that represents the time within the leap second that is one second later
than the time specified by the other parameters. Time_Error is raised
if the parameters do not form a proper date or time. If Time_Of is called
with a Seconds value of 86_400.0, the value returned is equal to the
value of Time_Of for the next day with a Seconds value of 0.0.
procedure Split (Date : in Time;
Year : out Year_Number;
Month : out Month_Number;
Day : out Day_Number;
Hour : out Hour_Number;
Minute : out Minute_Number;
Second : out Second_Number;
Sub_Second : out Second_Duration;
Leap_Second: out Boolean;
Time_Zone : in Time_Zones.Time_Offset := 0);
If Date does not
represent a time within a leap second, splits Date into its constituent
parts (Year, Month, Day, Hour, Minute, Second, Sub_Second), relative
to the specified time zone offset, and sets Leap_Second to False. If
Date represents a time within a leap second, set the constituent parts
to values corresponding to a time one second earlier than that given
by Date, relative to the specified time zone offset, and sets Leap_Seconds
to True. The value returned in the Sub_Second parameter is always less
than 1.0.
procedure Split (Date : in Time;
Year : out Year_Number;
Month : out Month_Number;
Day : out Day_Number;
Hour : out Hour_Number;
Minute : out Minute_Number;
Second : out Second_Number;
Sub_Second : out Second_Duration;
Time_Zone : in Time_Zones.Time_Offset := 0);
Splits Date into
its constituent parts (Year, Month, Day, Hour, Minute, Second, Sub_Second),
relative to the specified time zone offset. The value returned in the
Sub_Second parameter is always less than 1.0.
procedure Split (Date : in Time;
Year : out Year_Number;
Month : out Month_Number;
Day : out Day_Number;
Seconds : out Day_Duration;
Leap_Second: out Boolean;
Time_Zone : in Time_Zones.Time_Offset := 0);
If Date does not
represent a time within a leap second, splits Date into its constituent
parts (Year, Month, Day, Seconds), relative to the specified time zone
offset, and sets Leap_Second to False. If Date represents a time within
a leap second, set the constituent parts to values corresponding to a
time one second earlier than that given by Date, relative to the specified
time zone offset, and sets Leap_Seconds to True. The value returned in
the Seconds parameter is always less than 86_400.0.
function Image (Date : Time;
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 the Year is a 4-digit value, and all
others are 2-digit values, of the functions defined in Calendar and Calendar.Formatting,
including a leading zero, if needed. The separators between the values
are a minus, another minus, a colon, and a single space between the Day
and Hour. If Include_Time_Fraction is True, the integer part of Sub_Seconds*100
is suffixed to the string as a point followed by a 2-digit value.
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 "Hour:Minute:Second",
where all values are 2-digit values, including a leading zero, if necessary.
The separators between the values are colons. If Include_Time_Fraction
is True, the integer part of Sub_Seconds*100 is suffixed to the string
as a point followed by a 2-digit value. If Elapsed_Time < 0.0, the
result is Image (abs Elapsed_Time, Include_Time_Fraction) prefixed
with a minus sign. If abs Elapsed_Time represents 100 hours or
more, the result is implementation-defined.
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 Image, or the function
cannot interpret the given string as a Duration value.
Implementation Advice
An implementation should support leap seconds if
the target system supports 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.
NOTE 1 The implementation-defined
time zone of package Calendar can be the local time zone. Local_Time_Offset
always returns the difference relative to the implementation-defined
time zone of package Calendar. If Local_Time_Offset does not raise Unknown_Zone_Error,
UTC time can be safely calculated (within the accuracy of the underlying
time-base).
NOTE 2 Calling Split on the results
of subtracting Duration(Local_Time_Offset*60) from Clock provides the
components (hours, minutes, and so on) of the UTC time. In the United
States, for example, Local_Time_Offset will generally be negative.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
