AI22-0048-1

!standard 9.6.1(18/2)                                    23-03-23  AI22-0048-1/02

!standard 9.6.1(51/2)

!standard 9.6.1(52/2)

!class Amendment 22-10-24

!status work item 22-10-24

!status received 22-07-19

!priority Low

!difficulty Easy

!subject Time_Zone parameter for Day_Of_Week

!summary

An overloaded Day_Of_Week function is added to Ada.Calendar.Formatting.

!issue

Ada.Calendar.Formatting.Day_Of_Week does not account for the Time_Zone... unlike every other formatting function in the same package, including the Day function.

The Ada Reference Manual does not clearly state which Time_Zone is used by Day_Of_Week.

!recommendation

There should be a version of Day_Of_Week with a Time_Zone parameter. The parameter should not be defaulted, though, so that the original Day_Of_Week can still provide the Day_of_Week in the local timezone.

!wording

Add after 9.6.1(18/2):

function Day_Of_Week (Date : Time;

   Time_Zone : Time_Zones.Time_Offset) return Day_Name;

Add after 9.6.1(52/2):

AARM Ramification: The Year, Month, and Day here are the ones defined in Ada.Calendar; therefore, this function uses the local timezone.

function Day_Of_Week (Date : Time;

   Time_Zone : Time_Zones.Time_Offset) return Day_Name;

Returns the day of week for Time in the given Time_Zone.

!discussion

The intent of the original wording was to use the Year, Month, and Day as defined in Ada.Calendar to determine the day of week. As such, we cannot make any assumptions about the time zone used by Day_Of_Week. The simpler solution of defaulting the Time_Zone as with the other functions in Ada.Calendar.Formatting would possibly be incompatible with some implementations. By using overloaded functions, no implementation will have to change their current implementation of Day_Of_Week, allowing maximum compatibility.

We recommend that the ACAA not test the time zone of the default Day_Of_Week; we don’t want to force implementations to change what they are doing with this function as it was rather vaguely defined. Anyone that needs results that are portable between implementations should use the new version of Day_Of_Week giving the intended time zone.

As a point of reference, as of 22-March-2023, the GNAT implementation of Day_Of_Week uses the local time zone, so it would indeed be incompatible to simply add a default Time_Zone of 0 to this function. So this further reinforces the decision to add an overloading, rather than add a defaulted parameter to the existing function.

!ACATS test

An ACATS test should check that a Time_Zone parameter is available for Day_Of_Week.

!appendix

This issue is based on Github Issue #17 (https://github.com/Ada-Rapporteur-Group/User-Community-Input/issues/17).

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