Help language development. Donate to The Perl Foundation
Phileas Fogg avait, «sans s'en douter», gagné un jour sur son itinéraire, - et cela uniquement parce qu'il avait fait le tour du monde en allant vers l'est, et il eût, au contraire, perdu un jour en allant en sens inverse, soit vers l'ouest.
— Le Tour du monde en quatre-vingts jours (Jules Vernes)
An module to extend the built in DateTime
with timezone support.
To use, simply include it at any point in your code:
```raku use DateTime::Timezones;
my $dt = DateTime.new: now; ```
This extends DateTime
to include the following three new attributes whose names are subject to change.
attribute | type | information |
---|---|---|
.olson-id |
Str | The unique Olson ID for the timezone |
.tz-abbr |
Str | An (mostly) unique abbreviation for the timezone |
.is-dst |
Bool | Whether the timezone is in daylight savings time |
The Olson IDs (or timezone identifiers) are maintained by the IANA and based around city names, in the format of Region/City, and occasionally Region/Subregion/City.
They do not tend to align with popular usage.
In the United States, for instance, what is commonly called Eastern Time is listed as America/New_York).
The timezone abbreviation is representative of popular usage, but isn't unique.
It's appropriate for a quick timestamp as it adjusts for daylight savings time, but for other display purposes, you may want to look to Intl::Format::DateTime
.
The DST attribute returns whether the timezone is in what is commonly referred to as Daylight Saving Time (or Summer Time).
In some time zones, False
is the only value.
For the most part, once you enable it, you won't need to do anything different at all, as it is designed to be as discreet as possible. There are, nonetheless, a few things to note:
timezone
has been modified slightly to be allomorphic. Int
offset or a Str
Olson ID.
Integer offsets are taken into account but the resultant time will be zoned to GMT (eventually whole-hour offsets will be be given an appropriate Etc/
zone). .timezone
, you get an IntStr
comprising the offset and the Olson ID, so it should Just Work™.
If you absolutely must have a strict Int
value, use .offset
, and for a strict Str
value, use .olson-id
DateTime.new($datetime.Str)
may not preserve the Olson ID and DST information..later()
, .earlier()
methods are currently untested. DateTime::Timezones
should not use
it, and instead assume that the methods exist.
If functionality is critical, you can try sticking in a die unless DateTime.^can('is-dst')
that will be executed at runtime.
This is due to a bug in Rakudo where the original methods of wrapped methods are deleted. I am working to create a workaround.Leapseconds are annoying for timekeeping and POSIX explicitly ignores them since future ones are unpredictable because weird physics. I do not have the expertise to ensure that leapseconds are handled correctly, but welcome any code review and/or pull requests to remedy this (particularly test cases).
While the module initially planned on augment
ing DateTime
, it turns out that has significant problems for things like precompilation (you can't) and requires enabling MONKEY-TYPING
which just feels dirty.
Instead, DateTime.new
is wrapped with a new method that returns the same (or functionally the same) DateTime
you would have expected and mixes in the parameterized TimezoneAware
role.
It has a few tricks to make sure it doesn't apply the role multiple times.
.timezone
(entered infinite loop)Timezones::ZoneInfo
module
-b fat
option is used for backwards compatibilityInt
or Instant
.DS_Store
files (thanks to ZeroDogg for bringing it to my attention).DateTime
objects that may have been precompiled before this module's use
statement.world-clock.raku
and pass in your favorite timezones.floor
DateTime
with timezone information.