DateTi...Tzfile(3pm)

💖 DateTi...Tzfile(3pm) — DateTime::TimeZone::Tzfile 💖

okay so picture this: you're deep in a Perl doc, specifically one from User Contributed Perl Documentation, and you've found her — DateTime::TimeZone::Tzfile. she's literally the whole tzfile (zoneinfo) timezone files situation and she's about to make your whole day. let's get into it bestie 🫶

---

✨ NAME ✨

DateTime::TimeZone::Tzfile — tzfile (zoneinfo) timezone files. that's it, that's the vibe. 🎀

---

🌸 SYNOPSIS 🌸

use DateTime::TimeZone::Tzfile;

$tz = DateTime::TimeZone::Tzfile->new(
        name => "local timezone",
        filename => "/etc/localtime");
$tz = DateTime::TimeZone::Tzfile->new("/etc/localtime");

if($tz->is_floating) { ...
if($tz->is_utc) { ...
if($tz->is_olson) { ...
$category = $tz->category;
$tz_string = $tz->name;

if($tz->has_dst_changes) { ...
if($tz->is_dst_for_datetime($dt)) { ...
$offset = $tz->offset_for_datetime($dt);
$abbrev = $tz->short_name_for_datetime($dt);
$offset = $tz->offset_for_local_datetime($dt);

look at her go. iconic behavior only 💅

---

🦋 DESCRIPTION 🦋

okay so an instance of this class is literally a timezone that was encoded in a file, in the tzfile(5) format. and these files can express arbitrary patterns of offsets from Universal Time — changing over time, no cap. the tea though: offsets and change times are limited to a resolution of one second. that's the granularity, periodt.

this class implements the DateTime::TimeZone interface, so its instances can just chill with DateTime objects. they get along, it's giving found family 🥹

---

🌈 CONSTRUCTOR 🌈

👑 DateTime::TimeZone::Tzfile->new(ATTR => VALUE, ...)

reads and parses a tzfile(5) format file, then constructs and returns a DateTime-compatible timezone object that implements the timezone encoded in the file. literally the whole origin story. the following attributes may be given:

• name — the name for the timezone object. this will be returned by the "name" method described below, and will be included in certain error messages. so like, pick a good one bestie 🎀
• category — the string or "undef" that will be returned by the "category" method described below. default "undef".
• is_olson — the truth value that will be returned by the "is_olson" method described below. default false.
• filename — name of the file from which to read the timezone data. the filename must be understood by IO::File.
• filehandle — an IO::Handle object from which the timezone data can be read. this does not need to be a regular seekable file — it's read sequentially, sequentially only, no rewinding needed. and slay, because after the constructor has finished, the handle can still be used to read any data that follows the timezone data. nothing wasted 💖

okay so either a filename or a filehandle must be given — like, that's not optional, that's the rule. and if a timezone name is not given, then the filename is used instead if supplied; a timezone name must be given explicitly if no filename is given. read that again if you need to, it's lowkey important 🫶

🧚 DateTime::TimeZone::Tzfile->new(FILENAME)

simpler way to invoke the above constructor in the usual case. only the filename is given; this will also be used as the timezone name. one argument, one job, ate 💅

---

💜 METHODS 💜

these methods are all part of the DateTime::TimeZone interface. see that class for the general meaning of these methods; the documentation below only comments on the specific behaviour of this class. (so like, don't come for her for the general stuff, that's a different doc's business ✨)

⭐ Identification ⭐

• $tz->is_floating — returns false. that's the whole answer. no notes 💀
• $tz->is_utc — returns false. also the whole answer.
• $tz->is_olson — returns the truth value that was provided to the constructor for this purpose, default false. this nominally indicates whether the timezone data is from the Olson database. the files interpreted by this class are very likely to be from the Olson database, but there is no explicit indicator for this in the file, so this information must be supplied to the constructor if required. iykyk — the file itself is not gonna tell you 🙈
• $tz->category — returns the value that was provided to the constructor for this purpose, default "undef". this is intended to indicate the general region (continent or ocean) in which a geographical timezone is used, when the timezone is named according to the hierarchical scheme of the Olson timezone database. continent or ocean, pick your fighter 🌍
• $tz->name — returns the timezone name. usually this is the filename that was supplied to the constructor, but it can be overridden by the constructor's name attribute. main character energy, she can go by whatever she wants 👑

🔥 Offsets 🔥

• $tz->has_dst_changes — returns a truth value indicating whether any of the observances in the file are marked as DST. heads up though: these DST flags are potentially arbitrary, and don't affect any of the zone's behaviour. so like, decorative. cute but don't trust it with your life 🎀
• $tz->offset_for_datetime(DT) — DT must be a DateTime-compatible object (specifically, it must implement the "utc_rd_values" method). returns the offset from UT that is in effect at the instant represented by DT, in seconds.
• $tz->is_dst_for_datetime(DT) — DT must be a DateTime-compatible object (specifically, it must implement the "utc_rd_values" method). returns a truth value indicating whether the timezone's observance at the instant represented by DT is marked as DST. and again — this DST flag is potentially arbitrary, and doesn't affect anything else. it's just there, living its truth 💅
• $tz->short_name_for_datetime(DT) — DT must be a DateTime-compatible object (specifically, it must implement the "utc_rd_values" method). returns the abbreviation used to label the time scale at the instant represented by DT. plot twist: this abbreviation is potentially arbitrary, and does not uniquely identify either the timezone or the offset. so don't go reading too much into it, bestie 😭
• $tz->offset_for_local_datetime(DT) — DT must be a DateTime-compatible object (specifically, it must implement the "local_rd_values" method). takes the local time represented by DT (regardless of what absolute time it also represents), and interprets that as a local time in the timezone of the timezone object (not the timezone used in DT). returns the offset from UT that is in effect at that local time, in seconds.

if the local time given is ambiguous due to a nearby offset change, the numerically lowest offset (usually the standard one) is returned with no warning of the situation. (equivalently: the latest possible absolute time is indicated.) if the local time given does not exist due to a nearby offset change, the method "die"s saying so. like, it will literally end it. respectfully 💀

---

🍓 SEE ALSO 🍓

DateTime, DateTime::TimeZone, DateTime::TimeZone::Olson, Time::OlsonTZ::Data, Time::OlsonTZ::Download, tzfile(5)

go read them, they're all part of the friend group 🫶

---

🌸 AUTHOR 🌸

Andrew Main (Zefram) <zefram@fysh.org> — the icon, the legend 💖

🎀 COPYRIGHT 🎀

Copyright (C) 2007, 2009, 2010, 2011, 2012, 2013, 2017 Andrew Main (Zefram) <zefram@fysh.org>

⭐ LICENSE ⭐

this module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. free as in slay ✨

---

and that's the whole page bestie!! 🌈 sign-off time: this little beauty comes to you from perl v5.40.0, dated 2023-01-20, and it's the DateTi...Tzfile(3pm) page — mwah, go forth and timezone correctly 💋💅🦋