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