Package: Ada.Calendar.Time_Zones

Dependencies

pragma License (Unrestricted);

Description

AI-351

!summary

This proposal adds a number of useful operations on Calendar.Time.

!problem

Calendar.Time 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 in 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 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.

Fourth, displaying a time value is complex. This is needed not only in carefully formatted output, but also in logs and debugging code.

Finally, determining the UTC time is not possible. This is needed in many applications, such as internet communication. Since Ada does not define whether the time value represents UTC time, local time, or some other time, it isn't possible to use Calendar.Time in such applications.

Header

package Ada.Calendar.Time_Zones is

Exceptions

Unknown_Zone_Error

Type Summary

Time_Offset

Other Items:

type Time_Offset is range -1440 .. 1440;
Represents the number of minutes difference between the mplementation- defined timezone used by Ada.Calendar and another timezone. Subtracting this value from a time value yields the time for the timezone. 
function UTC_Time_Offset (Date : in 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 unknown, then Unknown_Zone_Error is raised.

Notes: The time in the time zone known as Greenwich Mean Time (GMT) is generally equivalent to UTC time.

The implementation-defined time zone used for type Time may be, but need not be, the local time zone. UTC_Time_Offset always returns the difference relative to the implementation-defined time zone of package Calendar. If UTC_Time_Offset does not raise Unknown_Zone_Error, UTC time can be safely calculated (within the accuracy of the underlying time-base).

AARM Notes:

The Date parameter is needed to take into account time differences caused by daylight-savings time and other time changes.

Other time zones can be supported with a child package.

The accuracy of this routine is not specified; the intent is that the facilities of the underlying target operating system are used to implement it.

Calling Split on the results of subtracting Duration(UTC_Time_Offset*60) from Clock provides the components (hours, minutes, and so on) of the UTC time. In the US, for example, UTC_Time_Offset will generally be negative.

AARM Note This is an illustration to help specify the value of UTC_Time_Offset. A user should pass UTC_Time_Offset as the Time_Zone parameter of Split, rather than trying to make the above calculation. 

end Ada.Calendar.Time_Zones;
Generated on 2004-05-17 at 23:21:43 by AdaBrowse 4.0.1 using configuration file ab.cfg.