1DateTime::TimeZone::TzfUisleer(3C)ontributed Perl DocumeDnattaetTiiomne::TimeZone::Tzfile(3)
2
6 DateTime::TimeZone::Tzfile - tzfile (zoneinfo) timezone files
7
9 use DateTime::TimeZone::Tzfile;
10 $tz = DateTime::TimeZone::Tzfile->new(
12 name => "local timezone",
13 filename => "/etc/localtime");
14 $tz = DateTime::TimeZone::Tzfile->new("/etc/localtime");
15 if($tz->is_floating) { ...
17 if($tz->is_utc) { ...
18 if($tz->is_olson) { ...
19 $category = $tz->category;
20 $tz_string = $tz->name;
21 if($tz->has_dst_changes) { ...
23 if($tz->is_dst_for_datetime($dt)) { ...
24 $offset = $tz->offset_for_datetime($dt);
25 $abbrev = $tz->short_name_for_datetime($dt);
26 $offset = $tz->offset_for_local_datetime($dt);
27
29 An instance of this class represents a timezone that was encoded in a
30 file in the tzfile(5) format. These can express arbitrary patterns of
31 offsets from Universal Time, changing over time. Offsets and change
32 times are limited to a resolution of one second.
33 This class implements the DateTime::TimeZone interface, so that its
35 instances can be used with DateTime objects.
36
38 DateTime::TimeZone::Tzfile->new(ATTR => VALUE, ...)
39 Reads and parses a tzfile(5) format file, then constructs and
40 returns a DateTime-compatible timezone object that implements the
41 timezone encoded in the file. The following attributes may be
42 given:
43 name
45 Name for the timezone object. This will be returned by the
46 "name" method described below, and will be included in certain
47 error messages.
48 category
50 The string or "undef" that will be returned by the "category"
51 method described below. Default "undef".
52 is_olson
54 The truth value that will be returned by the "is_olson" method
55 described below. Default false.
56 filename
58 Name of the file from which to read the timezone data. The
59 filename must be understood by IO::File.
60 filehandle
62 An IO::Handle object from which the timezone data can be read.
63 This does not need to be a regular seekable file; it is read
64 sequentially. After the constructor has finished, the handle
65 can still be used to read any data that follows the timezone
66 data.
67 Either a filename or filehandle must be given. If a timezone name
69 is not given, then the filename is used instead if supplied; a
70 timezone name must be given explicitly if no filename is given.
71 DateTime::TimeZone::Tzfile->new(FILENAME)
73 Simpler way to invoke the above constructor in the usual case.
74 Only the filename is given; this will also be used as the timezone
75 name.
76
78 These methods are all part of the DateTime::TimeZone interface. See
79 that class for the general meaning of these methods; the documentation
80 below only comments on the specific behaviour of this class.
81 Identification
83 $tz->is_floating
84 Returns false.
85 $tz->is_utc
87 Returns false.
88 $tz->is_olson
90 Returns the truth value that was provided to the constructor for
91 this purpose, default false. This nominally indicates whether the
92 timezone data is from the Olson database. The files interpreted by
93 this class are very likely to be from the Olson database, but there
94 is no explicit indicator for this in the file, so this information
95 must be supplied to the constructor if required.
96 $tz->category
98 Returns the value that was provided to the constructor for this
99 purpose, default "undef". This is intended to indicate the general
100 region (continent or ocean) in which a geographical timezone is
101 used, when the timezone is named according to the hierarchical
102 scheme of the Olson timezone database.
103 $tz->name
105 Returns the timezone name. Usually this is the filename that was
106 supplied to the constructor, but it can be overridden by the
107 constructor's name attribute.
108 Offsets
110 $tz->has_dst_changes
111 Returns a truth value indicating whether any of the observances in
112 the file are marked as DST. These DST flags are potentially
113 arbitrary, and don't affect any of the zone's behaviour.
114 $tz->offset_for_datetime(DT)
116 DT must be a DateTime-compatible object (specifically, it must
117 implement the "utc_rd_values" method). Returns the offset from UT
118 that is in effect at the instant represented by DT, in seconds.
119 $tz->is_dst_for_datetime(DT)
121 DT must be a DateTime-compatible object (specifically, it must
122 implement the "utc_rd_values" method). Returns a truth value
123 indicating whether the timezone's observance at the instant
124 represented by DT is marked as DST. This DST flag is potentially
125 arbitrary, and doesn't affect anything else.
126 $tz->short_name_for_datetime(DT)
128 DT must be a DateTime-compatible object (specifically, it must
129 implement the "utc_rd_values" method). Returns the abbreviation
130 used to label the time scale at the instant represented by DT.
131 This abbreviation is potentially arbitrary, and does not uniquely
132 identify either the timezone or the offset.
133 $tz->offset_for_local_datetime(DT)
135 DT must be a DateTime-compatible object (specifically, it must
136 implement the "local_rd_values" method). Takes the local time
137 represented by DT (regardless of what absolute time it also
138 represents), and interprets that as a local time in the timezone of
139 the timezone object (not the timezone used in DT). Returns the
140 offset from UT that is in effect at that local time, in seconds.
141 If the local time given is ambiguous due to a nearby offset change,
143 the numerically lowest offset (usually the standard one) is
144 returned with no warning of the situation. (Equivalently: the
145 latest possible absolute time is indicated.) If the local time
146 given does not exist due to a nearby offset change, the method
147 "die"s saying so.
148
150 DateTime, DateTime::TimeZone, DateTime::TimeZone::Olson,
151 Time::OlsonTZ::Data, Time::OlsonTZ::Download, tzfile(5)
152
154 Andrew Main (Zefram) <zefram@fysh.org>
155
157 Copyright (C) 2007, 2009, 2010, 2011, 2012, 2013, 2017 Andrew Main
158 (Zefram) <zefram@fysh.org>
159
161 This module is free software; you can redistribute it and/or modify it
162 under the same terms as Perl itself.
163perl v5.32.1 2021-01-27 DateTime::TimeZone::Tzfile(3)