Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Date::Simple - a simple date object |
2 | ||
3 | package Date::Simple; | |
4 | ||
5 | $VERSION = '2.04'; | |
6 | use Exporter (); | |
7 | @ISA = ('Exporter'); | |
8 | @EXPORT_OK = ('today', 'ymd', 'd8', 'date', 'leap_year', 'days_in_month'); | |
9 | %EXPORT_TAGS = ('all' => \@EXPORT_OK); | |
10 | ||
11 | # Try to load the C code. If that fails, fall back to Date::Simple::NoXS. | |
12 | if (! defined (&_add)) { | |
13 | my ($err); | |
14 | { | |
15 | # Use DynaLoader instead of XSLoader for pre-5.005. | |
16 | local ($@); | |
17 | local @ISA = ('DynaLoader'); | |
18 | require DynaLoader; | |
19 | eval { __PACKAGE__->bootstrap ($VERSION); }; | |
20 | $err = $@; | |
21 | } | |
22 | if ($err) { | |
23 | require Date::Simple::NoXS; | |
24 | } | |
25 | } | |
26 | ||
27 | use strict; | |
28 | use Carp (); | |
29 | use overload | |
30 | '+' => '_add', | |
31 | '-' => '_subtract', | |
32 | '==' => '_eq', | |
33 | '!=' => '_ne', | |
34 | '<=>' => '_compare', | |
35 | 'eq' => '_eq', | |
36 | 'ne' => '_ne', | |
37 | 'cmp' => '_compare', | |
38 | 'bool' => sub { 1 }, | |
39 | '""' => '_stringify'; | |
40 | ||
41 | sub today { | |
42 | my ($y, $m, $d) = (localtime) [5, 4, 3]; | |
43 | $y += 1900; | |
44 | $m += 1; | |
45 | return ymd ($y, $m, $d); | |
46 | } | |
47 | ||
48 | sub _inval { | |
49 | my ($first); | |
50 | $first = shift; | |
51 | Carp::croak ("Invalid ".(ref($first)||$first)." constructor args: ('" | |
52 | .join("', '", @_)."')"); | |
53 | } | |
54 | ||
55 | sub _new { | |
56 | my ($that, @ymd) = @_; | |
57 | my ($class); | |
58 | ||
59 | $class = ref ($that) || $that; | |
60 | ||
61 | if (scalar (@ymd) == 1) { | |
62 | my $x = $ymd[0]; | |
63 | if (ref ($x) eq 'ARRAY') { | |
64 | @ymd = @$x; | |
65 | } | |
66 | elsif (UNIVERSAL::isa ($x, $class)) { | |
67 | return ($x); | |
68 | } | |
69 | elsif ($x =~ /^(\d\d\d\d)-(\d\d)-(\d\d)$/ | |
70 | || $x =~ /^(\d\d\d\d)(\d\d)(\d\d)$/) | |
71 | { | |
72 | @ymd = ($1, $2, $3); | |
73 | } | |
74 | else { | |
75 | return (undef); | |
76 | } | |
77 | } | |
78 | if (scalar (@ymd) == 0) { | |
79 | return (today()); | |
80 | } | |
81 | if (scalar (@ymd) == 3) { | |
82 | my $days = ymd_to_days (@ymd); | |
83 | return undef if ! defined ($days); | |
84 | return (bless (\$days, $class)); | |
85 | } | |
86 | _inval ($class, @ymd); | |
87 | } | |
88 | ||
89 | sub date { | |
90 | return (scalar (_new (__PACKAGE__, @_))); | |
91 | } | |
92 | ||
93 | # Same as date() but it's a method and croaks on error if called with | |
94 | # one arg. | |
95 | sub new { | |
96 | my ($date); | |
97 | ||
98 | $date = &_new; | |
99 | if (! $date && scalar (@_) == 1) { | |
100 | Carp::croak ("'" . shift() . "' is not a valid ISO formated date"); | |
101 | } | |
102 | return ($date); | |
103 | } | |
104 | ||
105 | sub next { return ($_[0] + 1); } | |
106 | sub prev { return ($_[0] - 1); } | |
107 | ||
108 | sub _gmtime { | |
109 | my ($y, $m, $d) = days_to_ymd (${$_[0]}); | |
110 | $y -= 1900; | |
111 | $m -= 1; | |
112 | return (0, 0, 0, $d, $m, $y); | |
113 | } | |
114 | ||
115 | sub format { | |
116 | my ($self, $format) = @_; | |
117 | return "$self" unless defined ($format); | |
118 | require POSIX; | |
119 | local $ENV{TZ} = 'UTC+0'; | |
120 | return POSIX::strftime ($format, _gmtime ($self)); | |
121 | } | |
122 | ||
123 | sub strftime { &format } | |
124 | ||
125 | 1; | |
126 | ||
127 | =head1 NAME | |
128 | ||
129 | Date::Simple - a simple date object | |
130 | ||
131 | =head1 SYNOPSIS | |
132 | ||
133 | use Date::Simple ('date', 'today'); | |
134 | ||
135 | # Difference in days between two dates: | |
136 | $diff = date('2001-08-27') - date('1977-10-05'); | |
137 | ||
138 | # Offset $n days from now: | |
139 | $date = today() + $n; | |
140 | print "$date\n"; # uses ISO 8601 format (YYYY-MM-DD) | |
141 | ||
142 | use Date::Simple (); | |
143 | my $date = Date::Simple->new('1972-01-17'); | |
144 | my $year = $date->year; | |
145 | my $month = $date->month; | |
146 | my $day = $date->day; | |
147 | ||
148 | use Date::Simple (':all'); | |
149 | my $date2 = ymd($year, $month, $day); | |
150 | my $date3 = d8('19871218'); | |
151 | my $today = today(); | |
152 | my $tomorrow = $today + 1; | |
153 | if ($tomorrow->year != $today->year) { | |
154 | print "Today is New Year's Eve!\n"; | |
155 | } | |
156 | ||
157 | if ($today > $tomorrow) { | |
158 | die "warp in space-time continuum"; | |
159 | } | |
160 | ||
161 | print "Today is "; | |
162 | print(('Sun','Mon','Tues','Wednes','Thurs','Fri','Satur') | |
163 | [$today->day_of_week]); | |
164 | print "day.\n"; | |
165 | ||
166 | # you can also do this: | |
167 | ($date cmp "2001-07-01") | |
168 | # and this | |
169 | ($date <=> [2001, 7, 1]) | |
170 | ||
171 | =begin text | |
172 | ||
173 | INSTALLATION | |
174 | ||
175 | If your system has the "make" program or a clone: | |
176 | ||
177 | perl Makefile.PL | |
178 | make | |
179 | make test | |
180 | make install | |
181 | ||
182 | If you lack "make", copy the "lib/Date" directory to your module | |
183 | directory (run "perl -V:sitelib" to find it). | |
184 | ||
185 | If "make test" fails, perhaps it means your system can't compile C | |
186 | code. Try: | |
187 | ||
188 | make distclean | |
189 | perl Makefile.PL noxs | |
190 | make | |
191 | make test | |
192 | make install | |
193 | ||
194 | This will use the pure-Perl implementation. | |
195 | ||
196 | =end text | |
197 | ||
198 | =head1 DESCRIPTION | |
199 | ||
200 | Dates are complex enough without times and timezones. This module may | |
201 | be used to create simple date objects. It handles: | |
202 | ||
203 | =over 4 | |
204 | ||
205 | =item Validation. | |
206 | ||
207 | Reject 1999-02-29 but accept 2000-02-29. | |
208 | ||
209 | =item Interval arithmetic. | |
210 | ||
211 | How many days were between two given dates? What date comes N days | |
212 | after today? | |
213 | ||
214 | =item Day-of-week calculation. | |
215 | ||
216 | What day of the week is a given date? | |
217 | ||
218 | =back | |
219 | ||
220 | It does B<not> deal with hours, minutes, seconds, and time zones. | |
221 | ||
222 | A date is uniquely identified by year, month, and day integers within | |
223 | valid ranges. This module will not allow the creation of objects for | |
224 | invalid dates. Attempting to create an invalid date will return | |
225 | undef. Month numbering starts at 1 for January, unlike in C and Java. | |
226 | Years are 4-digit. | |
227 | ||
228 | Gregorian dates up to year 9999 are handled correctly, but we rely on | |
229 | Perl's builtin C<localtime> function when the current date is | |
230 | requested. On some platforms, C<localtime> may be vulnerable to | |
231 | rollovers such as the Unix C<time_t> wraparound of 18 January 2038. | |
232 | ||
233 | Overloading is used so you can compare or subtract two dates using | |
234 | standard numeric operators such as C<==>, and the sum of a date object | |
235 | and an integer is another date object. | |
236 | ||
237 | Date::Simple objects are immutable. After assigning C<$date1> to | |
238 | C<$date2>, no change to C<$date1> can affect C<$date2>. This means, | |
239 | for example, that there is nothing like a C<set_year> operation, and | |
240 | C<$date++> assigns a new object to C<$date>. | |
241 | ||
242 | This module contains various undocumented functions. They may not be | |
243 | available on all platforms and are likely to change or disappear in | |
244 | future releases. Please let the author know if you think any of them | |
245 | should be public. | |
246 | ||
247 | =cut | |
248 | ||
249 | =head1 CONSTRUCTORS | |
250 | ||
251 | Several functions take a string or numeric representation and generate | |
252 | a corresponding date object. The most general is C<new>, whose | |
253 | argument list may be empty (returning the current date), a string in | |
254 | format YYYY-MM-DD or YYYYMMDD, a list or arrayref of year, month, and | |
255 | day number, or an existing date object. | |
256 | ||
257 | =over 4 | |
258 | ||
259 | =item Date::Simple->new ([ARG, ...]) | |
260 | ||
261 | =item date ([ARG, ...]) | |
262 | ||
263 | my $date = Date::Simple->new('1972-01-17'); | |
264 | ||
265 | The C<new> method will return a date object if the values passed in | |
266 | specify a valid date. (See above.) If an invalid date is passed, the | |
267 | method returns undef. If the argument is invalid in form as opposed | |
268 | to numeric range, C<new> dies. | |
269 | ||
270 | The C<date> function provides the same functionality but must be | |
271 | imported or qualified as C<Date::Simple::date>. (To import all public | |
272 | functions, do C<use Date::Simple (':all');>.) This function returns | |
273 | undef on all invalid input, rather than dying in some cases like | |
274 | C<new>. | |
275 | ||
276 | =item today() | |
277 | ||
278 | Returns the current date according to C<localtime>. | |
279 | ||
280 | B<Caution:> To get tomorrow's date (or any fixed offset from today), | |
281 | do not use C<today + 1>. Perl parses this as C<today(+1)>. You need | |
282 | to put empty parentheses after the function: C<today() + 1>. | |
283 | ||
284 | =item ymd (YEAR, MONTH, DAY) | |
285 | ||
286 | Returns a date object with the given year, month, and day numbers. If | |
287 | the arguments do not specify a valid date, undef is returned. | |
288 | ||
289 | Example: | |
290 | ||
291 | use Date::Simple ('ymd'); | |
292 | $pbd = ymd(1987, 12, 18); | |
293 | ||
294 | =item d8 (STRING) | |
295 | ||
296 | Parses STRING as "YYYYMMDD" and returns the corresponding date object, | |
297 | or undef if STRING has the wrong format or specifies an invalid date. | |
298 | ||
299 | Example: | |
300 | ||
301 | use Date::Simple ('d8'); | |
302 | $doi = d8('17760704'); | |
303 | ||
304 | Mnemonic: The string matches C</\d{8}/>. Also, "d8" spells "date", if | |
305 | 8 is expanded phonetically. | |
306 | ||
307 | =back | |
308 | ||
309 | =head1 INSTANCE METHODS | |
310 | ||
311 | =over 4 | |
312 | ||
313 | =item DATE->next | |
314 | ||
315 | my $tomorrow = $today->next; | |
316 | ||
317 | Returns an object representing tomorrow. | |
318 | ||
319 | =item DATE->prev | |
320 | ||
321 | my $yesterday = $today->prev; | |
322 | ||
323 | Returns an object representing yesterday. | |
324 | ||
325 | =item DATE->year | |
326 | ||
327 | my $year = $date->year; | |
328 | ||
329 | Return the year of DATE as an integer. | |
330 | ||
331 | =item DATE->month | |
332 | ||
333 | my $month = $date->month; | |
334 | ||
335 | Return the month of DATE as an integer from 1 to 12. | |
336 | ||
337 | =item DATE->day | |
338 | ||
339 | my $day = $date->day; | |
340 | ||
341 | Return the DATE's day of the month as an integer from 1 to 31. | |
342 | ||
343 | =item DATE->day_of_week | |
344 | ||
345 | Return a number representing DATE's day of the week from 0 to 6, where | |
346 | 0 means Sunday. | |
347 | ||
348 | =item DATE->as_ymd | |
349 | ||
350 | my ($year, $month, $day) = $date->as_ymd; | |
351 | ||
352 | Returns a list of three numbers: year, month, and day. | |
353 | ||
354 | =item DATE->as_d8 | |
355 | ||
356 | Returns the "d8" representation (see C<d8>), like | |
357 | C<$date-E<gt>format("%Y%m%d")>. | |
358 | ||
359 | =item DATE->format (STRING) | |
360 | ||
361 | =item DATE->strftime (STRING) | |
362 | ||
363 | These functions are equivalent. Return a string representing the | |
364 | date, in the format specified. If you don't pass a parameter, an ISO | |
365 | 8601 formatted date is returned. | |
366 | ||
367 | my $change_date = $date->format("%d %b %y"); | |
368 | my $iso_date1 = $date->format("%Y-%m-%d"); | |
369 | my $iso_date2 = $date->format; | |
370 | ||
371 | The formatting parameter is similar to one you would pass to | |
372 | strftime(3). This is because we actually do pass it to strftime to | |
373 | format the date. This may result in differing behavior across | |
374 | platforms and locales and may not even work everywhere. | |
375 | ||
376 | =back | |
377 | ||
378 | =head1 OPERATORS | |
379 | ||
380 | Some operators can be used with Date::Simple instances. If one side | |
381 | of an expression is a date object, and the operator expects two date | |
382 | objects, the other side is interpreted as C<date(ARG)>, so an array | |
383 | reference or ISO 8601 string will work. | |
384 | ||
385 | =over 4 | |
386 | ||
387 | =item DATE + NUMBER | |
388 | ||
389 | =item DATE - NUMBER | |
390 | ||
391 | You can construct a new date offset by a number of days using the C<+> | |
392 | and C<-> operators. | |
393 | ||
394 | =item DATE1 - DATE2 | |
395 | ||
396 | You can subtract two dates to find the number of days between them. | |
397 | ||
398 | =item DATE1 == DATE2 | |
399 | ||
400 | =item DATE1 < DATE2 | |
401 | ||
402 | =item DATE1 <=> DATE2 | |
403 | ||
404 | =item DATE1 cmp DATE2 | |
405 | ||
406 | =item etc. | |
407 | ||
408 | You can compare two dates using the arithmetic or string comparison | |
409 | operators. Equality tests (C<==> and C<eq>) return false when one of | |
410 | the expressions can not be converted to a date. Other comparison | |
411 | tests die in such cases. This is intentional, because in a sense, all | |
412 | non-dates are not "equal" to all dates, but in no sense are they | |
413 | "greater" or "less" than dates. | |
414 | ||
415 | =item DATE += NUMBER | |
416 | ||
417 | =item DATE -= NUMBER | |
418 | ||
419 | You can increment or decrement a date by a number of days using the += | |
420 | and -= operators. This actually generates a new date object and is | |
421 | equivalent to C<$date = $date + $number>. | |
422 | ||
423 | =item "$date" | |
424 | ||
425 | You can interpolate a date instance directly into a string, in the | |
426 | format specified by ISO 8601 (eg: 2000-01-17). | |
427 | ||
428 | =back | |
429 | ||
430 | =head1 UTILITIES | |
431 | ||
432 | =over 4 | |
433 | ||
434 | =item leap_year (YEAR) | |
435 | ||
436 | Returns true if YEAR is a leap year. | |
437 | ||
438 | =item days_in_month (YEAR, MONTH) | |
439 | ||
440 | Returns the number of days in MONTH, YEAR. | |
441 | ||
442 | =back | |
443 | ||
444 | =head1 AUTHOR | |
445 | ||
446 | Marty Pauley <marty@kasei.com> | |
447 | John Tobey <jtobey@john-edwin-tobey.org> | |
448 | ||
449 | =head1 COPYRIGHT | |
450 | ||
451 | Copyright (C) 2001 Kasei | |
452 | Copyright (C) 2001,2002 John Tobey. | |
453 | ||
454 | This program is free software; you can redistribute it and/or | |
455 | modify it under the terms of either: | |
456 | ||
457 | a) the GNU General Public License; | |
458 | either version 2 of the License, or (at your option) any later | |
459 | version. You should have received a copy of the GNU General | |
460 | Public License along with this program; see the file COPYING. | |
461 | If not, write to the Free Software Foundation, Inc., 59 | |
462 | Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
463 | ||
464 | b) the Perl Artistic License. | |
465 | ||
466 | This program is distributed in the hope that it will be useful, | |
467 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
468 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | |
469 | ||
470 | =cut |