Use Zero-Indexing for Weekdays

[LennartCode]

Current State

Currently, there are 3 ways to index Weekday objects. iso and index both offer number Monday to Sunday 1..7 and us numbers Sunday to Saturday 0..6.

Proposal

I propose that index should number Monday to Sunday using 0..6, which would be different to the other two ways. This has the following advantage: Most cultures consider Monday the first day of the week and for mathematical reasons it is convenient to be able to access a first day of the week using the 0th index (like for us, the first day index is also 0).

While this is a breaking change, it does not influence the semantics of iso and us, which are presumably used by most people for accessing a weekday index for clarity, as suggested in the documentation.

Current Workaround

Either subtract 1 from the index on every operation or implement an extension type that uses an additional index implementation.

Somewhat related

On that note, it would also be nice to add dedicated methods for parsing Weekdays and a getter for accessing two-letter weekday shorthands. Those are minor quality of life features and unrelated to the actual proposal. I would be happy to contribute them if you deem them in the scope of the package though!

[pcekm]

I'd rather not change index. It's the primary value of the enum, and it matches the ISO-8601 calendar this library implements.

It's not much effort to write foo.iso - 1. And it's easy enough to write extension on Weekday { int get foo => iso - 1; } if you get tired of writing that extra - 1. But it's also easy to add another getter. Deciding what to name it, though—that would be hard. :-)

What is your use case? If this is bothering you, I'm guessing you're doing some sort of calculation based on the weekday. Perhaps there's a higher-level feature we can add to make that calculation unnecessary, or at least a lot easier.

[Lets discuss the parsing thing separately. I'll open another issue.]

[LennartCode]

In general, I appreciate indices starting at 0 as this way, the index encodes the offset from the first (zeroth) element. This makes most calculations easier and avoids off-by-one errors.
There are plenty more general reasons, cf. Wikipedia, in case you are interested.

My specific use case is drawing a calendar timetable grid on a Canvas for a calendar week view. The user can set their preferred first day of the week and appointments are shifted around accordingly. If the index was 0-based, it would inherently encode the offset factor from the start of the table and make calculations on where to draw columns clearer.

The request is coming from a general point of preference. The calculations are working fine but look more complicated than they should (in my humble opinion) and were initially a bit more complicated to write due to the index behaving unexpectedly (for me at least).

I don't think that there is an obvious higher-level feature or alternative getter that would make sense for my use case. Indices in Dart start at 0, so "index" is the best fitting name in my opinion. This is why the workaround using the unused enum field is required in the first place.

As of now, I don't see any reason not to have the index be 0-based for the ISO weekday order. Could you elaborate on why it being the primary value of the enum plays a role here? There are two reasons I could imagine where 1-based indices would be advantageous.

The first is serialisation, which should be done using the iso and us getters depending on the desired result anyway.

The second reason would be code that retreives the enumerated value for an ISO weekday index, something like var start = Weekday.values[1]; expecting Weekday.monday. I would argue, that this is a code smell though as the order of values in the enum is arbitrary without the locale (as there are multiple) and that another getter for enumerating the days of the week based on the desired locale would be better; something like Weekday.isoWeekdays[1] returning Weekday.monday.

I differentiate between locale-based access, which has iso and us depending on context, and implementation-based access, which should make programming as easy as possible. I agree that the perspective of ISO-8601 should be predominant for implementation here, thus starting at Monday instead of actually ordering the enum values arbitrarily. The enum index (the inherent property of the implementation) and the iso getter have two different tasks, which are at odds (in my opinion as I prefer 0-based indices) here, so differentiating between them would cleanly resolve this issue.

[pcekm]

You definitely don't need to sell me on 0-based indexing. I agree it's better. I apologize for not being more clear in my initial response. It's taken me a bit to remember why I made some of the decisions I did. Hopefully I'll do better this time around. :-)

As of now, I don't see any reason not to have the index be 0-based for the ISO weekday order. Could you elaborate on why it being the primary value of the enum plays a role here? There are two reasons I could imagine where 1-based indices would be advantageous.

I made index start with Monday = 1 for consistency with ISO-8601 and with DateTime.weekday. Put another way, this enum was meant to be an ISO 8601 weekday, which start numbering at Monday = 1. (The additional getters were added later, and—spoiler alert—I'm thinking about removing them.)

The first is serialisation, which should be done using the iso and us getters depending on the desired result anyway.

The second reason would be code that retreives the enumerated value for an ISO weekday index, something like var start = Weekday.values[1]; expecting Weekday.monday. I would argue, that this is a code smell though as the order of values in the enum is arbitrary without the locale (as there are multiple) and that another getter for enumerating the days of the week based on the desired locale would be better; something like Weekday.isoWeekdays[1] returning Weekday.monday.

I differentiate between locale-based access, which has iso and us depending on context, and implementation-based access, which should make programming as easy as possible. I agree that the perspective of ISO-8601 should be predominant for implementation here, thus starting at Monday instead of actually ordering the enum values arbitrarily. The enum index (the inherent property of the implementation) and the iso getter have two different tasks, which are at odds (in my opinion as I prefer 0-based indices) here, so differentiating between them would cleanly resolve this issue.

You're ascribing more purpose to these fields than I originally intended. I was just thinking of them as two common ways weekdays are encoded for computers. They're definitely not meant to have anything to do with locale. While the name iso is OK, us was a poor choice. Maybe c would have been better, since It's how the C standard library does it. Also, iso exists mostly for clarity, since it's identical to index. In hindsight, I wonder if I should have added them at all. One adds zero additional functionality, and the other is just index % 7.

---

With all that said, these are the open questions:

1. Should us and iso be removed?
2. How should weekdays be indexed?

For the first, I think they should both be removed. Having two (or three, if we change weekday indexes) is just going to cause confusion. I'd rather pick a weekday numbering scheme and stick with it. The minuscule amount additional functionality just isn't worth the potential confusion.

As for the second, lets restrict ourselves to considering three options:

Monday = 1

Pros: No change needed. This is the ISO standard, and it's consistent with DateTime. And java.time, for whatever that's worth.

Cons: That 1-based index offends programmer sensibilities.

Ultimately, it's only the ISO standard inasmuch as it's used as part of an ISO week date (e.g. 2026-W15-6). Tempo doesn't currently support creating or parsing such dates, and having Weekday use a different number scheme would not be much of an impediment to adding it.

Sunday = 0

Pros: Zero-based index makes programmers happy. It's a very common scheme: The C standard library, JavaScript, and many others use it. It's consistent with the WEEKDAYS array in the intl package.

Cons: In North America, people think, speak, and act like the week starts on Monday. I have no idea why our calendars don't reflect this.

I have a slight preference for this option. In spite of my misgivings, having a ready index into WEEKDAYS is very useful for displaying a localized calendar.

Monday = 0

Pros: Partially adheres to ISO 8601 insofar as weeks start with Monday. Also has a zero-based index. Consistent with the WEEKENDRANGE array in the intl package. (Yes, that's right, intl is inconsistent with itself.)

Cons: Probably the least common numbering method. Python's datetime uses it, though, so it's definitely got its adherents. The actual numbers are off by one from ISO 8601.

---

So, after all of that, you hopefully understand what I was thinking originally, and what I'm thinking now. What do you think I should do?

[pcekm]

One more reason to prefer a zero-based index: That _ identifier breaks the default enum handling in json_serialization. Specifically, it causes it to generate broken code that attempts to access Weekday._:

const _$WeekdayEnumMap = {
  Weekday._: '_',
  Weekday.monday: 'monday',
  Weekday.tuesday: 'tuesday',
  Weekday.wednesday: 'wednesday',
  Weekday.thursday: 'thursday',
  Weekday.friday: 'friday',
  Weekday.saturday: 'saturday',
  Weekday.sunday: 'sunday',
};