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