lib/Time/Local.pm

   1 package Time::Local;
   2
   3 require Exporter;
   4 use Carp;
   5 use Config;
   6 use strict;
   7 use integer;
   8
   9 use vars qw( $VERSION @ISA @EXPORT @EXPORT_OK );
  10 $VERSION    = '1.09';
  11 $VERSION    = eval $VERSION;
  12 @ISA    = qw( Exporter );
  13 @EXPORT = qw( timegm timelocal );
  14 @EXPORT_OK      = qw( timegm_nocheck timelocal_nocheck );
  15
  16 my @MonthDays = (31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31);
  17
  18 # Determine breakpoint for rolling century
  19 my $ThisYear     = (localtime())[5];
  20 my $Breakpoint   = ($ThisYear + 50) % 100;
  21 my $NextCentury  = $ThisYear - $ThisYear % 100;
  22    $NextCentury += 100 if $Breakpoint < 50;
  23 my $Century      = $NextCentury - 100;
  24 my $SecOff       = 0;
  25
  26 my (%Options, %Cheat, %Min, %Max);
  27 my ($MinInt, $MaxInt);
  28
  29 if ($^O eq 'MacOS') {
  30     # time_t is unsigned...
  31     $MaxInt = (1 << (8 * $Config{intsize})) - 1;
  32     $MinInt = 0;
  33 } else {
  34     $MaxInt = ((1 << (8 * $Config{intsize} - 2))-1)*2 + 1;
  35     $MinInt = -$MaxInt - 1;
  36 }
  37
  38 $Max{Day} = ($MaxInt >> 1) / 43200;
  39 $Min{Day} = ($MinInt)? -($Max{Day}+1) : 0;
  40
  41 $Max{Sec} =  $MaxInt - 86400 * $Max{Day};
  42 $Min{Sec} =  $MinInt - 86400 * $Min{Day};
  43
  44 # Determine the EPOC day for this machine
  45 my $Epoc = 0;
  46 if ($^O eq 'vos') {
  47 # work around posix-977 -- VOS doesn't handle dates in
  48 # the range 1970-1980.
  49   $Epoc = _daygm((0, 0, 0, 1, 0, 70, 4, 0));
  50 }
  51 elsif ($^O eq 'MacOS') {
  52   no integer;
  53
  54   # MacOS time() is seconds since 1 Jan 1904, localtime
  55   # so we need to calculate an offset to apply later
  56   $Epoc = 693901;
  57   $SecOff = timelocal(localtime(0)) - timelocal(gmtime(0));
  58   $Epoc += _daygm(gmtime(0));
  59 }
  60 else {
  61   $Epoc = _daygm(gmtime(0));
  62 }
  63
  64 %Cheat=(); # clear the cache as epoc has changed
  65
  66 sub _daygm {
  67     $_[3] + ($Cheat{pack("ss",@_[4,5])} ||= do {
  68         my $month = ($_[4] + 10) % 12;
  69         my $year = $_[5] + 1900 - $month/10;
  70         365*$year + $year/4 - $year/100 + $year/400 + ($month*306 + 5)/10 - $Epoc
  71     });
  72 }
  73
  74
  75 sub _timegm {
  76     my $sec = $SecOff + $_[0]  +  60 * $_[1]  +  3600 * $_[2];
  77
  78     no integer;
  79
  80     $sec +  86400 * &_daygm;
  81 }
  82
  83
  84 sub _zoneadjust {
  85     my ($day, $sec, $time) = @_;
  86
  87     $sec = $sec + _timegm(localtime($time)) - $time;
  88     if ($sec >= 86400) { $day++; $sec -= 86400; }
  89     if ($sec <  0)     { $day--; $sec += 86400; }
  90
  91     ($day, $sec);
  92 }
  93
  94
  95 sub timegm {
  96     my ($sec,$min,$hour,$mday,$month,$year) = @_;
  97
  98     if ($year >= 1000) {
  99         $year -= 1900;
 100     }
 101     elsif ($year < 100 and $year >= 0) {
 102         $year += ($year > $Breakpoint) ? $Century : $NextCentury;
 103     }
 104
 105     unless ($Options{no_range_check}) {
 106         if (abs($year) >= 0x7fff) {
 107             $year += 1900;
 108             croak "Cannot handle date ($sec, $min, $hour, $mday, $month, *$year*)";
 109         }
 110
 111         croak "Month '$month' out of range 0..11" if $month > 11 or $month < 0;
 112
 113         my $md = $MonthDays[$month];
 114         ++$md unless $month != 1 or $year % 4 or !($year % 400);
 115
 116         croak "Day '$mday' out of range 1..$md"   if $mday  > $md  or $mday  < 1;
 117         croak "Hour '$hour' out of range 0..23"   if $hour  > 23   or $hour  < 0;
 118         croak "Minute '$min' out of range 0..59"  if $min   > 59   or $min   < 0;
 119         croak "Second '$sec' out of range 0..59"  if $sec   > 59   or $sec   < 0;
 120     }
 121
 122     my $days = _daygm(undef, undef, undef, $mday, $month, $year);
 123     my $xsec = $sec + $SecOff + 60*$min + 3600*$hour;
 124
 125     unless ($Options{no_range_check}
 126         or  ($days > $Min{Day} or $days == $Min{Day} and $xsec >= $Min{Sec})
 127        and  ($days < $Max{Day} or $days == $Max{Day} and $xsec <= $Max{Sec}))
 128     {
 129         warn "Day too small - $days > $Min{Day}\n" if $days < $Min{Day};
 130         warn "Day too big - $days > $Max{Day}\n" if $days > $Max{Day};
 131         warn "Sec too small - $days < $Min{Sec}\n" if $days < $Min{Sec};
 132         warn "Sec too big - $days > $Max{Sec}\n" if $days > $Max{Sec};
 133         $year += 1900;
 134         croak "Cannot handle date ($sec, $min, $hour, $mday, $month, $year)";
 135     }
 136
 137     no integer;
 138
 139     $xsec + 86400 * $days;
 140 }
 141
 142
 143 sub timegm_nocheck {
 144     local $Options{no_range_check} = 1;
 145     &timegm;
 146 }
 147
 148
 149 sub timelocal {
 150     # Adjust Max/Min allowed times to fit local time zone and call timegm
 151     local ($Max{Day}, $Max{Sec}) = _zoneadjust($Max{Day}, $Max{Sec}, $MaxInt);
 152     local ($Min{Day}, $Min{Sec}) = _zoneadjust($Min{Day}, $Min{Sec}, $MinInt);
 153     my $ref_t = &timegm;
 154
 155     # Calculate first guess with a one-day delta to avoid localtime overflow
 156     my $delta = ($_[5] < 100)? 86400 : -86400;
 157     my $loc_t = _timegm(localtime( $ref_t + $delta )) - $delta;
 158
 159     # Is there a timezone offset from GMT or are we done
 160     my $zone_off = $ref_t - $loc_t
 161         or return $loc_t;
 162
 163     # This hack is needed to always pick the first matching time
 164     # during a DST change when time would otherwise be ambiguous
 165     $zone_off -= 3600 if ($delta > 0 && $ref_t >= 3600);
 166
 167     # Adjust for timezone
 168     $loc_t = $ref_t + $zone_off;
 169
 170     # Are we close to a DST change or are we done
 171     my $dst_off = $ref_t - _timegm(localtime($loc_t))
 172         or return $loc_t;
 173
 174     # Adjust for DST change
 175     $loc_t += $dst_off;
 176
 177     return $loc_t if $dst_off >= 0;
 178
 179     # for a negative offset from GMT, and if the original date
 180     # was a non-extent gap in a forward DST jump, we should
 181     # now have the wrong answer - undo the DST adjust;
 182
 183     my ($s,$m,$h) = localtime($loc_t);
 184     $loc_t -= $dst_off if $s != $_[0] || $m != $_[1] || $h != $_[2];
 185
 186     $loc_t;
 187 }
 188
 189
 190 sub timelocal_nocheck {
 191     local $Options{no_range_check} = 1;
 192     &timelocal;
 193 }
 194
 195 1;
 196
 197 __END__
 198
 199 =head1 NAME
 200
 201 Time::Local - efficiently compute time from local and GMT time
 202
 203 =head1 SYNOPSIS
 204
 205     $time = timelocal($sec,$min,$hour,$mday,$mon,$year);
 206     $time = timegm($sec,$min,$hour,$mday,$mon,$year);
 207
 208 =head1 DESCRIPTION
 209
 210 These routines are the inverse of built-in perl functions localtime()
 211 and gmtime().  They accept a date as a six-element array, and return
 212 the corresponding time(2) value in seconds since the system epoch
 213 (Midnight, January 1, 1970 GMT on Unix, for example).  This value can
 214 be positive or negative, though POSIX only requires support for
 215 positive values, so dates before the system's epoch may not work on
 216 all operating systems.
 217
 218 It is worth drawing particular attention to the expected ranges for
 219 the values provided.  The value for the day of the month is the actual day
 220 (ie 1..31), while the month is the number of months since January (0..11).
 221 This is consistent with the values returned from localtime() and gmtime().
 222
 223 The timelocal() and timegm() functions perform range checking on the
 224 input $sec, $min, $hour, $mday, and $mon values by default.  If you'd
 225 rather they didn't, you can explicitly import the timelocal_nocheck()
 226 and timegm_nocheck() functions.
 227
 228         use Time::Local 'timelocal_nocheck';
 229
 230         {
 231             # The 365th day of 1999
 232             print scalar localtime timelocal_nocheck 0,0,0,365,0,99;
 233
 234             # The twenty thousandth day since 1970
 235             print scalar localtime timelocal_nocheck 0,0,0,20000,0,70;
 236
 237             # And even the 10,000,000th second since 1999!
 238             print scalar localtime timelocal_nocheck 10000000,0,0,1,0,99;
 239         }
 240
 241 Your mileage may vary when trying these with minutes and hours,
 242 and it doesn't work at all for months.
 243
 244 Strictly speaking, the year should also be specified in a form consistent
 245 with localtime(), i.e. the offset from 1900.
 246 In order to make the interpretation of the year easier for humans,
 247 however, who are more accustomed to seeing years as two-digit or four-digit
 248 values, the following conventions are followed:
 249
 250 =over 4
 251
 252 =item *
 253
 254 Years greater than 999 are interpreted as being the actual year,
 255 rather than the offset from 1900.  Thus, 1963 would indicate the year
 256 Martin Luther King won the Nobel prize, not the year 3863.
 257
 258 =item *
 259
 260 Years in the range 100..999 are interpreted as offset from 1900,
 261 so that 112 indicates 2012.  This rule also applies to years less than zero
 262 (but see note below regarding date range).
 263
 264 =item *
 265
 266 Years in the range 0..99 are interpreted as shorthand for years in the
 267 rolling "current century," defined as 50 years on either side of the current
 268 year.  Thus, today, in 1999, 0 would refer to 2000, and 45 to 2045,
 269 but 55 would refer to 1955.  Twenty years from now, 55 would instead refer
 270 to 2055.  This is messy, but matches the way people currently think about
 271 two digit dates.  Whenever possible, use an absolute four digit year instead.
 272
 273 =back
 274
 275 The scheme above allows interpretation of a wide range of dates, particularly
 276 if 4-digit years are used.
 277
 278 Please note, however, that the range of dates that can be actually be handled
 279 depends on the size of an integer (time_t) on a given platform.
 280 Currently, this is 32 bits for most systems, yielding an approximate range
 281 from Dec 1901 to Jan 2038.
 282
 283 Both timelocal() and timegm() croak if given dates outside the supported
 284 range.
 285
 286 =head2 Ambiguous Local Times (DST)
 287
 288 Because of DST changes, there are many time zones where the same local
 289 time occurs for two different GMT times on the same day.  For example,
 290 in the "Europe/Paris" time zone, the local time of 2001-10-28 02:30:00
 291 can represent either 2001-10-28 00:30:00 GMT, B<or> 2001-10-28
 292 01:30:00 GMT.
 293
 294 When given an ambiguous local time, the timelocal() function should
 295 always return the epoch for the I<earlier> of the two possible GMT
 296 times.
 297
 298 =head2 Non-Existent Local Times (DST)
 299
 300 When a DST change causes a locale clock to skip one hour forward,
 301 there will be an hour's worth of local times that don't exist.  Again,
 302 for the "Europe/Paris" time zone, the local clock jumped from
 303 2001-03-25 01:59:59 to 2001-03-25 03:00:00.
 304
 305 If the timelocal() function is given a non-existent local time, it
 306 will simply return an epoch value for the time one hour later.
 307
 308 =head2 Negative Epoch Values
 309
 310 Negative epoch (time_t) values are not officially supported by the
 311 POSIX standards, so this module's tests do not test them.  On some
 312 systems, they are known not to work.  These include MacOS (pre-OSX)
 313 and Win32.
 314
 315 On systems which do support negative epoch values, this module should
 316 be able to cope with dates before the start of the epoch, down the
 317 minimum value of time_t for the system.
 318
 319 =head1 IMPLEMENTATION
 320
 321 These routines are quite efficient and yet are always guaranteed to agree
 322 with localtime() and gmtime().  We manage this by caching the start times
 323 of any months we've seen before.  If we know the start time of the month,
 324 we can always calculate any time within the month.  The start times
 325 are calculated using a mathematical formula. Unlike other algorithms
 326 that do multiple calls to gmtime().
 327
 328 timelocal() is implemented using the same cache.  We just assume that we're
 329 translating a GMT time, and then fudge it when we're done for the timezone
 330 and daylight savings arguments.  Note that the timezone is evaluated for
 331 each date because countries occasionally change their official timezones.
 332 Assuming that localtime() corrects for these changes, this routine will
 333 also be correct.
 334
 335 =head1 BUGS
 336
 337 The whole scheme for interpreting two-digit years can be considered a bug.
 338
 339 =head1 SUPPORT
 340
 341 Support for this module is provided via the datetime@perl.org
 342 email list.  See http://lists.perl.org/ for more details.
 343
 344 Please submit bugs using the RT system at rt.cpan.org, or as a last
 345 resort, to the datetime@perl.org list.
 346
 347 =head1 AUTHOR
 348
 349 This module is based on a Perl 4 library, timelocal.pl, that was
 350 included with Perl 4.036, and was most likely written by Tom
 351 Christiansen.
 352
 353 The current version was written by Graham Barr.
 354
 355 It is now being maintained separately from the Perl core by Dave
 356 Rolsky, <autarch@urth.org>.
 357
 358 =cut
 359