9.6.1 Formatting, Time Zones, and other operations for Time

Reason: {AI12-0005-1} We want to be able to specify the difference between any two arbitrary time zones. You might think that 1440 (24 hours) would be enough, but there are places (like Tonga, which is UTC+13hr) which are more than 12 hours different than UTC. Combined with summer time (known as daylight saving time in some parts of the world) – which switches opposite in the northern and southern hemispheres – and even greater differences are possible. We know of cases of a 26 hours difference, so we err on the safe side by selecting 28 hours as the limit. 

Reason: The maximum number of leap seconds is likely to be much less than this, but we don't want to reach the limit too soon if the earth's behavior suddenly changes. We believe that the maximum number is 1612, based on the current rules, but that number is too weird to use here. 

Ramification: {AI05-0119-1} In North America, the result will be negative; in Europe, the result will be zero or positive. 

Discussion: {AI12-0336-1} 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. We don't define one because of the lack of agreement on the definition of a time zone.

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. 

Discussion: Leap_Seconds, if any, are not included in Seconds. However, Leap_Seconds should be included in calculations using the operators defined in Calendar, as is specified for "–" above. 

Ramification: There is only one way to do the split which meets all of the requirements. 

Reason: {AI05-0238-1} If Seconds = 86400.0, one of the returned values would have to be out of its defined range (either Sub_Second = 1.0 or Hour = 24 with the other value being 0). This doesn't seem worth breaking the invariants. 

Discussion: Time_Error should be raised if Leap_Second is True, and the date and time values do not represent the second before a leap second. A leap second always occurs at midnight UTC, and is 23:59:60 UTC in ISO notation. So, if the time zone is UTC and Leap_Second is True, if any of Hour /= 23, Minute /= 59, or Second /= 59, then Time_Error should be raised. However, we do not say that, because other time zones will have different values where a leap second is allowed. 

Discussion: The Image provides a string in ISO 8601 format, the international standard time format. Alternative representations allowed in ISO 8601 are not supported here.

ISO 8601 allows 24:00:00 for midnight; and a seconds value of 60 for leap seconds. These are not allowed here (the routines mentioned above cannot produce those results). 

Ramification: The fractional part is truncated, not rounded. It would be quite hard to define the result with proper rounding, as it can change all of the values of the image. Values can be rounded up by adding an appropriate constant (0.5 if Include_Time_Fraction is False, 0.005 otherwise) to the time before taking the image. 

Discussion: {AI05-0005-1} The intent is that the implementation enforce the same range rules on the string as the appropriate function Time_Of, except for the hour, so “cannot interpret the given string as a Time value” happens when one of the values is out of the required range. For example, "2005-08-31 24:00:00" should raise Constraint_Error (the hour is out of range).

Implementation defined: The result of Calendar.Formatting.Image if its argument represents more than 100 hours.

Implementation Note: This cannot be implemented (directly) by calling 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. 

Discussion: The intent is that the implementation enforce the same range rules on the string as the appropriate function Time_Of, except for the hour, so “cannot interpret the given string as a Time value” happens when one of the values is out of the required range. For example, "10:23:60" should raise Constraint_Error (the seconds value is out of range). 

Implementation Advice: Leap seconds should be supported if the target system supports them. Otherwise, operations in Calendar.Formatting should return results consistent with no leap seconds.

Discussion: An implementation can always support leap seconds when the target system does not; indeed, this isn't particularly hard (all that is required is a table of when leap seconds were inserted). As such, leap second support isn't “impossible or impractical” in the sense of 1.1.3. However, for some purposes, it may be important to follow the target system's lack of leap second support (if the target is a GPS satellite, which does not use leap seconds, leap second support would be a handicap to work around). Thus, this Implementation Advice should be read as giving permission to not support leap seconds on target systems that don't support leap seconds. Implementers should use the needs of their customers to determine whether or not support leap seconds on such targets. 

Discussion: {AI95-00351-01} The time in the time zone known as Greenwich Mean Time (GMT) is generally very close to UTC time; for most purposes they can be treated the same. GMT is the time based on the rotation of the Earth; UTC is the time based on atomic clocks, with leap seconds periodically inserted to realign with GMT (because most human activities depend on the rotation of the Earth). At any point in time, there will be a sub-second difference between GMT and UTC. 

Discussion: {AI12-0336-1} This is an illustration to help specify the value of Local_Time_Offset. A user should pass zero as the Time_Zone parameter of Split, rather than trying to make the above calculation. 

{AI95-00351-01} {AI95-00428-01} Packages Calendar.Time_Zones, Calendar.Arithmetic, and Calendar.Formatting are new. 

{AI05-0238-1} Correction: Defined that Split for Seconds raises Time_Error for a value of exactly 86400.0, rather than breaking some invariant or raising some other exception. Ada 2005 left this unspecified; a program that depended on what some implementation does might break, but such a program is not portable anyway. 

{AI05-0119-1} Correction: Clarified the sign of UTC_Time_Offset. 

{AI12-0336-1} Correction: Changed the definition of Time_Offset to be compatible with most compilers. Also added Local_Time_Offset and Local_Image to better describe the intent. A program that expects the Ada 2012 definition of Time_Offset would get incorrect answers. However, most compilers tested use the revised definition, so the likelihood of a program breaking is quite low. Additionally, the new definitions could cause a use clause conflict; see the introduction of Annex A for more on this topic.