1DateTime::TimeZone::TzfUisleer(3C)ontributed Perl DocumeDnattaetTiiomne::TimeZone::Tzfile(3)
2
3
4

NAME

6       DateTime::TimeZone::Tzfile - tzfile (zoneinfo) timezone files
7

SYNOPSIS

9           use DateTime::TimeZone::Tzfile;
10
11           $tz = DateTime::TimeZone::Tzfile->new(
12                   name => "local timezone",
13                   filename => "/etc/localtime");
14           $tz = DateTime::TimeZone::Tzfile->new("/etc/localtime");
15
16           if($tz->is_floating) { ...
17           if($tz->is_utc) { ...
18           if($tz->is_olson) { ...
19           $category = $tz->category;
20           $tz_string = $tz->name;
21
22           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

DESCRIPTION

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
34       This class implements the DateTime::TimeZone interface, so that its
35       instances can be used with DateTime objects.
36

CONSTRUCTOR

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
44           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
49           category
50               The string or "undef" that will be returned by the "category"
51               method described below.  Default "undef".
52
53           is_olson
54               The truth value that will be returned by the "is_olson" method
55               described below.  Default false.
56
57           filename
58               Name of the file from which to read the timezone data.  The
59               filename must be understood by IO::File.
60
61           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
68           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
72       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

METHODS

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
82   Identification
83       $tz->is_floating
84           Returns false.
85
86       $tz->is_utc
87           Returns false.
88
89       $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
97       $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
104       $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
109   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
115       $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
120       $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
127       $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
134       $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
142           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

SEE ALSO

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

AUTHOR

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

LICENSE

161       This module is free software; you can redistribute it and/or modify it
162       under the same terms as Perl itself.
163
164
165
166perl v5.28.0                      2018-07-14     DateTime::TimeZone::Tzfile(3)
Impressum