week/week_number/week_year are hardcoded to utc_c and are not respecting the time_zone

[hwrobel]

When trying to determine a working week number, you want to have it where you are located. Unfortunately, week info is derived in UTC only, so you are off by one depending on the time_zone and time.

For example, Sun 23:00 in America/Detroit means that time has already rolled over to Mon in UTC, leading to an "off-by-one" error when using week functions. There is no workaround other than manually calculating the week number from (year, month, day), which are in local time by reimplementing the algorithm externally.

The week functions must respect the time_zone of the DateTime object, or they have to be assumed in general to be inaccurate by +/-1.

[autarch]

This is definitely a bug, but I suspect that changing it may break existing code. I think the best fix would be to add some new local_week, etc. methods.

[hwrobel]

Technically, you are right, but I don't think that fixing it in-place is a problem. :-)

I have a very hard time imagining an application that uses a local date with local year/month/day, but still wants a UTC week. This combination just doesn't make any sense at all. If someone ran UTC dates in the application, they wouldn't see a difference. And if it was a local date, a fix would lead to the correct week at all times, not just most of the time. So I think "fix in place" would be ok.

I really don't think it really breaks code, I think people simply haven't noticed, as most don't run things Sunday late at night or Monday early morning in affected time zones. Weeks are used for work weeks, and few countries in the world would be affected at rollover time, given week starts, work times, and time zones. Statistically, it is simply unlikely that you notice even if you are affected as you get the correct result most of the time. My code has been running for many years 24x7 and I only noticed the off-by-one problem when using a date for a specific time zone that then caused the week rollover scenario during some activity that wasn't focused on dates at all.

If you want to keep API integrity 100% and not fix in-place, then I think there should be utc_week and local_week method(s), also for the week year of course, with the original week related method(s) being explained and deprecated, and clearly pointing to the well defined new methods then.

[autarch]

I discussed this with @n1vux and he pointed out that folks might be using this for something like naming weekly backup paths. Having it change subtly when upgrading the module might break that somehow. I don't think changing it in place is an option.

[n1vux]

... and that quiet time of oh-dark-early the night of Sunday/Monday is exactly when IT likes to schedule those backup jobs.

Meantime, as discussed in #148 and in BostonPM June 2025, when fuller POSIX LOCALE compatibility is needed, I consider the module POSIX strftime() which will compute a week number, or Time::Piece the official minimalist OO wrapper for time, with ->week for ISO weeknumber.

In fact, the one use I have for week-number uses POSIX::strftime "Y%Y W%U", localtime and note DateTime despite being a DateTime partisan, despite timezone not particularly mattering since I only need it to be the same from Sunday NY time thru Tuesday NY time.

If you have computed in a DateTime $dt you can use it in Time::Piece by this idiom:

Time::Piece->strptime($dt->epoch,q(%s))->week

[hwrobel]

After discovery of the problem I went for the seemingly straightforward "use Date::Calc qw(Week_of_Year);" with my DateTime year/month/day input values. Time::Piece apparently does not permit you to get to the week year without going through more somewhat complex formatting and number parsing stunts. If you need an ISO week for any given date, then you very likely also need the corresponding week year, which may not be the year of the date.

[n1vux]

If you need an ISO week for any given date, then you very likely also need the corresponding week year, which may not be the year of the date.

Excellent point! Yes Date::Calc returning ordered pair ($week_of_year,$year_of_week) is a very good interface, and their strong caution to do so should help avoid Oopsies during the critical New Years ± 2 weeks IT Freeze / Accounting Close of Books EOY/SOY period. (They've got good warnings throughout.)
[For some purposes I'd prefer formatting as YYYY:WW so it's sortable.]

Yes, if one is not going to format week-number into a string anyway, Time::Piece::strftime or POSIX::strftime is awkward.

If one has existing DateTime objects in the workflow and need to use Date::Calc for e.g. the safer week-number, the same epoch idiom I used for Time::Piece works:

perl -MDateTime -MDate::Calc=:all -E 'my $dt=DateTime->now; say join(q(,),Week_of_Year(Today($dt->epoch)));'

TIMTOWTDI - not every module has to be best at everything, choice is good.