/Class-Date-1.1.9/Date.pod
Unknown | 797 lines | 576 code | 221 blank | 0 comment | 0 complexity | 14f0136a556bfbdc50a4af3ef45bf277 MD5 | raw file
1=head1 NAME
2
3Class::Date - Class for easy date and time manipulation
4
5=head1 SYNOPSIS
6
7 use Class::Date qw(:errors date localdate gmdate now -DateParse -EnvC);
8
9 # creating absolute date object (local time)
10 $date = new Class::Date [$year,$month,$day,$hour,$min,$sec];
11 $date = date [$year,$month,$day,$hour,$min,$sec];
12 # ^- "date" is an exportable function, the same as Class::Date->new
13 $date = date { year => $year, month => $month, day => $day,
14 hour => $hour, min => $min, sec => $sec };
15 $date = date "2001-11-12 07:13:12";
16 $date = localdate "2001-12-11";
17 $date = now; # the same as date(time)
18 $date = date($other_date_object); # cloning
19 ...
20
21 # creating absolute date object (GMT)
22 $date = new Class::Date [$year,$month,$day,$hour,$min,$sec],'GMT';
23 $date = gmdate "2001-11-12 17:13";
24 ...
25
26 # creating absolute date object in any other timezone
27 $date = new Class::Date [$year,$month,$day,$hour,$min,$sec],'Iceland';
28 $date = date "2001-11-12 17:13", 'Iceland';
29 $date2 = $date->new([$y2, $m2, $d2, $h2, $m2, $s2]);
30 # ^- timezone is inherited from the $date object
31
32 # creating relative date object
33 # (normally you don't need to create this object explicitly)
34 $reldate = new Class::Date::Rel "3Y 1M 3D 6h 2m 4s";
35 $reldate = new Class::Date::Rel "6Y";
36 $reldate = new Class::Date::Rel $secs; # secs
37 $reldate = new Class::Date::Rel [$year,$month,$day,$hour,$min,$sec];
38 $reldate = new Class::Date::Rel { year => $year, month => $month, day => $day,
39 hour => $hour, min => $min, sec => $sec };
40 $reldate = new Class::Date::Rel "2001-11-12 07:13:12";
41 $reldate = new Class::Date::Rel "2001-12-11";
42
43 # getting values of an absolute date object
44 $date; # prints the date in default output format (see below)
45 $date->year; # year, e.g: 2001
46 $date->_year; # year - 1900, e.g. 101
47 $date->yr; # 2-digit year 0-99, e.g 1
48 $date->mon; # month 1..12
49 $date->month; # same as prev.
50 $date->_mon; # month 0..11
51 $date->_month; # same as prev.
52 $date->day; # day of month
53 $date->mday; # day of month
54 $date->day_of_month;# same as prev.
55 $date->hour;
56 $date->min;
57 $date->minute; # same as prev.
58 $date->sec;
59 $date->second; # same as prev.
60 $date->wday; # 1 = Sunday
61 $date->_wday; # 0 = Sunday
62 $date->day_of_week; # same as prev.
63 $date->yday;
64 $date->day_of_year; # same as prev.
65 $date->isdst; # DST?
66 $date->daylight_savings; # same as prev.
67 $date->epoch; # UNIX time_t
68 $date->monname; # name of month, eg: March
69 $date->monthname; # same as prev.
70 $date->wdayname; # Thursday
71 $date->day_of_weekname # same as prev.
72 $date->hms # 01:23:45
73 $date->ymd # 2000/02/29
74 $date->mdy # 02/29/2000
75 $date->dmy # 29/02/2000
76 $date->meridiam # 01:23 AM
77 $date->ampm # AM/PM
78 $date->string # 2000-02-29 12:21:11 (format can be changed, look below)
79 "$date" # same as prev.
80 $date->tzoffset # timezone-offset
81 $date->strftime($format) # POSIX strftime (without the huge POSIX.pm)
82 $date->tz # returns the base timezone as you specify, eg: CET
83 $date->tzdst # returns the real timezone with dst information, eg: CEST
84
85 ($year,$month,$day,$hour,$min,$sec)=$date->array;
86 ($year,$month,$day,$hour,$min,$sec)=@{ $date->aref };
87 # !! $year: 1900-, $month: 1-12
88
89 ($sec,$min,$hour,$day,$mon,$year,$wday,$yday,$isdst)=$date->struct;
90 ($sec,$min,$hour,$day,$mon,$year,$wday,$yday,$isdst)=@{ $date->sref };
91 # !! $year: 0-, $month: 0-11
92
93 $hash=$date->href; # $href can be reused as a constructor
94 print $hash->{year}."-".$hash->{month}. ... $hash->{sec} ... ;
95
96 %hash=$date->hash;
97 # !! $hash{year}: 1900-, $hash{month}: 1-12
98
99 $date->month_begin # First day of the month (date object)
100 $date->month_end # Last day of the month
101 $date->days_in_month # 28..31
102
103 # constructing new date based on an existing one:
104 $new_date = $date->clone;
105 $new_date = $date->clone( year => 1977, sec => 14 );
106 # valid keys: year, _year, month, mon, _month, _mon, day, mday, day_of_month,
107 # hour, min, minute, sec, second, tz
108 # constructing a new date, which is the same as the original, but in
109 # another timezone:
110 $new_date = $date->to_tz('Iceland');
111
112 # changing date format
113 {
114 local $Class::Date::DATE_FORMAT="%Y%m%d%H%M%S";
115 print $date # result: 20011222000000
116 $Class::Date::DATE_FORMAT=undef;
117 print $date # result: Thu Oct 13 04:54:34 1994
118 $Class::Date::DATE_FORMAT="%Y/%m/%d"
119 print $date # result: 1994/10/13
120 }
121
122 # error handling
123 $a = date($date_string);
124 if ($a) { # valid date
125 ...
126 } else { # invalid date
127 if ($a->error == E_INVALID) { ... }
128 print $a->errstr;
129 }
130
131 # adjusting DST in calculations (see the doc)
132 $Class::Date::DST_ADJUST = 1; # this is the default
133 $Class::Date::DST_ADJUST = 0;
134
135 # "month-border adjust" flag
136 $Class::Date::MONTH_BORDER_ADJUST = 0; # this is the default
137 print date("2001-01-31")+'1M'; # will print 2001-03-03
138 $Class::Date::MONTH_BORDER_ADJUST = 1;
139 print date("2001-01-31")+'1M'; # will print 2001-02-28
140
141 # date range check
142 $Class::Date::RANGE_CHECK = 0; # this is the default
143 print date("2001-02-31"); # will print 2001-03-03
144 $Class::Date::RANGE_CHECK = 1;
145 print date("2001-02-31"); # will print nothing
146
147 # getting values of a relative date object
148 $reldate; # reldate in seconds (assumed 1 month = 2_629_744 secs)
149 $reldate->year;
150 $reldate->mon;
151 $reldate->month; # same as prev.
152 $reldate->day;
153 $reldate->hour;
154 $reldate->min;
155 $reldate->minute; # same as prev.
156 $reldate->sec; # same as $reldate
157 $reldate->second; # same as prev.
158 $reldate->sec_part; # "second" part of the relative date
159 $reldate->mon_part; # "month" part of the relative date
160
161 # arithmetic with dates:
162 print date([2001,12,11,4,5,6])->truncate;
163 # will print "2001-12-11"
164 $new_date = $date+$reldate;
165 $date2 = $date+'3Y 2D'; # 3 Years and 2 days
166 $date3 = $date+[1,2,3]; # $date plus 1 year, 2 months, 3 days
167 $date4 = $date+'3-1-5' # $date plus 3 years, 1 months, 5 days
168
169 $new_date = $date-$reldate;
170 $date2 = $date-'3Y'; # 3 Yearss
171 $date3 = $date-[1,2,3]; # $date minus 1 year, 2 months, 3 days
172 $date4 = $date-'3-1-5' # $date minus 3 years, 1 month, 5 days
173
174 $new_reldate = $date1-$date2;
175 $reldate2 = Class::Date->new('2000-11-12')-'2000-11-10';
176 $reldate3 = $date3-'1977-11-10';
177
178 $days_between = (Class::Date->new('2001-11-12')-'2001-07-04')->day;
179
180 # comparison between absolute dates
181 print $date1 > $date2 ? "I am older" : "I am younger";
182
183 # comparison between relative dates
184 print $reldate1 > $reldate2 ? "I am faster" : "I am slower";
185
186 # Adding / Subtracting months and years are sometimes tricky:
187 print date("2001-01-29") + '1M' - '1M'; # gives "2001-02-01"
188 print date("2000-02-29") + '1Y' - '1Y'; # gives "2000-03-01"
189
190 # Named interface ($date2 does not necessary to be a Class::Date object)
191 $date1->string; # same as $date1 in scalar context
192 $date1->subtract($date2); # same as $date1 - $date2
193 $date1->add($date2); # same as $date1 + $date2
194 $date1->compare($date2); # same as $date1 <=> $date2
195
196 $reldate1->sec; # same as $reldate1 in numeric or scalar context
197 $reldate1->compare($reldate2);# same as $reldate1 <=> $reldate2
198 $reldate1->add($reldate2); # same as $reldate1 + $reldate2
199 $reldate1->neg # used for subtraction
200
201 # Disabling Class::Date warnings at load time
202 BEGIN { $Class::Date::WARNINGS=0; }
203 use Class::Date;
204
205=head1 DESCRIPTION
206
207This module is intended to provide a general-purpose date and datetime type
208for perl. You have a Class::Date class for absolute date and datetime, and have
209a Class::Date::Rel class for relative dates.
210
211You can use "+", "-", "<" and ">" operators as with native perl data types.
212
213=head1 USAGE
214
215If you want to use a date object, you need to do the following:
216
217 - create a new object
218 - do some operations (+, -, comparison)
219 - get result back
220
221=head2 Creating a new date object
222
223You can create a date object by the "date", "localdate" or "gmdate" function,
224or by calling the Class::Date constructor.
225
226"date" and "Class::Date->new" are equivalent, both has two arguments: The
227date and the timezone.
228
229 $date1= date [2000,11,12];
230 $date2= Class::Date->new([2000,06,11,13,11,22],'GMT');
231 $date2= $date1->new([2000,06,11,13,11,22]);
232
233If the timezone information is omitted, then it first check if "new" is
234called as an object method or a class method. If it is an object method,
235then it inherits the timezone from the base object, otherwise the default
236timezone is used ($Class::Date::DEFAULT_TIMEZONE), which is usually set to
237the local timezone (which is stored in $Class::Date::LOCAL_TIMEZONE). These
238two variables are set only once to the value, which is returned by the
239Class::Date::local_timezone() function. You can change these values
240whenever you want.
241
242"localdate $x" is equivalent to "date $x, $Class::Date::LOCAL_TIMEZONE",
243"gmdate $x" is equivalent to "date $x, $Class::Date::GMT_TIMEZONE".
244
245$Class::Date::GMT_TIMEZONE is set to 'GMT' by default.
246
247 $date1= localdate [2000,11,12];
248 $date2= gmdate [2000,4,2,3,33,33];
249
250 $date = localdate(time);
251
252The format of the accepted input date can be:
253
254=over 4
255
256=item [$year,$month,$day,$hour,$min,$sec]
257
258An array reference with 6 elements. The missing elements have default
259values (year: 2000, month, day: 1, hour, min, sec: 0)
260
261=item { year => $year, month => $month, day => $day, hour => $hour, min => $min, sec => $sec }
262
263A hash reference with the same 6 elements as above.
264
265=item "YYYYMMDDhhmmss"
266
267A mysql-style timestamp value, which consist of at least 14 digit.
268
269=item "973897262"
270
271A valid 32-bit integer: This is parsed as a unix time.
272
273=item "YYYY-MM-DD hh:mm:ss"
274
275A standard ISO(-like) date format. Additional ".fraction" part is ignored,
276":ss" can be omitted.
277
278=item additional input formats
279
280You can specify "-DateParse" as an import parameter, e.g:
281
282 use Class::Date qw(date -DateParse);
283
284With this, the module will try to load Date::Parse module, and if it find it then all
285these formats can be used as an input. Please refer to the Date::Parse
286documentation.
287
288=back
289
290=head2 Operations
291
292=over 4
293
294=item addition
295
296You can add the following to a Class::Date object:
297
298 - a valid Class::Date::Rel object
299 - anything, that can be used for creating a new Class::Date::Rel object
300
301It means that you don't need to create a new Class::Date::Rel object every
302time when you add something to the Class::Date object, it creates them
303automatically:
304
305 $date= Class::Date->new('2001-12-11')+Class::Date::Rel->new('3Y');
306
307is the same as:
308
309 $date= date('2001-12-11')+'3Y';
310
311You can provide a Class::Date::Rel object in the following form:
312
313=over 4
314
315=item array ref
316
317The same format as seen in Class::Date format, except the default values are
318different: all zero.
319
320=item hash ref
321
322The same format as seen in Class::Date format, except the default values are
323different: all zero.
324
325=item "973897262"
326
327A valid 32-bit integer is parsed as seconds.
328
329=item "YYYY-MM-DD hh:mm:ss"
330
331A standard ISO date format, but this is parsed as relative date date and time,
332so month, day and year can be zero (and defaults to zero).
333
334=item "12Y 6M 6D 20h 12m 5s"
335
336This special string can be used if you don't want to use the ISO format. This
337string consists of whitespace separated tags, each tag consists of a number and
338a unit. The units can be:
339
340 Y: year
341 M: month
342 D: day
343 h: hour
344 m: min
345 s: sec
346
347The number and unit must be written with no space between them.
348
349=back
350
351=item substraction
352
353The same rules are true for substraction, except you can substract
354two Class::Date object from each other, and you will get a Class::Date::Rel
355object:
356
357 $reldate=$date1-$date2;
358 $reldate=date('2001-11-12 12:11:07')-date('2001-10-07 10:3:21');
359
360In this case, the "month" field of the $reldate object will be 0,
361and the other fields will contain the difference between two dates;
362
363=item comparison
364
365You can compare two Class::Date objects, or one Class::Date object and
366another data, which can be used for creating a new Class::Data object.
367
368It means that you don't need to bless both objects, one of them can be a
369simple string, array ref, hash ref, etc (see how to create a date object).
370
371 if ( date('2001-11-12') > date('2000-11-11') ) { ... }
372
373or
374
375 if ( date('2001-11-12') > '2000-11-11' ) { ... }
376
377=item truncate
378
379You can chop the time value from this object (set hour, min and sec to 0)
380with the "truncate" or "trunc" method. It does not modify the specified
381object, it returns with a new one.
382
383=item clone
384
385You can create new date object based on an existing one, by using the "clone"
386method. Note, this DOES NOT modify the base object.
387
388 $new_date = $date->clone( year => 2001, hour => 14 );
389
390The valid keys are: year, _year, month, mon, _month, _mon, day, mday,
391day_of_month, hour, min, minute, sec, second, tz.
392
393There is a "set" method, which does the same as the "clone", it exists
394only for compatibility.
395
396=item to_tz
397
398You can use "to_tz" to create a new object, which means the same time as
399the base object, but in the different timezone.
400
401Note that $date->clone( tz => 'Iceland') and $date->to_tz('Iceland') is not
402the same! Cloning a new object with setting timezone will preserve the
403time information (hour, minute, second, etc.), but transfer the time into
404other timezone, while to_tz usually change these values based on the
405difference between the source and the destination timezone.
406
407=item Operations with Class::Date::Rel
408
409The Class::Date::Rel object consists of a month part and a day part. Most
410people only use the "day" part of it. If you use both part, then you can get
411these parts with the "sec_part" and "mon_part" method. If you use "sec",
412"month", etc. methods or if you use this object in a mathematical conent,
413then this object is converted to one number, which is interpreted as second.
414The conversion is based on a 30.436 days month. Don't use it too often,
415because it is confusing...
416
417If you use Class::Date::Rel in an expression with other Class::Date or
418Class::Date::Rel objects, then it does what is expected:
419
420 date('2001-11-12')+'1M' will be '2001-12-12'
421
422and
423
424 date('1996-02-11')+'2M' will be '1996-04-11'
425
426=back
427
428=head2 Accessing data from a Class::Date and Class::Date::Rel object
429
430You can use the methods methods described at the top of the document
431if you want to access parts of the data
432which is stored in a Class::Date and Class::Date::Rel object.
433
434=head2 Error handling
435
436If a date object became invalid, then the object will be reblessed to
437Class::Date::Invalid. This object is false in boolean environment, so you can
438test the date validity like this:
439
440 $a = date($input_date);
441 if ($a) { # valid date
442 ...
443 } else { # invalid date
444 if ($a->error == E_INVALID) { ... }
445 print $a->errstr;
446 }
447
448Note even the date is invalid, the expression "defined $a" always returns
449true, so the following is wrong:
450
451 $a = date($input_date);
452 if (defined $a) ... # WRONG!!!!
453
454You can test the error by getting the $date->error value. You might import
455the ":errors" tag:
456
457 use Class::Date qw(:errors);
458
459Possible error values are:
460
461=over 4
462
463=item E_OK
464
465No errors.
466
467=item E_INVALID
468
469Invalid date. It is set when some of the parts of the date are invalid, and
470Time::Local functions cannot convert them to a valid date.
471
472=item E_RANGE
473
474This error is set, when parts of the date are valid, but the whole date is
475not valid, e.g. 2001-02-31. When the $Class::Date::RANGE_CHECK is not set, then
476these date values are automatically converted to a valid date: 2001-03-03,
477but the $date->error value are set to E_RANGE. If $Class::Date::RANGE_CHECK
478is set, then a date "2001-02-31" became invalid date.
479
480=item E_UNPARSABLE
481
482This error is set, when the constructor cannot be created from a scalar, e.g:
483
484 $a = date("4kd sdlsdf lwekrmk");
485
486=item E_UNDEFINED
487
488This error is set, when you want to create a date object from an undefined
489value:
490
491 $a = new Class::Date (undef);
492
493Note, that localdate(undef) will create a valid object, because it calls
494$Class::Date(time).
495
496=back
497
498You can get the error in string form by calling the "errstr" method.
499
500=head1 DST_ADJUST
501
502$DST_ADJUST is an importable variable, and is a very important configuration
503option.
504
505If it is set to true (default), then it adjusts the date and time when the
506operation switches the border of DST. You will see the difference if you run
507this code:
508
509 $Class::Date::DST_ADJUST=0;
510 for (my $date=localdate("2000-06-11");$date<"2001-4-5";$date+='1D') {
511 print $date."\n";
512 }
513
514 $Class::Date::DST_ADJUST=1;
515 for (my $date=localdate("2000-06-11");$date<"2001-4-5";$date+='1D') {
516 print $date."\n";
517 }
518
519=head1 MONTHS AND YEARS
520
521If you add or subtract "months" and "years" to a date, you may get wrong
522dates, e.g when you add one month to 2001-01-31, you expect to get
5232001-02-31, but this date is invalid and converted to 2001-03-03. Thats' why
524
525 date("2001-01-31") + '1M' - '1M' != "2001-01-31"
526
527This problem can occur only with months and years, because others can
528easily be converted to seconds.
529
530=head1 MONTH_BORDER_ADJUST
531
532$MONTH_BORDER_ADJUST variable is used to switch on or off the
533month-adjust feature. This is used only when someone adds months or years to
534a date and then the resulted date became invalid. An example: adding one
535month to "2001-01-31" will result "2001-02-31", and this is an invalid date.
536
537When $MONTH_BORDER_ADJUST is false, this result simply normalized, and
538becomes "2001-03-03". This is the default behaviour.
539
540When $MONTH_BORDER_ADJUST is true, this result becomes "2001-02-28". So when
541the date overflows, then it returns the last day insted.
542
543Both settings keeps the time information.
544
545=head1 WORKING WITHOUT A C COMPILER
546
547Class::Date can be used without a C compiler since 1.0.8. If you want to do
548this, you only need to copy the "Date.pm" whereever your perl compiler searches
549for it. You must make a "Class" directory for it before.
550
551In Debian GNU/Linux system (woody) , a good choice can be the following:
552
553 mkdir /usr/local/share/perl/5.6.1/Class
554 cp Date.pm /usr/local/share/perl/5.6.1/Class
555
556And the module will work.
557
558You can use the $WARNINGS switch to switch off the complains about the missing
559XS part from your perl program:
560
561 BEGIN { $Class::Date::WARNINGS=0; }
562 use Class::Date;
563 ...
564
565=head1 TIMEZONE SUPPORT
566
567Since 1.0.11, Class::Date handle timezones natively on most platforms (see
568the BUGS AND LIMITATIONS section for more info).
569
570When the module is loaded, then it determines the local base timezone by
571calling the Class::Date::local_timezone() function, and stores these values
572into two variables, these are: $Class::Date::LOCAL_TIMEZONE and
573$Class::Date::DEFAULT_TIMEZONE. The first value is used, when you call the
574"localdate" function, the second value is used, when you call the "date"
575function and you don't specify the timezone. There is
576a $Class::Date::GMT_TIMEZONE function also, which is used by the "gmdate"
577function, this is set to 'GMT'.
578
579You can query the timezone of a date object by calling the $date->tz
580method. Note this value returns the timezone as you specify, so if you
581create the object with an unknown timezone, you will get this back. If you
582want to query the effective timezone, you can call the $date->tzdst method.
583This method returns only valid timezones, but it is not necessarily the
584timezone, which can be used to create a new object. For example
585$date->tzdst can return 'CEST', which is not a valid base timezone, because
586it contains daylight savings information also. On Linux systems, you can
587see the possible base timezones in the /usr/share/zoneinfo directory.
588
589In Class::Date 1.1.6, a new environment variable is introduced:
590$Class::Date::NOTZ_TIMEZONE. This variable stores the local timezone, which
591is used, when the TZ environment variable is not set. It is introduced,
592because there are some systems, which cannot handle the queried timezone
593well. For example the local timezone is CST, it is returned by the tzname()
594perl function, but when I set the TZ environment variable to CST, it
595works like it would be GMT. The workaround is NOTZ_TIMEZONE: if a date
596object has a timezone, which is the same as NOTZ_TIMEZONE, then the TZ
597variable will be removed before each calculation. In normal case, it would
598be the same as setting TZ to $NOTZ_TIMEZONE, but some systems don't like
599it, so I decided to introduce this variable. The
600$Class::Date::NOTZ_TIMEZONE variable is set in the initialization of the
601module by removing the TZ variable from the environment and querying the
602tzname variable.
603
604=head1 INTERNALS
605
606This module uses operator overloading very heavily. I've found it quite stable,
607but I am afraid of it a bit.
608
609A Class::Date object is an array reference.
610
611A Class::Date::Rel object is an array reference, which contains month and
612second information. I need to store it as an array ref, because array and month
613values cannot be converted into seconds, because of our super calendar.
614
615You can add code references to the @Class::Date::NEW_FROM_SCALAR and
616@Class::Date::Rel::NEW_FROM_SCALAR. These arrays are iterated through when a
617scalar-format date must be parsed. These arrays only have one or two values
618at initialization. The parameters which the code references got are the same
619as the "new" method of each class. In this way, you can personalize the date
620parses as you want.
621
622As of 0.90, the Class::Date has been rewritten. A lot of code and design
623decision has been borrowed from Matt Sergeant's Time::Object, and there will
624be some incompatibility with the previous public version (0.5). I tried to
625keep compatibility methods in Class::Date. If you have problems regarding
626this, please drop me an email with the description of the problem, and I will
627set the compatibility back.
628
629Invalid dates are Class::Date::Invalid objects. Every method call on this
630object and every operation with this object returns undef or 0.
631
632=head1 DEVELOPMENT FOCUS
633
634This module tries to be as full-featured as can be. It currently lacks
635business-day calculation, which is planned to be implemented in the 1.0.x
636series.
637
638I try to keep this module not to depend on other modules and I want this
639module usable without a C compiler.
640
641Currently the module uses the POSIX localtime function very extensively.
642This makes the date calculation a bit slow, but provides a rich interface,
643which is not provided by any other module. When I tried to redesign the
644internals to not depend on localtime, I failed, because there are no other
645way to determine the daylight savings information.
646
647=head1 SPEED ISSUES
648
649There are two kind of adjustment in this module, DST_ADJUST and
650MONTH_BORDER_ADJUST. Both of them makes the "+" and "-" operations slower. If
651you don't need them, switch them off to achieve faster calculations.
652
653In general, if you really need fast date and datetime calculation, don't use
654this module. As you see in the previous section, the focus of development is
655not the speed in 1.0. For fast date and datetime calculations, use
656Date::Calc module instead.
657
658=head1 THREAD SAFETY and MOD_PERL
659
660This module is NOT thread-safe, since it uses C library functions, which
661are not thread-safe. Using this module in a multi-threaded environment can
662cause timezones to be messed up. I did not put any warning about it, you
663have to make sure that you understand this!
664
665Under some circumstances in a mod_perl environment, you require the Env::C
666module to set the TZ variable properly before calling the time functions. I
667added the -EnvC import option to automatically load this module if it is
668not loaded already. Please read the mod_perl documentation about the
669environment variables and mod_perl to get the idea why it is required
670sometimes:
671
672 http://perl.apache.org/docs/2.0/user/troubleshooting/troubleshooting.html#C_Libraries_Don_t_See_C__ENV__Entries_Set_by_Perl_Code
673
674You are sure have this problem if the $Class::Date::NOTZ_TIMEZONE variable
675is set to 'UTC', althought you are sure that your timezone is not that. Try
676-EnvC in this case, but make sure that you are not using it in a
677multi-threaded environment!
678
679=head1 OTHER BUGS AND LIMITATIONS
680
681=over 4
682
683=item *
684
685I cannot manage to get the timezone code working properly on ActivePerl
6865.8.0 on win XP and earlier versions possibly have this problem also. If
687you have a system like this, then you will have only two timezones, the
688local and the GMT. Every timezone, which is not equal to
689$Class::Date::GMT_TIMEZONE is assumed to be local. This seems to be caused
690by the win32 implementation of timezone routines. I don't really know how
691to make this thing working, so I gave up this issue. If anyone know a
692working solution, then I will integrate it into Class::Date, but until
693then, the timezone support will not be available for these platforms.
694
695=item *
696
697Perl 5.8.0 and earlier versions has a bug in the strftime code on some
698operating systems (for example Linux), which is timezone related. I
699recommend using the strftime, which is provided with Class::Date, so don't
700try to use the module without the compiled part. The module will not work
701with a buggy strftime - the test is hardcoded into the beginning of the
702code. If you anyway want to use the module, remove the hardcoded "die" from
703the module, but do it for your own risk.
704
705=item *
706
707This module uses the POSIX functions for date and
708time calculations, so it is not working for dates beyond 2038 and before 1902.
709
710I don't know what systems support dates in 1902-1970 range, it may not work on
711your system. I know it works on the Linux glibc system with perl 5.6.1
712and 5.7.2. I know it does not work with perl 5.005_03 (it may be the bug of
713the Time::Local module). Please report if you know any system where it does
714_not_ work with perl 5.6.1 or later.
715
716I hope that someone will fix this with new time_t in libc. If you really need
717dates over 2038 and before 1902, you need to completely rewrite this module or
718use Date::Calc or other date modules.
719
720=item *
721
722This module uses Time::Local, and when it croaks, Class::Date returns
723"Invalid date or time" error message. Time::Local is different in the 5.005
724and 5.6.x (and even 5.7.x) version of perl, so the following code will
725return different results:
726
727 $a = date("2006-11-11")->clone(year => -1);
728
729In perl 5.6.1, it returns an invalid date with error message "Invali date or
730time", in perl 5.005 it returns an invalid date with range check error. Both
731are false if you use them in boolean context though, only the error message
732is different, but don't rely on the error message in this case. It however
733works in the same way if you change other fields than "year" to an invalid
734field.
735
736=back
737
738=head1 SUPPORT
739
740Class::Date is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
741
742If you have questions, you can send questions directly to me:
743
744 dlux@dlux.hu
745
746=head1 WIN32 notes
747
748You can get a binary win32 version of Class::Date from Chris Winters' .ppd
749repository with the following commands:
750
751For people using PPM2:
752
753 c:\> ppm
754 PPM> set repository oi http://openinteract.sourceforge.net/ppmpackages/
755 PPM> set save
756 PPM> install Class-Date
757
758For people using PPM3:
759
760 c:\> ppm
761 PPM> repository http://openinteract.sourceforge.net/ppmpackages/
762 PPM> install Class-Date
763
764The first steps in PPM only needs to be done at the first time. Next time
765you just run the 'install'.
766
767=head1 COPYRIGHT
768
769Copyright (c) 2001 Szab?, Bal?zs (dLux)
770
771All rights reserved. This program is free software; you can redistribute it
772and/or modify it under the same terms as Perl itself.
773
774Portions Copyright (c) Matt Sergeant
775
776=head1 AUTHOR
777
778 dLux (Szab?, Bal?zs) <dlux@dlux.hu>
779
780=head1 CREDITS
781
782 - Matt Sergeant <matt@sergeant.org>
783 (Lots of code are borrowed from the Time::Object module)
784 - Tatsuhiko Miyagawa <miyagawa@cpan.org> (bugfixes)
785 - Stas Bekman <stas@stason.org> (suggestions, bugfix)
786 - Chris Winters <chris@cwinters.com> (win32 .ppd version)
787 - Benoit Beausejour <bbeausej@pobox.com>
788 (Parts of the timezone code is borrowed from his Date::Handler module)
789
790=head1 SEE ALSO
791
792perl(1).
793Date::Calc(3pm).
794Time::Object(3pm).
795Date::Handler(3pm).
796
797=cut