AI22-0049-1

!standard 9.6(13)                                    23-07-10  AI22-0049-1/03

!standard 9.6.1(23/2)

!standard 9.6.1(58/2)

!class Binding Interpretation 22-10-25

!status Amendment 1-2022  23-07-10

!status WG9 Approved 23-10-12

!status ARG Approved  7-0-0  23-06-11

!status work item 22-10-25

!status received 22-07-19

!submitter Joshua Fletcher

!priority Low

!difficulty Easy

!qualifier Omission

!subject Seconds function with Time_Zone parameter

!summary

Add a function Seconds_Of to Ada.Calendar.Formatting.

!issue

Ada.Calendar.Formatting should provide a function to get Day_Duration with a time zone offset.

Currently, the simplest call is to use the Split function that returns "Seconds" as a Day_Duration, along with all the other parameters.

!recommendation

(See Summary.)

!wording

Add after 9.6.1(23/2):

function Seconds_Of (Date : Time;

            Time_Zone : Time_Zones.Time_Offset) return Day_Duration;

Add after 9.6.1(58/2):

function Seconds_Of (Date : Time;

            Time_Zone : Time_Zones.Time_Offset) return Day_Duration;

Returns the number of seconds in Date, as appropriate for the specified time zone offset.

!discussion

The original version of this package omitted a Seconds function as it seemed to be easily confused with the more useful Second function (as well as the Seconds_Of function). We side-step this issue by calling the new function Seconds_Of (rather than just Seconds).

Another reason that the function was omitted is that the Day_Duration type is rather vestigial. It was defined by the original Ada.Calendar but really does not have much use in the new packages. In Ada 83/95 programs, it was often used as part of calculating time differences (as the original “-” function risks Constraint_Error if the time difference can exceed one day), but that functionality is better accomplished using the facilities of Ada.Calendar.Arithmetic. It also was used for display purposes, but it is hard to correctly extract the hours and minutes from that value, and the facilities in Ada.Calendar.Formatting are much more likely to handle the boundary conditions correctly. So in new and substantially modified code (that is, any which uses Time_Zones or other facilities from the 9.6.1), the use cases for which Day_Duration would be useful are very limited.

The existing package makes regular and extensive use of overloading, and already contains a function of the name “Seconds_Of”. Making the new function an additional overload of Seconds_Of maintains the style of the existing package, and benefits from reduced ambiguity when viewed in the context of the existing Seconds_Of function.

Like any Binding Interpretation, this change can be provided for any Ada version (including Ada 2012 and Ada 2005). The intent is that this change will always be included in Ada 2022 implementations, but need not be provided in any earlier versions.

!corrigendum 9.6.1(23/2)

@dinsa

@xcode{@b{function} Day        (Date : Time;

                        Time_Zone  : Time_Zones.Time_Offset := 0)

                           @b{return} Day_Number;}

@dinst

@xcode{@b{function} Seconds_Of (Date : Time;

                        Time_Zone  : Time_Zones.Time_Offset := 0)

                           @b{return} Day_Duration;}

!corrigendum 9.6.1(58/2)

@dinsa

@xindent{Returns the day number for Date, as appropriate for the specified time zone offset.}

@dinss

@xcode{@b{function} Seconds_Of (Date : Time;

                        Time_Zone  : Time_Zones.Time_Offset := 0)

                           @b{return} Day_Duration;}

@xindent{Returns the number of seconds in Date, as appropriate for the specified time zone offset.}

!ACATS test

An ACATS C-Test should be made for a new function, but shall not be included in the ACATS version for testing Ada 2012. (ACATS versions for earlier versions of Ada no longer get any new tests, and there are no current ACATS tests for testing of Time_Zones.)

!appendix

This AI was constructed from Github Issue #18 (https://github.com/Ada-Rapporteur-Group/User-Community-Input/issues/18).

*************************************************