AI22-0048-1
!standard 9.6.1(18/2) 25-05-02 AI22-0048-1/04
!standard 9.6.1(51/2)
!standard 9.6.1(52/2)
!class Binding Interpretation 22-10-24
!status Amendment 1-2022 23-03-30
!status WG9 Approved 25-07-18
!status WG9 Approved 23-06-13
!status ARG Approved 12-0-0 23-03-30
!status work item 22-10-24
!status received 22-07-19
!submitter Joshua Fletcher
!priority Low
!difficulty Easy
!qualifier Omission
!subject Time_Zone parameter for Day_Of_Week
An overloaded Day_Of_Week function is added to Ada.Calendar.Formatting.
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 specify which Time_Zone is used by Day_Of_Week. As such, the function cannot be used portably, as a different implementation (including a newer version of the current implementation) might have different behavior. As such, this function is limited to use only in non-critical circumstances, such as debugging. The function should be better specified.
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.
Spell Day_Of_Week with a capital ‘O’ (including the existing function).
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.
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.
The spelling of Day_Of_Week is changed to match the incorrect but simpler spelling used for identifiers elsewhere in the Reference Manual. (One never capitalizes “of” unless it is starting a sentence; this has been a major peeve of the Project Editor for many years and something that he finds extremely unnatural.) This is done both for the existing function and for the newly added function.
@dinsa
@xcode{ @b{function} Day_of_Week (Date : Time) @b{return} Day_Name;}
@dinst
@xcode{ @b{function} Day_Of_Week (Date : Time;
Time_Zone : Time_Zones.Time_Offset) @b{return} Day_Name;}
@dinsa
@xindent{Returns the day of the week for Time. This is based on the Year, Month, and Day values of Time.}
@dinss
@xcode{@b{function} Day_Of_Week (Date : Time;
Time_Zone : Time_Zones.Time_Offset) @b{return} Day_Name;}
@xindent{Returns the day of the week for Time in the given Time_Zone.}
An ACATS test should check that a Time_Zone parameter is available for Day_Of_Week.
This issue is based on Github Issue #17 (https://github.com/Ada-Rapporteur-Group/User-Community-Input/issues/17).
***********************************************************