Ambiguity due to the change in semantics of the type `t:Calendar.day_of_week`

[kipcole9]

Environment

• Elixir 1.11.0-dev compared to earlier releases

Current behaviour in Elixir up to 1.10

In Elixir versions up to 1.10, the type t:Calendar.day_of_week has no @typedoc to clarify whether this is intended to refer to the cardinal day of the week (ie 1 == Monday, 2 == Tuesday) or whether it is intended to be the ordinal day of the week (ie 1 == 1st day of the week, 2 = 2nd day of the week). For all of these versions they are the same thing for Calendar.ISO since that calendar has the first day of the week to be Monday.

This is an issue for the Date.day_of_week/1 function because it states:

Returns the day of the week as an integer. For the ISO 8601 calendar (the default), it is an integer from 1 to 7, where 1 is Monday and 7 is Sunday.

Which would, I think, be interpreted most commonly as the cardinal use of the day_of_week.

New behaviour in Elixir 1.11

In Elixir 1.11, Calendar.day_of_week also has no @typedoc to clarify whether this is intended to refer to the cardinal day of the week or ordinal. However the result is now clearly an ordinal day of week as reflected in the updated docs for Date.day_of_week/1:

Calculates the day of the week of a given date.
Returns the day of the week as an integer. For the ISO 8601
calendar (the default), it is an integer from 1 to 7, where
1 is Monday and 7 is Sunday.

Why is this an issue?

While the default behaviour for Calendar.ISO is unchanged, it's not possible to determine:

1. If other calendar implementations have treated day_of_week as a cardinal or ordinal number and the type t:Calendar.day_of_week has never been clear on the topic. Date.day_of_week/1 today would tend to suggest cardinal. And as a side note, all my calendar implementations have followed this assumption (that however is not the motivation for this issue).

2. If consumers of Date.day_of_week/1 have interpreted the result as a cardinal or an ordinal number and therefore may return an unexpected result in Elixir 1.11. This arises because Date functions are intended to return a semantically consistent result irrespective of calendar and today the semantics would appear, although not certain, to be a cardinal number.

Net: In the current versions of elixir the result is ambiguous but the same. In Elixir 1.11 the result is not ambiguous but may be different to Elixir 1.10 and earlier. And the documentation does not, I think, make that clear enough.

Some suggestions

1. Change the return type of Date.day_of_week/1 to be t:Calendar.ordinal_day_of_week which would be added as a type of non_neg_integer. This at least clarifies the intent but does not remove the incompatibility between earlier releases and Elixir 1.11. Update the documentation is all areas to make clear which interpretation of day of week is being returned when.

2. Leave the current Elixir 1.10 implementation of Date.day_of_week/1 in place and confirm its meaning to be a cardinal number. The type t:Calendar.day_of_week strictly means 1==Monday, 2==Tuesday and so on. Add t:Calendar.ordinal_day_of_week and Date.ordinal_day_of_week/2 to make clear it's returning the nth day of the week based upon the :starting_day.

My preference is (2) as you might expect since even though the current Date.day_of_week/1 returns an ambiguous result it is consistent for Calendar.ISO and doesn't disrupt the semantics of other calendar implementation. All calendars, including Calendar.ISO, can then add the new callback knowing explicitly when to return a cardinal day of week or an ordinal day of week.

Consumers are then also clear about when they are receiving a cardinal or ordinal number and they have a choice as to which one they want using either Date.day_of_week/1 to get the cardinal number or Date.ordinal_day_of_week/2 to get the ordinal number.

[josevalim]

Which would, I think, be interpreted most commonly as the cardinal use of the day_of_week.

I have been very careful to not bake that assumption into the docs and into the code, so I would say at the moment that this is not true.

The proof is in the return type of c:Calendar.day_of_week/4. If we were to assume it returns the cardinal day of the week, then there would be no need for it to return the first_day_of_week in {day_of_week, first_day_of_week, last_day_of_week}, as we could assume that first_day_of_week is always 1.

I am still in the camp of "calendars can return whatever they want" because I am not comfortable making the assumption ordinal day of the week is the best option for everyone. Calendar.ISO has chosen to follow an ordinal implementation for it, regardless of starting_on, but the behaviour does not require it. As you know, we should not necessarily look at Calendar.ISO and draw conclusions from its implementation, as otherwise someone could erroneously conclude we only support 4 digits for year. :)

So I believe we sit on the same camp as Elixir v1.10, where no assumptions are made. WDYT?

[kipcole9]

José, you may not make assumptions in the implementation about whether its cardinal or ordinal. But I'm pretty sure in your consumer code you do make an assumption about what the returned result represents otherwise what's the point of the function? It didn't matter before because they were the same (for Calendar.ISO). It always mattered if you were using dates in other calendars because that assumption never held.

I think a behaviour suffers if there is ambiguity in the semantics. The representation can be as different as it needs to be but the meaning should, I think, be consistent.

I appreciate the irony of these remarks because for Cldr.Date.day_of_month/1, Date.day_of_year/1 and Date.day_of_era/1 the interpretation I apply is ordinal. Logically therefore Date.day_of_week/2 should return an ordinal value and I'm fine with that. Its the ambiguity that I think can no longer be sustained given that now we are supporting different starting days of the week and therefore ordinal and cardinal are no longer necessarily the same (for Calendar.ISO).

I think we may also need a function that unambiguously returns what day of the week (cardinal) a given date falls on.

[josevalim]

Sorry @kipcole9, but I am afraid I don't understand the issue.

I don't think there is an ambiguity. There is an under-specification. There is nothing stopping someone from implementing their own calendar that returns 0 to 6 instead of 1 to 7. Or one that keeps the days consistent regardless of the starting_on. Why are we proposing to impose such semantics?

[kipcole9]

Let me use an example. You write some code to log the day of the week for a meeting. Your function looks like:

def log_day_of_meeting(%Date{} = date) do
  day_of_week = Date.day_of_week(date)
  Logger.info("The meeting is on #{day_of_week) day of week")
end

The date you receive is any date in any calendar. It seems strange to me that I cannot know by reading this code whether the day_of_week means the ordinal day or the cardinal day. I would need to know explicitly how each calendar interprets the notion of day_of_week. And I don't know in advance what calendar the dates might be in.

Note that this doesn't mean that I am suggesting calendars need to always return 1 == Monday. I'm just saying that whatever is returned, it is understood to be the cardinal day or the ordinal day. Seems perfectly ok in some mythical calendar to return Date.day_of_week(date) as 9876 as long as I know that its either "The meeting is on 9876 day of week" or "The meeting is on 9876th day of week" without having to know - for each possible calendar - how each calendar interprets the return value of this function.

[josevalim]

It seems strange to me that I cannot know by reading this code whether the day_of_week means the ordinal day or the cardinal day.

Yes, this was the case before and this is still the case now. In fact, in Elixir master it is now possible to unambiguously retrieve the ordinal day with the new API:

{day_of_week, first_day_of_week, _} = calendar.day_of_week(year, month, day, :default) 
day_of_week - first_day_of_week + 1

But I am still not comfortable with assuming this should be the imposed day_of_week representation for everyone. Calendars return a number here, what the number means should be dictated by them, especially because changing so would be backwards incompatible.

[kipcole9]

That being the case then I would like to make one final small proposal:

1. Review all callback implementations in Calendar.ISO and make sure that it is clearly documented what is returned. I'm not sure how that works in practise since it seems the @callback is typically documented but the implementation not. I'm fine to work on this with your guidance on how/where to do so.

2. The Calendar module documentation makes clear that calendars are free to decide what to return and that interpreting what is returned in one calendar cannot be assumed to have the same meaning as another. Happy to tackle this too if acceptable. Similarly for the Date and DateTime modules.

[josevalim]

I believe those proposals are great. We already document all functions in Calendar.ISO, exactly because the @callback definition is vague on purpose, so if something is missing, we should just complement it.

Regarding 2, I believe the focus should be on the Calendar module. We should clarify that the return is Calendar specific in Date and DateTime, but not dwell too much on calendar implementations.

[josevalim]

I will close this one for now, but the improvements to the docs are certainly welcome whenever you feel applicable. Thank you! :)