.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "DateTime::TimeZone::SystemV 3pm" .TH DateTime::TimeZone::SystemV 3pm "2022-06-13" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" DateTime::TimeZone::SystemV \- System V and POSIX timezone strings .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use DateTime::TimeZone::SystemV; \& \& $tz = DateTime::TimeZone::SystemV\->new( \& name => "US Eastern", \& recipe => "EST5EDT,M3.2.0,M11.1.0"); \& $tz = DateTime::TimeZone::SystemV\->new( \& "EST5EDT,M3.2.0,M11.1.0"); \& \& 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); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" An instance of this class represents a timezone that was specified by means of a System V timezone recipe or an extended form of the same syntax (such as that specified by \s-1POSIX\s0). These can express a plain offset from Universal Time, or a system of two offsets (standard and daylight saving time) switching on a yearly cycle according to certain types of rule. .PP This class implements the DateTime::TimeZone interface, so that its instances can be used with DateTime objects. .SH "SYSTEM V TIMEZONE RECIPE SYSTEM" .IX Header "SYSTEM V TIMEZONE RECIPE SYSTEM" This module supports multiple versions of the timezone recipe syntax derived from System V. Specifically, it supports the version specified by \s-1POSIX.1,\s0 and the extension of the \s-1POSIX\s0 format that is used by version 3 of the \fBtzfile\fR\|(5) file format. .PP A timezone may be specified that has a fixed offset by the syntax "\fIaaa\fR\fIooo\fR\*(L", or a timezone with \s-1DST\s0 by the syntax \&\*(R"\fIaaa\fR\fIooo\fR\fIaaa\fR[\fIooo\fR]\fB,\fR\fIrrr\fR\fB,\fR\fIrrr\fR\*(L". \*(R"\fIaaa\fR\*(L" specifies an abbreviation by which an offset is known, \*(R"\fIooo\fR\*(L" specifies the offset, and \*(R"\fIrrr\fR" is a rule for when \s-1DST\s0 starts or ends. For backward compatibility, the rules part may also be omitted from a DST-using timezone, in which case some built-in default rules are used; don't rely on those rules being useful. .PP An abbreviation must be a string of three or more characters from \s-1ASCII\s0 alphanumerics, "\fB+\fR\*(L", and \*(R"\fB\-\fR\*(L". If it contains only \s-1ASCII\s0 alphabetic characters then the abbreviation specification \*(R"\fIaaa\fR\*(L" may be simply the abbreviation. Otherwise \*(R"\fIaaa\fR\*(L" must consist of the abbreviation wrapped in angle brackets (\*(R"\fB<\fR...\fB>\fR"). The angle bracket form is always allowed. \s-1POSIX\s0 allows an implementation to set an upper limit on the length of timezone abbreviations. The limit is known as \&\f(CW\*(C`TZNAME_MAX\*(C'\fR, and is required to be no less than 6 (characters/bytes). Abbreviations longer than 6 characters are therefore not portable. This class imposes no such limit. .PP An offset (from Universal Time), "\fIooo\fR\*(L", is given in hours, or hours and minutes, or hours and minutes and seconds, with an optional preceding sign. Hours, minutes, and seconds must be separated by colons. The hours may be one or two digits, and the minutes and seconds must be two digits each. The maximum magnitude permitted is 24:59:59. The sign in the specification is the opposite of the sign of the actual offset. If no sign is given then the default is \*(R"\fB+\fR", meaning a timezone that is behind \s-1UT\s0 (or equal to \s-1UT\s0 if the offset is zero). If no \s-1DST\s0 offset is specified, it defaults to one hour ahead of the standard offset. .PP A DST-using timezone has one transition to \s-1DST\s0 and one transition to standard time in each Gregorian year. The transitions may be in either order within the year. If the transitions are in different orders from year to year then the behaviour is undefined; don't rely on it remaining the same in future versions. Likewise, the behaviour is generally undefined if transitions coincide. However, in the \fBtzfile\fR\|(5) variant, if the rules specify a transition to \s-1DST\s0 at 00:00 standard time on 1 January and a transition to standard time at 24:00 standard time on 31 December, which makes the transitions coincide with those of adjacent years, then the timezone is treated as observing \s-1DST\s0 all year. .PP A transition rule "\fIrrr\fR\*(L" takes the form \*(R"\fIddd\fR[\fB/\fR\fIttt\fR]\*(L", where \&\*(R"\fIddd\fR\*(L" is the rule giving the day on which the transition notionally takes place and \*(R"\fIttt\fR" is the time of day at which the transition takes place. (A time of day outside the usual 24\-hour range can make the transition actually take place on a different day.) The time may be given in hours, or hours and minutes, or hours and minutes and seconds. Hours, minutes, and seconds must be separated by colons. The minutes and seconds must be two digits each. In the \s-1POSIX\s0 variant, the hours may be one or two digits, with no preceding sign, and the time stated may range from 00:00:00 to 24:59:59 (almost an hour into the following day). In the \fBtzfile\fR\|(5) variant, the hours may be one to three digits, with optional preceding sign, and the time stated may range from \-167:59:59 to +167:59:59 (a span of a little over two weeks). If the time is not stated then it defaults to 02:00:00. The time for the transition to \s-1DST\s0 is interpreted according to the standard offset, and the time for the transition to standard time is interpreted according to the \s-1DST\s0 offset. (Thus normally the transition time is interpreted according to the offset that prevailed immediately before the transition.) .PP A day rule "\fIddd\fR\*(L" may take three forms. Firstly, \*(R"\fBJ\fR\fInnn\fR" means the month-day date that is the \fInnn\fRth day of a non-leap year. Thus "\fBJ59\fR\*(L" means the February 28 and \*(R"\fBJ60\fR" means March 1 (even in a leap year). February 29 cannot be specified this way. .PP Secondly, if "\fIddd\fR" is just a decimal number, it means the (1+\fIddd\fR)th day of the year. February 29 counts in this case, and it is not possible to specify December 31 of a leap year. .PP Thirdly, "\fIddd\fR\*(L" may have the form \*(R"\fBM\fR\fIm\fR\fB.\fR\fIw\fR\fB.\fR\fId\fR" means day \&\fId\fR of the \fIw\fRth week of the \fIm\fRth month. The day is given as a single digit, with "\fB0\fR\*(L" meaning Sunday and \*(R"\fB6\fR\*(L" meaning Saturday. The first week contains days 1 to 7 of the month, the second week contains days 8 to 14, and so on. If \*(R"\fIw\fR\*(L" is \*(R"\fB5\fR" then the last week of the month (containing its last seven days) is used, rather than the fifth week (which is incomplete). .PP Examples: .IP "\s-1MUT\-4\s0" 4 .IX Item "MUT-4" Mauritius time, since 1907: 4 hours ahead of \s-1UT\s0 all year. .IP "\s-1EST5EDT,M3.2.0,M11.1.0\s0" 4 .IX Item "EST5EDT,M3.2.0,M11.1.0" \&\s-1US\s0 Eastern timezone with \s-1DST,\s0 from 2007 onwards. 5 hours behind \s-1UT\s0 in winter and 4 hours behind in summer. Changes on the second Sunday in March and the first Sunday in November, in each case at 02:00 local time. .IP "\s-1NST3:30NDT,M3.2.0/0:01,M11.1.0/0:01\s0" 4 .IX Item "NST3:30NDT,M3.2.0/0:01,M11.1.0/0:01" Newfoundland timezone with \s-1DST,\s0 from 2007 onwards. 3.5 hours behind \s-1UT\s0 in winter and 2.5 hours behind in summer. Changes on the second Sunday in March and the first Sunday in November, in each case at 00:01 local time. .IP "\s-1GMT0BST,M3.5.0/1,M10.5.0\s0" 4 .IX Item "GMT0BST,M3.5.0/1,M10.5.0" \&\s-1UK\s0 civil time, from 1996 onwards. On \s-1UT\s0 during the winter, calling it \*(L"\s-1GMT\*(R",\s0 and 1 hour ahead of \s-1UT\s0 during the summer, called \*(L"\s-1BST\*(R".\s0 Changes on the last Sunday in March and the last Sunday in October, in each case at 01:00 \s-1UT.\s0 .IP "\s-1EST\-10EST,M10.5.0,M3.5.0/3\s0" 4 .IX Item "EST-10EST,M10.5.0,M3.5.0/3" Australian Eastern timezone, from 2007 onwards. 10 hours ahead of \s-1UT\s0 in the southern winter (the middle of the calendar year), and 11 hours ahead in the southern summer. Changes to \s-1DST\s0 on the last Sunday in October, and back on the last Sunday in March, in each case at 02:00 standard time (16:00 \s-1UT\s0 of the preceding day). .IP "\s-1EET\-2EEST,M3.5.4/24,M9.3.6/145\s0" 4 .IX Item "EET-2EEST,M3.5.4/24,M9.3.6/145" Palestinian civil time, from 2012 onwards. 2 hours ahead of \s-1UT\s0 in winter and 3 hours ahead in summer. Changes at the end (24:00 local time) of the last Thursday in March and 01:00 local time on the Friday following the third Saturday in September (that is, the Friday falling between September 21 and September 27 inclusive). The extended time-of-day \*(L"145\*(R", meaning 01:00 of the day six days after the nominal day, is only valid in the \fBtzfile\fR\|(5) variant of the System V syntax. The time-of-day \&\*(L"24\*(R" is not so restricted, being permitted by \s-1POSIX.\s0 .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .IP "DateTime::TimeZone::SystemV\->new(\s-1ATTR\s0 => \s-1VALUE, ...\s0)" 4 .IX Item "DateTime::TimeZone::SystemV->new(ATTR => VALUE, ...)" Constructs and returns a DateTime\-compatible timezone object that implements the timezone described by the recipe given in the arguments. The following attributes may be given: .RS 4 .IP "\fBname\fR" 4 .IX Item "name" Name for the timezone object. This will be returned by the \f(CW\*(C`name\*(C'\fR method described below, and will be included in certain error messages. If not given, then the recipe is used as the timezone name. .IP "\fBrecipe\fR" 4 .IX Item "recipe" The short textual timezone recipe, as described in \*(L"\s-1SYSTEM V TIMEZONE RECIPE SYSTEM\*(R"\s0. Must be given. .IP "\fBsystem\fR" 4 .IX Item "system" Keyword identifying the particular variant of the recipe system according to which the recipe is to be interpreted. It may be: .RS 4 .IP "\fBposix\fR (default)" 4 .IX Item "posix (default)" As specified by \s-1POSIX.1.\s0 .IP "\fBtzfile3\fR" 4 .IX Item "tzfile3" As specified by version 3 of the \fBtzfile\fR\|(5) file format. .RE .RS 4 .RE .RE .RS 4 .RE .IP "DateTime::TimeZone::SystemV\->new(\s-1RECIPE\s0)" 4 .IX Item "DateTime::TimeZone::SystemV->new(RECIPE)" Simpler way to invoke the above constructor in the usual case. Only the recipe is given; it will be interpreted according to \s-1POSIX\s0 system, and the recipe will also be used as the timezone name. .SH "METHODS" .IX Header "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. .SS "Identification" .IX Subsection "Identification" .ie n .IP "$tz\->is_floating" 4 .el .IP "\f(CW$tz\fR\->is_floating" 4 .IX Item "$tz->is_floating" Returns false. .ie n .IP "$tz\->is_utc" 4 .el .IP "\f(CW$tz\fR\->is_utc" 4 .IX Item "$tz->is_utc" Returns false. .ie n .IP "$tz\->is_olson" 4 .el .IP "\f(CW$tz\fR\->is_olson" 4 .IX Item "$tz->is_olson" Returns false. .ie n .IP "$tz\->category" 4 .el .IP "\f(CW$tz\fR\->category" 4 .IX Item "$tz->category" Returns \f(CW\*(C`undef\*(C'\fR, because the category concept doesn't properly apply to these timezones. .ie n .IP "$tz\->name" 4 .el .IP "\f(CW$tz\fR\->name" 4 .IX Item "$tz->name" Returns the timezone name. Usually this is the recipe that was supplied to the constructor, but it can be overridden by the constructor's \fBname\fR attribute. .SS "Offsets" .IX Subsection "Offsets" .ie n .IP "$tz\->has_dst_changes" 4 .el .IP "\f(CW$tz\fR\->has_dst_changes" 4 .IX Item "$tz->has_dst_changes" Returns a truth value indicating whether the timezone includes a \s-1DST\s0 offset. .ie n .IP "$tz\->is_dst_for_datetime(\s-1DT\s0)" 4 .el .IP "\f(CW$tz\fR\->is_dst_for_datetime(\s-1DT\s0)" 4 .IX Item "$tz->is_dst_for_datetime(DT)" \&\fI\s-1DT\s0\fR must be a DateTime\-compatible object (specifically, it must implement the \f(CW\*(C`utc_rd_values\*(C'\fR method). Returns a truth value indicating whether the timezone is on \s-1DST\s0 at the instant represented by \fI\s-1DT\s0\fR. .ie n .IP "$tz\->offset_for_datetime(\s-1DT\s0)" 4 .el .IP "\f(CW$tz\fR\->offset_for_datetime(\s-1DT\s0)" 4 .IX Item "$tz->offset_for_datetime(DT)" \&\fI\s-1DT\s0\fR must be a DateTime\-compatible object (specifically, it must implement the \f(CW\*(C`utc_rd_values\*(C'\fR method). Returns the offset from \s-1UT\s0 that is in effect at the instant represented by \fI\s-1DT\s0\fR, in seconds. .ie n .IP "$tz\->short_name_for_datetime(\s-1DT\s0)" 4 .el .IP "\f(CW$tz\fR\->short_name_for_datetime(\s-1DT\s0)" 4 .IX Item "$tz->short_name_for_datetime(DT)" \&\fI\s-1DT\s0\fR must be a DateTime\-compatible object (specifically, it must implement the \f(CW\*(C`utc_rd_values\*(C'\fR method). Returns the time scale abbreviation for the offset that is in effect at the instant represented by \fI\s-1DT\s0\fR. .ie n .IP "$tz\->offset_for_local_datetime(\s-1DT\s0)" 4 .el .IP "\f(CW$tz\fR\->offset_for_local_datetime(\s-1DT\s0)" 4 .IX Item "$tz->offset_for_local_datetime(DT)" \&\fI\s-1DT\s0\fR must be a DateTime\-compatible object (specifically, it must implement the \f(CW\*(C`local_rd_values\*(C'\fR method). Takes the local time represented by \fI\s-1DT\s0\fR (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 \fI\s-1DT\s0\fR). Returns the offset from \s-1UT\s0 that is in effect at that local time, in seconds. .Sp If the local time given is ambiguous due to a nearby offset change, the numerically lower offset (usually the standard one) is returned with no warning of the situation. If the local time given does not exist due to a nearby offset change, the method \f(CW\*(C`die\*(C'\fRs saying so. .SH "SEE ALSO" .IX Header "SEE ALSO" DateTime, DateTime::TimeZone, \&\s-1POSIX.1\s0 , \&\fBtzfile\fR\|(5) .SH "AUTHOR" .IX Header "AUTHOR" Andrew Main (Zefram) .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2007, 2009, 2010, 2011, 2012, 2013, 2017 Andrew Main (Zefram) .SH "LICENSE" .IX Header "LICENSE" This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.