This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
better implementation of change#3326; open(local $foo,...) now
[perl5.git] / lib / Time / Local.pm
CommitLineData
a0d0e21e
LW
1package Time::Local;
2require 5.000;
3require Exporter;
4use Carp;
5
ac54365a
GS
6@ISA = qw( Exporter );
7@EXPORT = qw( timegm timelocal );
a0d0e21e 8
06ef4121 9# Set up constants
16bb4654 10 $SEC = 1;
11 $MIN = 60 * $SEC;
12 $HR = 60 * $MIN;
13 $DAY = 24 * $HR;
06ef4121
PC
14# Determine breakpoint for rolling century
15 my $thisYear = (localtime())[5];
16 $nextCentury = int($thisYear / 100) * 100;
17 $breakpoint = ($thisYear + 50) % 100;
18 $nextCentury += 100 if $breakpoint < 50;
9bb8015a
MK
19
20sub timegm {
06ef4121
PC
21 my (@date) = @_;
22 if ($date[5] > 999) {
23 $date[5] -= 1900;
24 }
25 elsif ($date[5] >= 0 && $date[5] < 100) {
26 $date[5] -= 100 if $date[5] > $breakpoint;
27 $date[5] += $nextCentury;
28 }
29 $ym = pack(C2, @date[5,4]);
30 $cheat = $cheat{$ym} || &cheat(@date);
31 $cheat
32 + $date[0] * $SEC
33 + $date[1] * $MIN
34 + $date[2] * $HR
35 + ($date[3]-1) * $DAY;
9bb8015a
MK
36}
37
38sub timelocal {
39 my $t = &timegm;
84902520 40 my $tt = $t;
9bb8015a
MK
41
42 my (@lt) = localtime($t);
43 my (@gt) = gmtime($t);
84902520 44 if ($t < $DAY and ($lt[5] >= 70 or $gt[5] >= 70 )) {
06ef4121
PC
45 # Wrap error, too early a date
46 # Try a safer date
e85ca32b 47 $tt += $DAY;
06ef4121
PC
48 @lt = localtime($tt);
49 @gt = gmtime($tt);
84902520 50 }
a0d0e21e 51
9bb8015a 52 my $tzsec = ($gt[1] - $lt[1]) * $MIN + ($gt[2] - $lt[2]) * $HR;
16bb4654 53
16bb4654 54 if($lt[5] > $gt[5]) {
55 $tzsec -= $DAY;
56 }
57 elsif($gt[5] > $lt[5]) {
58 $tzsec += $DAY;
59 }
60 else {
61 $tzsec += ($gt[7] - $lt[7]) * $DAY;
62 }
63
9bb8015a
MK
64 $tzsec += $HR if($lt[8]);
65
66 $time = $t + $tzsec;
84902520 67 @test = localtime($time + ($tt - $t));
a0d0e21e
LW
68 $time -= $HR if $test[2] != $_[2];
69 $time;
70}
71
72sub cheat {
73 $year = $_[5];
74 $month = $_[4];
ac54365a
GS
75 unless ($no_range_check) {
76 croak "Month '$month' out of range 0..11" if $month > 11 || $month < 0;
77 croak "Day '$_[3]' out of range 1..31" if $_[3] > 31 || $_[3] < 1;
78 croak "Hour '$_[2]' out of range 0..23" if $_[2] > 23 || $_[2] < 0;
79 croak "Minute '$_[1]' out of range 0..59" if $_[1] > 59 || $_[1] < 0;
80 croak "Second '$_[0]' out of range 0..59" if $_[0] > 59 || $_[0] < 0;
81 }
a0d0e21e
LW
82 $guess = $^T;
83 @g = gmtime($guess);
a0d0e21e 84 $lastguess = "";
390badbd 85 $counter = 0;
a0d0e21e 86 while ($diff = $year - $g[5]) {
390badbd 87 croak "Can't handle date (".join(", ",@_).")" if ++$counter > 255;
16bb4654 88 $guess += $diff * (363 * $DAY);
a0d0e21e
LW
89 @g = gmtime($guess);
90 if (($thisguess = "@g") eq $lastguess){
06ef4121
PC
91 croak "Can't handle date (".join(", ",@_).")";
92 #date beyond this machine's integer limit
a0d0e21e
LW
93 }
94 $lastguess = $thisguess;
95 }
96 while ($diff = $month - $g[4]) {
390badbd 97 croak "Can't handle date (".join(", ",@_).")" if ++$counter > 255;
16bb4654 98 $guess += $diff * (27 * $DAY);
a0d0e21e
LW
99 @g = gmtime($guess);
100 if (($thisguess = "@g") eq $lastguess){
06ef4121
PC
101 croak "Can't handle date (".join(", ",@_).")";
102 #date beyond this machine's integer limit
a0d0e21e
LW
103 }
104 $lastguess = $thisguess;
105 }
106 @gfake = gmtime($guess-1); #still being sceptic
107 if ("@gfake" eq $lastguess){
06ef4121
PC
108 croak "Can't handle date (".join(", ",@_).")";
109 #date beyond this machine's integer limit
a0d0e21e
LW
110 }
111 $g[3]--;
16bb4654 112 $guess -= $g[0] * $SEC + $g[1] * $MIN + $g[2] * $HR + $g[3] * $DAY;
a0d0e21e
LW
113 $cheat{$ym} = $guess;
114}
115
1161;
06ef4121
PC
117
118__END__
119
120=head1 NAME
121
122Time::Local - efficiently compute time from local and GMT time
123
124=head1 SYNOPSIS
125
126 $time = timelocal($sec,$min,$hours,$mday,$mon,$year);
127 $time = timegm($sec,$min,$hours,$mday,$mon,$year);
128
129=head1 DESCRIPTION
130
131These routines are the inverse of built-in perl fuctions localtime()
132and gmtime(). They accept a date as a six-element array, and return
133the corresponding time(2) value in seconds since the Epoch (Midnight,
134January 1, 1970). This value can be positive or negative.
135
136It is worth drawing particular attention to the expected ranges for
137the values provided. While the day of the month is expected to be in
138the range 1..31, the month should be in the range 0..11.
139This is consistent with the values returned from localtime() and gmtime().
140
ac54365a
GS
141Also worth noting is the ability to disable the range checking that
142would normally occur on the input $sec, $min, $hours, $mday, and $mon
a1f33342
GS
143values. You can do this by localizing $Time::Local::no_range_check
144to 1.
ac54365a 145
a1f33342
GS
146 use Time::Local;
147
148 {
149 local $Time::Local::no_range_check = 1;
ac54365a 150
a1f33342
GS
151 # The 365th day of 1999
152 print scalar localtime timelocal 0,0,0,365,0,99;
ac54365a 153
a1f33342
GS
154 # The twenty thousandth day since 1970
155 print scalar localtime timelocal 0,0,0,20000,0,70;
ac54365a 156
a1f33342
GS
157 # And even the 10,000,000th second since 1999!
158 print scalar localtime timelocal 10000000,0,0,1,0,99;
159 }
ac54365a
GS
160
161Your mileage may vary when trying this trick with minutes and hours,
162and it doesn't work at all for months.
163
06ef4121
PC
164Strictly speaking, the year should also be specified in a form consistent
165with localtime(), i.e. the offset from 1900.
166In order to make the interpretation of the year easier for humans,
167however, who are more accustomed to seeing years as two-digit or four-digit
168values, the following conventions are followed:
169
170=over 4
171
172=item *
173
174Years greater than 999 are interpreted as being the actual year,
175rather than the offset from 1900. Thus, 1963 would indicate the year
90ca0aaa 176Martin Luther King won the Nobel prize, not the year 2863.
06ef4121
PC
177
178=item *
179
180Years in the range 100..999 are interpreted as offset from 1900,
181so that 112 indicates 2012. This rule also applies to years less than zero
182(but see note below regarding date range).
183
184=item *
185
186Years in the range 0..99 are interpreted as shorthand for years in the
187rolling "current century," defined as 50 years on either side of the current
188year. Thus, today, in 1999, 0 would refer to 2000, and 45 to 2045,
189but 55 would refer to 1955. Twenty years from now, 55 would instead refer
190to 2055. This is messy, but matches the way people currently think about
191two digit dates. Whenever possible, use an absolute four digit year instead.
192
193=back
194
195The scheme above allows interpretation of a wide range of dates, particularly
196if 4-digit years are used.
90ca0aaa 197
06ef4121
PC
198Please note, however, that the range of dates that can be actually be handled
199depends on the size of an integer (time_t) on a given platform.
200Currently, this is 32 bits for most systems, yielding an approximate range
201from Dec 1901 to Jan 2038.
202
203Both timelocal() and timegm() croak if given dates outside the supported
204range.
205
206=head1 IMPLEMENTATION
207
208These routines are quite efficient and yet are always guaranteed to agree
209with localtime() and gmtime(). We manage this by caching the start times
210of any months we've seen before. If we know the start time of the month,
211we can always calculate any time within the month. The start times
212themselves are guessed by successive approximation starting at the
213current time, since most dates seen in practice are close to the
214current date. Unlike algorithms that do a binary search (calling gmtime
215once for each bit of the time value, resulting in 32 calls), this algorithm
216calls it at most 6 times, and usually only once or twice. If you hit
217the month cache, of course, it doesn't call it at all.
218
219timelocal() is implemented using the same cache. We just assume that we're
220translating a GMT time, and then fudge it when we're done for the timezone
221and daylight savings arguments. Note that the timezone is evaluated for
222each date because countries occasionally change their official timezones.
223Assuming that localtime() corrects for these changes, this routine will
224also be correct. The daylight savings offset is currently assumed
225to be one hour.
226
227=head1 BUGS
228
229The whole scheme for interpreting two-digit years can be considered a bug.
230
231Note that the cache currently handles only years from 1900 through 2155.
232
233The proclivity to croak() is probably a bug.
234
235=cut