1Class::Date(3)        User Contributed Perl Documentation       Class::Date(3)
2
3
4

NAME

6       Class::Date - Class for easy date and time manipulation
7

VERSION

9       version 1.1.17
10

SYNOPSIS

12         use Class::Date qw(:errors date localdate gmdate now -DateParse -EnvC);
13
14         # creating absolute date object (local time)
15         $date = Class::Date->new( [$year,$month,$day,$hour,$min,$sec]);
16         $date = date [$year,$month,$day,$hour,$min,$sec];
17           # ^- "date" is an exportable function, the same as Class::Date->new
18         $date = date { year => $year, month => $month, day => $day,
19           hour => $hour, min => $min, sec => $sec };
20         $date = date "2001-11-12 07:13:12";
21         $date = localdate "2001-12-11";
22         $date = now;                      #  the same as date(time)
23         $date = date($other_date_object); # cloning
24         ...
25
26         # creating absolute date object (GMT)
27         $date = Class::Date->new( [$year,$month,$day,$hour,$min,$sec],'GMT');
28         $date = gmdate "2001-11-12 17:13";
29         ...
30
31         # creating absolute date object in any other timezone
32         $date = Class::Date->new( [$year,$month,$day,$hour,$min,$sec],'Iceland' );
33         $date = date "2001-11-12 17:13", 'Iceland';
34         $date2 = $date->new([$y2, $m2, $d2, $h2, $m2, $s2]);
35           # ^- timezone is inherited from the $date object
36
37         # creating relative date object
38         # (normally you don't need to create this object explicitly)
39         $reldate = Class::Date::Rel->new( "3Y 1M 3D 6h 2m 4s" );
40         $reldate = Class::Date::Rel->new( "6Y" );
41         $reldate = Class::Date::Rel->new( $secs );  # secs
42         $reldate = Class::Date::Rel->new( [$year,$month,$day,$hour,$min,$sec] );
43         $reldate = Class::Date::Rel->new( { year => $year, month => $month, day => $day,
44           hour => $hour, min => $min, sec => $sec } );
45         $reldate = Class::Date::Rel->new( "2001-11-12 07:13:12" );
46         $reldate = Class::Date::Rel->new( "2001-12-11" );
47
48         # getting values of an absolute date object
49         $date;              # prints the date in default output format (see below)
50         $date->year;        # year, e.g: 2001
51         $date->_year;       # year - 1900, e.g. 101
52         $date->yr;          # 2-digit year 0-99, e.g 1
53         $date->mon;         # month 1..12
54         $date->month;       # same as prev.
55         $date->_mon;        # month 0..11
56         $date->_month;      # same as prev.
57         $date->day;         # day of month
58         $date->mday;        # day of month
59         $date->day_of_month;# same as prev.
60         $date->hour;
61         $date->min;
62         $date->minute;      # same as prev.
63         $date->sec;
64         $date->second;      # same as prev.
65         $date->wday;        # 1 = Sunday
66         $date->_wday;       # 0 = Sunday
67         $date->day_of_week; # same as prev.
68         $date->yday;
69         $date->day_of_year; # same as prev.
70         $date->isdst;       # DST?
71         $date->daylight_savings; # same as prev.
72         $date->epoch;       # UNIX time_t
73         $date->monname;     # name of month, eg: March
74         $date->monthname;   # same as prev.
75         $date->wdayname;    # Thursday
76         $date->day_of_weekname # same as prev.
77         $date->hms          # 01:23:45
78         $date->ymd          # 2000/02/29
79         $date->mdy          # 02/29/2000
80         $date->dmy          # 29/02/2000
81         $date->meridiam     # 01:23 AM
82         $date->ampm         # AM/PM
83         $date->string       # 2000-02-29 12:21:11 (format can be changed, look below)
84         "$date"             # same as prev.
85         $date->tzoffset     # timezone-offset
86         $date->strftime($format) # POSIX strftime (without the huge POSIX.pm)
87         $date->tz           # returns the base timezone as you specify, eg: CET
88         $date->tzdst        # returns the real timezone with dst information, eg: CEST
89
90         ($year,$month,$day,$hour,$min,$sec)=$date->array;
91         ($year,$month,$day,$hour,$min,$sec)=@{ $date->aref };
92         # !! $year: 1900-, $month: 1-12
93
94         ($sec,$min,$hour,$day,$mon,$year,$wday,$yday,$isdst)=$date->struct;
95         ($sec,$min,$hour,$day,$mon,$year,$wday,$yday,$isdst)=@{ $date->sref };
96         # !! $year: 0-, $month: 0-11
97
98         $hash=$date->href; # $href can be reused as a constructor
99         print $hash->{year}."-".$hash->{month}. ... $hash->{sec} ... ;
100
101         %hash=$date->hash;
102         # !! $hash{year}: 1900-, $hash{month}: 1-12
103
104         $date->month_begin  # First day of the month (date object)
105         $date->month_end    # Last day of the month
106         $date->days_in_month # 28..31
107
108         # constructing new date based on an existing one:
109         $new_date = $date->clone;
110         $new_date = $date->clone( year => 1977, sec => 14 );
111         # valid keys: year, _year, month, mon, _month, _mon, day, mday, day_of_month,
112         #             hour, min, minute, sec, second, tz
113         # constructing a new date, which is the same as the original, but in
114         # another timezone:
115         $new_date = $date->to_tz('Iceland');
116
117         # changing date format
118         {
119           local $Class::Date::DATE_FORMAT="%Y%m%d%H%M%S";
120           print $date       # result: 20011222000000
121           $Class::Date::DATE_FORMAT=undef;
122           print $date       # result: Thu Oct 13 04:54:34 1994
123           $Class::Date::DATE_FORMAT="%Y/%m/%d"
124           print $date       # result: 1994/10/13
125         }
126
127         # error handling
128         $a = date($date_string);
129         if ($a) { # valid date
130           ...
131         } else { # invalid date
132           if ($a->error == E_INVALID) { ... }
133           print $a->errstr;
134         }
135
136         # adjusting DST in calculations  (see the doc)
137         $Class::Date::DST_ADJUST = 1; # this is the default
138         $Class::Date::DST_ADJUST = 0;
139
140         # "month-border adjust" flag
141         $Class::Date::MONTH_BORDER_ADJUST = 0; # this is the default
142         print date("2001-01-31")+'1M'; # will print 2001-03-03
143         $Class::Date::MONTH_BORDER_ADJUST = 1;
144         print date("2001-01-31")+'1M'; # will print 2001-02-28
145
146         # date range check
147         $Class::Date::RANGE_CHECK = 0; # this is the default
148         print date("2001-02-31"); # will print 2001-03-03
149         $Class::Date::RANGE_CHECK = 1;
150         print date("2001-02-31"); # will print nothing
151
152         # getting values of a relative date object
153         $reldate;              # reldate in seconds (assumed 1 month = 2_629_744 secs)
154         $reldate->year;
155         $reldate->mon;
156         $reldate->month;       # same as prev.
157         $reldate->day;
158         $reldate->hour;
159         $reldate->min;
160         $reldate->minute;      # same as prev.
161         $reldate->sec;         # same as $reldate
162         $reldate->second;      # same as prev.
163         $reldate->sec_part;    # "second" part of the relative date
164         $reldate->mon_part;    # "month"  part of the relative date
165
166         # arithmetic with dates:
167         print date([2001,12,11,4,5,6])->truncate;
168                                      # will print "2001-12-11"
169         $new_date = $date+$reldate;
170         $date2    = $date+'3Y 2D';   # 3 Years and 2 days
171         $date3    = $date+[1,2,3];   # $date plus 1 year, 2 months, 3 days
172         $date4    = $date+'3-1-5'    # $date plus 3 years, 1 months, 5 days
173
174         $new_date = $date-$reldate;
175         $date2    = $date-'3Y';      # 3 Yearss
176         $date3    = $date-[1,2,3];   # $date minus 1 year, 2 months, 3 days
177         $date4    = $date-'3-1-5'    # $date minus 3 years, 1 month, 5 days
178
179         $new_reldate = $date1-$date2;
180         $reldate2 = Class::Date->new('2000-11-12')-'2000-11-10';
181         $reldate3    = $date3-'1977-11-10';
182
183         $days_between = (Class::Date->new('2001-11-12')-'2001-07-04')->day;
184
185         # comparison between absolute dates
186         print $date1 > $date2 ? "I am older" : "I am younger";
187
188         # comparison between relative dates
189         print $reldate1 > $reldate2 ? "I am faster" : "I am slower";
190
191         # Adding / Subtracting months and years are sometimes tricky:
192         print date("2001-01-29") + '1M' - '1M'; # gives "2001-02-01"
193         print date("2000-02-29") + '1Y' - '1Y'; # gives "2000-03-01"
194
195         # Named interface ($date2 does not necessary to be a Class::Date object)
196         $date1->string;               # same as $date1 in scalar context
197         $date1->subtract($date2);     # same as $date1 - $date2
198         $date1->add($date2);          # same as $date1 + $date2
199         $date1->compare($date2);      # same as $date1 <=> $date2
200
201         $reldate1->sec;               # same as $reldate1 in numeric or scalar context
202         $reldate1->compare($reldate2);# same as $reldate1 <=> $reldate2
203         $reldate1->add($reldate2);    # same as $reldate1 + $reldate2
204         $reldate1->neg                # used for subtraction
205
206         # Disabling Class::Date warnings at load time
207         BEGIN { $Class::Date::WARNINGS=0; }
208         use Class::Date;
209

DESCRIPTION

211       This module is intended to provide a general-purpose date and datetime
212       type for perl. You have a Class::Date class for absolute date and
213       datetime, and have a Class::Date::Rel class for relative dates.
214
215       You can use "+", "-", "<" and ">" operators as with native perl data
216       types.
217
218       Note that this module is fairly ancient and dusty. You might want to
219       take a look at DateTime and its related modules for a more standard,
220       and maintained, Perl date manipulation solution.
221

USAGE

223       If you want to use a date object, you need to do the following:
224
225         - create a new object
226         - do some operations (+, -, comparison)
227         - get result back
228
229   Creating a new date object
230       You can create a date object by the "date", "localdate" or "gmdate"
231       function, or by calling the Class::Date constructor.
232
233       "date" and "Class::Date->new" are equivalent, both has two arguments:
234       The date and the timezone.
235
236         $date1= date [2000,11,12];
237         $date2= Class::Date->new([2000,06,11,13,11,22],'GMT');
238         $date2= $date1->new([2000,06,11,13,11,22]);
239
240       If the timezone information is omitted, then it first check if "new" is
241       called as an object method or a class method. If it is an object
242       method, then it inherits the timezone from the base object, otherwise
243       the default timezone is used ($Class::Date::DEFAULT_TIMEZONE), which is
244       usually set to the local timezone (which is stored in
245       $Class::Date::LOCAL_TIMEZONE). These two variables are set only once to
246       the value, which is returned by the Class::Date::local_timezone()
247       function. You can change these values whenever you want.
248
249       "localdate $x" is equivalent to "date $x,
250       $Class::Date::LOCAL_TIMEZONE", "gmdate $x" is equivalent to "date $x,
251       $Class::Date::GMT_TIMEZONE".
252
253       $Class::Date::GMT_TIMEZONE is set to 'GMT' by default.
254
255         $date1= localdate [2000,11,12];
256         $date2= gmdate [2000,4,2,3,33,33];
257
258         $date = localdate(time);
259
260       The format of the accepted input date can be:
261
262       [$year,$month,$day,$hour,$min,$sec]
263           An array reference with 6 elements. The missing elements have
264           default values (year: 2000, month, day: 1, hour, min, sec: 0)
265
266       { year => $year, month => $month, day => $day, hour => $hour, min =>
267       $min, sec => $sec }
268           A hash reference with the same 6 elements as above.
269
270       "YYYYMMDDhhmmss"
271           A mysql-style timestamp value, which consist of at least 14 digit.
272
273       "973897262"
274           A valid 32-bit integer: This is parsed as a unix time.
275
276       "YYYY-MM-DD hh:mm:ss"
277           A standard ISO(-like) date format. Additional ".fraction" part is
278           ignored, ":ss" can be omitted.
279
280       additional input formats
281           You can specify "-DateParse" as  an import parameter, e.g:
282
283             use Class::Date qw(date -DateParse);
284
285           With this, the module will try to load Date::Parse module, and if
286           it find it then all these formats can be used as an input. Please
287           refer to the Date::Parse documentation.
288
289   Operations
290       addition
291           You can add the following to a Class::Date object:
292
293             - a valid Class::Date::Rel object
294             - anything, that can be used for creating a new Class::Date::Rel object
295
296           It means that you don't need to create a new Class::Date::Rel
297           object every time when you add something to the Class::Date object,
298           it creates them automatically:
299
300             $date= Class::Date->new('2001-12-11')+Class::Date::Rel->new('3Y');
301
302           is the same as:
303
304             $date= date('2001-12-11')+'3Y';
305
306           You can provide a Class::Date::Rel object in the following form:
307
308           array ref
309               The same format as seen in Class::Date format, except the
310               default values are different: all zero.
311
312           hash ref
313               The same format as seen in Class::Date format, except the
314               default values are different: all zero.
315
316           "973897262"
317               A valid 32-bit integer is parsed as seconds.
318
319           "YYYY-MM-DD hh:mm:ss"
320               A standard ISO date format, but this is parsed as relative date
321               date and time, so month, day and year can be zero (and defaults
322               to zero).
323
324           "12Y 6M 6D 20h 12m 5s"
325               This special string can be used if you don't want to use the
326               ISO format. This string consists of whitespace separated tags,
327               each tag consists of a number and a unit. The units can be:
328
329                 Y: year
330                 M: month
331                 D: day
332                 h: hour
333                 m: min
334                 s: sec
335
336               The number and unit must be written with no space between them.
337
338       substraction
339           The same rules are true for substraction, except you can substract
340           two Class::Date object from each other, and you will get a
341           Class::Date::Rel object:
342
343             $reldate=$date1-$date2;
344             $reldate=date('2001-11-12 12:11:07')-date('2001-10-07 10:3:21');
345
346           In this case, the "month" field of the $reldate object will be 0,
347           and the other fields will contain the difference between two dates;
348
349       comparison
350           You can compare two Class::Date objects, or one Class::Date object
351           and another data, which can be used for creating a new Class::Data
352           object.
353
354           It means that you don't need to bless both objects, one of them can
355           be a simple string, array ref, hash ref, etc (see how to create a
356           date object).
357
358             if ( date('2001-11-12') > date('2000-11-11') ) { ... }
359
360           or
361
362             if ( date('2001-11-12') > '2000-11-11' ) { ... }
363
364       truncate
365           You can chop the time value from this object (set hour, min and sec
366           to 0) with the "truncate" or "trunc" method. It does not modify the
367           specified object, it returns with a new one.
368
369       clone
370           You can create new date object based on an existing one, by using
371           the "clone" method. Note, this DOES NOT modify the base object.
372
373             $new_date = $date->clone( year => 2001, hour => 14 );
374
375           The valid keys are: year, _year, month, mon, _month, _mon, day,
376           mday, day_of_month, hour, min, minute, sec, second, tz.
377
378           There is a "set" method, which does the same as the "clone", it
379           exists only for compatibility.
380
381       to_tz
382           You can use "to_tz" to create a new object, which means the same
383           time as the base object, but in the different timezone.
384
385           Note that $date->clone( tz => 'Iceland') and
386           $date->to_tz('Iceland') is not the same! Cloning a new object with
387           setting timezone will preserve the time information (hour, minute,
388           second, etc.), but transfer the time into other timezone, while
389           to_tz usually change these values based on the difference between
390           the source and the destination timezone.
391
392       Operations with Class::Date::Rel
393           The Class::Date::Rel object consists of a month part and a day
394           part. Most people only use the "day" part of it. If you use both
395           part, then you can get these parts with the "sec_part" and
396           "mon_part" method. If you use "sec", "month", etc. methods or if
397           you use this object in a mathematical context, then this object is
398           converted to one number, which is interpreted as second.  The
399           conversion is based on a 30.436 days month. Don't use it too often,
400           because it is confusing...
401
402           If you use Class::Date::Rel in an expression with other Class::Date
403           or Class::Date::Rel objects, then it does what is expected:
404
405             date('2001-11-12')+'1M' will be '2001-12-12'
406
407           and
408
409             date('1996-02-11')+'2M' will be '1996-04-11'
410
411   Accessing data from a Class::Date and Class::Date::Rel object
412       You can use the methods methods described at the top of the document if
413       you want to access parts of the data which is stored in a Class::Date
414       and Class::Date::Rel object.
415
416   Error handling
417       If a date object became invalid, then the object will be reblessed to
418       Class::Date::Invalid. This object is false in boolean environment, so
419       you can test the date validity like this:
420
421         $a = date($input_date);
422         if ($a) { # valid date
423             ...
424         } else { # invalid date
425             if ($a->error == E_INVALID) { ... }
426             print $a->errstr;
427         }
428
429       Note even the date is invalid, the expression "defined $a" always
430       returns true, so the following is wrong:
431
432         $a = date($input_date);
433         if (defined $a) ... # WRONG!!!!
434
435       You can test the error by getting the $date->error value. You might
436       import the ":errors" tag:
437
438         use Class::Date qw(:errors);
439
440       Possible error values are:
441
442       E_OK
443           No errors.
444
445       E_INVALID
446           Invalid date. It is set when some of the parts of the date are
447           invalid, and Time::Local functions cannot convert them to a valid
448           date.
449
450       E_RANGE
451           This error is set, when parts of the date are valid, but the whole
452           date is not valid, e.g. 2001-02-31. When the
453           $Class::Date::RANGE_CHECK is not set, then these date values are
454           automatically converted to a valid date: 2001-03-03, but the
455           $date->error value are set to E_RANGE. If $Class::Date::RANGE_CHECK
456           is set, then a date "2001-02-31" became invalid date.
457
458       E_UNPARSABLE
459           This error is set, when the constructor cannot be created from a
460           scalar, e.g:
461
462             $a = date("4kd sdlsdf lwekrmk");
463
464       E_UNDEFINED
465           This error is set, when you want to create a date object from an
466           undefined value:
467
468             $a = Class::Date->new(undef);
469
470           Note, that localdate(undef) will create a valid object, because it
471           calls $Class::Date(time).
472
473       You can get the error in string form by calling the "errstr" method.
474

DST_ADJUST

476       $DST_ADJUST is an important configuration option.
477
478       If it is set to true (default), then the module adjusts the date and
479       time when the operation switches the border of DST. With this setting,
480       you are ignoring the effect of DST.
481
482       When $DST_ADJUST is set to false, then no adjustment is done, the
483       calculation will be based on the exact time difference.
484
485       You will see the difference through an example:
486
487         $Class::Date::DST_ADJUST=1;
488
489         print date("2000-10-29", "CET") + "1D";
490         # This will print 2000-10-30 00:00:00
491
492         print date("2001-03-24 23:00:00", "CET") + "1D";
493         # This will be 2001-03-25 23:00:00
494
495         print date("2001-03-25", "CET") + "1D";
496         # This will be 2001-03-26 00:00:00
497
498
499         $Class::Date::DST_ADJUST=0;
500
501         print date("2000-10-29", "CET") + "1D";
502         # This will print 2000-10-29 23:00:00
503
504         print date("2001-03-24 23:00:00", "CET") + "1D";
505         # This will be 2001-03-26 00:00:00
506

MONTHS AND YEARS

508       If you add or subtract "months" and "years" to a date, you may get
509       wrong dates, e.g when you add one month to 2001-01-31, you expect to
510       get 2001-02-31, but this date is invalid and converted to 2001-03-03.
511       Thats' why
512
513         date("2001-01-31") + '1M' - '1M' != "2001-01-31"
514
515       This problem can occur only with months and years, because others can
516       easily be converted to seconds.
517

MONTH_BORDER_ADJUST

519       $MONTH_BORDER_ADJUST variable is used to switch on or off the month-
520       adjust feature. This is used only when someone adds months or years to
521       a date and then the resulted date became invalid. An example: adding
522       one month to "2001-01-31" will result "2001-02-31", and this is an
523       invalid date.
524
525       When $MONTH_BORDER_ADJUST is false, this result simply normalized, and
526       becomes "2001-03-03". This is the default behaviour.
527
528       When $MONTH_BORDER_ADJUST is true, this result becomes "2001-02-28". So
529       when the date overflows, then it returns the last day insted.
530
531       Both settings keep the time information.
532

TIMEZONE SUPPORT

534       Since 1.0.11, Class::Date handle timezones natively on most platforms
535       (see the BUGS AND LIMITATIONS section for more info).
536
537       When the module is loaded, then it determines the local base timezone
538       by calling the Class::Date::local_timezone() function, and stores these
539       values into two variables, these are: $Class::Date::LOCAL_TIMEZONE and
540       $Class::Date::DEFAULT_TIMEZONE. The first value is used, when you call
541       the "localdate" function, the second value is used, when you call the
542       "date" function and you don't specify the timezone. There is a
543       $Class::Date::GMT_TIMEZONE function also, which is used by the "gmdate"
544       function, this is set to 'GMT'.
545
546       You can query the timezone of a date object by calling the $date->tz
547       method. Note this value returns the timezone as you specify, so if you
548       create the object with an unknown timezone, you will get this back. If
549       you want to query the effective timezone, you can call the $date->tzdst
550       method.  This method returns only valid timezones, but it is not
551       necessarily the timezone which can be used to create a new object. For
552       example $date->tzdst can return 'CEST', which is not a valid base
553       timezone, because it contains daylight savings information also. On
554       Linux systems, you can see the possible base timezones in the
555       /usr/share/zoneinfo directory.
556
557       In Class::Date 1.1.6, a new environment variable is introduced:
558       $Class::Date::NOTZ_TIMEZONE. This variable stores the local timezone,
559       which is used, when the TZ environment variable is not set. It is
560       introduced, because there are some systems, which cannot handle the
561       queried timezone well. For example the local timezone is CST, it is
562       returned by the tzname() perl function, but when I set the TZ
563       environment variable to CST, it works like it would be GMT.  The
564       workaround is NOTZ_TIMEZONE: if a date object has a timezone, which is
565       the same as NOTZ_TIMEZONE, then the TZ variable will be removed before
566       each calculation. In normal case, it would be the same as setting TZ to
567       $NOTZ_TIMEZONE, but some systems don't like it, so I decided to
568       introduce this variable. The $Class::Date::NOTZ_TIMEZONE variable is
569       set in the initialization of the module by removing the TZ variable
570       from the environment and querying the tzname variable.
571

INTERNALS

573       This module uses operator overloading very heavily. I've found it quite
574       stable, but I am afraid of it a bit.
575
576       A Class::Date object is an array reference.
577
578       A Class::Date::Rel object is an array reference, which contains month
579       and second information. I need to store it as an array ref, because
580       array and month values cannot be converted into seconds, because of our
581       super calendar.
582
583       You can add code references to the @Class::Date::NEW_FROM_SCALAR and
584       @Class::Date::Rel::NEW_FROM_SCALAR. These arrays are iterated through
585       when a scalar-format date must be parsed. These arrays only have one or
586       two values at initialization. The parameters which the code references
587       got are the same as the "new" method of each class. In this way, you
588       can personalize the date parses as you want.
589
590       As of 0.90, the Class::Date has been rewritten. A lot of code and
591       design decision has been borrowed from Matt Sergeant's Time::Object,
592       and there will be some incompatibility with the previous public version
593       (0.5). I tried to keep compatibility methods in Class::Date. If you
594       have problems regarding this, please drop me an email with the
595       description of the problem, and I will set the compatibility back.
596
597       Invalid dates are Class::Date::Invalid objects. Every method call on
598       this object and every operation with this object returns undef or 0.
599

DEVELOPMENT FOCUS

601       This module tries to be as full-featured as can be. It currently lacks
602       business-day calculation, which is planned to be implemented in the
603       1.0.x series.
604
605       I try to keep this module not to depend on other modules and I want
606       this module usable without a C compiler.
607
608       Currently the module uses the POSIX localtime function very
609       extensively.  This makes the date calculation a bit slow, but provides
610       a rich interface, which is not provided by any other module. When I
611       tried to redesign the internals to not depend on localtime, I failed,
612       because there are no other way to determine the daylight savings
613       information.
614

SPEED ISSUES

616       There are two kind of adjustment in this module, DST_ADJUST and
617       MONTH_BORDER_ADJUST. Both of them makes the "+" and "-" operations
618       slower. If you don't need them, switch them off to achieve faster
619       calculations.
620
621       In general, if you really need fast date and datetime calculation,
622       don't use this module. As you see in the previous section, the focus of
623       development is not the speed in 1.0.  For fast date and datetime
624       calculations, use Date::Calc module instead.
625

THREAD SAFETY and MOD_PERL

627       This module is NOT thread-safe, since it uses C library functions,
628       which are not thread-safe. Using this module in a multi-threaded
629       environment can cause timezones to be messed up. I did not put any
630       warning about it, you have to make sure that you understand this!
631
632       Under some circumstances in a mod_perl environment, you require the
633       Env::C module to set the TZ variable properly before calling the time
634       functions. I added the -EnvC import option to automatically load this
635       module if it is not loaded already. Please read the mod_perl
636       documentation about the environment variables and mod_perl to get the
637       idea why it is required sometimes:
638
639         http://perl.apache.org/docs/2.0/user/troubleshooting/troubleshooting.html#C_Libraries_Don_t_See_C__ENV__Entries_Set_by_Perl_Code
640
641       You are sure have this problem if the $Class::Date::NOTZ_TIMEZONE
642       variable is set to 'UTC', althought you are sure that your timezone is
643       not that. Try -EnvC in this case, but make sure that you are not using
644       it in a multi-threaded environment!
645

OTHER BUGS AND LIMITATIONS

647       •   Not all date/time values can be expressed in all timezones. For
648           example:
649
650             print date("2010-10-03 02:00:00", "Australia/Sydney")
651             # it will print 2010-10-03 03:00:00
652
653           No matter how hard you try you, you are not going to be able to
654           express the time in the example in that timezone. If you don't need
655           the timezone information and you want to make sure that the
656           calculations are always correct, please use GMT as a timezone (the
657           'gmdate' function can be a shortcut for it). In this case, you
658           might also consider turning off DST_ADJUST to speed up the
659           calculation.
660
661       •   I cannot manage to get the timezone code working properly on
662           ActivePerl 5.8.0 on win XP and earlier versions possibly have this
663           problem also. If you have a system like this, then you will have
664           only two timezones, the local and the GMT. Every timezone, which is
665           not equal to $Class::Date::GMT_TIMEZONE is assumed to be local.
666           This seems to be caused by the win32 implementation of timezone
667           routines. I don't really know how to make this thing working, so I
668           gave up this issue. If anyone know a working solution, then I will
669           integrate it into Class::Date, but until then, the timezone support
670           will not be available for these platforms.
671
672       •   Perl 5.8.0 and earlier versions has a bug in the strftime code on
673           some operating systems (for example Linux), which is timezone
674           related. I recommend using the strftime, which is provided with
675           Class::Date, so don't try to use the module without the compiled
676           part. The module will not work with a buggy strftime - the test is
677           hardcoded into the beginning of the code. If you anyway want to use
678           the module, remove the hardcoded "die" from the module, but do it
679           for your own risk.
680
681       •   This module uses the POSIX functions for date and time
682           calculations, so it is not working for dates beyond 2038 and before
683           1902.
684
685           I don't know what systems support dates in 1902-1970 range, it may
686           not work on your system. I know it works on the Linux glibc system
687           with perl 5.6.1 and 5.7.2. I know it does not work with perl
688           5.005_03 (it may be the bug of the Time::Local module). Please
689           report if you know any system where it does _not_ work with perl
690           5.6.1 or later.
691
692           I hope that someone will fix this with new time_t in libc. If you
693           really need dates over 2038 and before 1902, you need to completely
694           rewrite this module or use Date::Calc or other date modules.
695
696       •   This module uses Time::Local, and when it croaks, Class::Date
697           returns "Invalid date or time" error message. Time::Local is
698           different in the 5.005 and 5.6.x (and even 5.7.x) version of perl,
699           so the following code will return different results:
700
701             $a = date("2006-11-11")->clone(year => -1);
702
703           In perl 5.6.1, it returns an invalid date with error message
704           "Invali date or time", in perl 5.005 it returns an invalid date
705           with range check error. Both are false if you use them in boolean
706           context though, only the error message is different, but don't rely
707           on the error message in this case. It however works in the same way
708           if you change other fields than "year" to an invalid field.
709

SUPPORT

711       Class::Date is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
712
713       If you have questions, you can send questions directly to me:
714
715         dlux@dlux.hu
716

WIN32 notes

718       You can get a binary win32 version of Class::Date from Chris Winters'
719       .ppd repository with the following commands:
720
721       For people using PPM2:
722
723         c:\> ppm
724         PPM> set repository oi http://openinteract.sourceforge.net/ppmpackages/
725         PPM> set save
726         PPM> install Class-Date
727
728       For people using PPM3:
729
730         c:\> ppm
731         PPM> repository http://openinteract.sourceforge.net/ppmpackages/
732         PPM> install Class-Date
733
734       The first steps in PPM only needs to be done at the first time. Next
735       time you just run the 'install'.
736
738       Copyright (c) 2001 Szabó, Balázs (dLux)
739
740       All rights reserved. This program is free software; you can
741       redistribute it and/or modify it under the same terms as Perl itself.
742
743       Portions Copyright (c) Matt Sergeant
744

CREDITS

746         - Matt Sergeant <matt@sergeant.org>
747           (Lots of code are borrowed from the Time::Object module)
748         - Tatsuhiko Miyagawa <miyagawa@cpan.org> (bugfixes)
749         - Stas Bekman <stas@stason.org> (suggestions, bugfix)
750         - Chris Winters <chris@cwinters.com> (win32 .ppd version)
751         - Benoit Beausejour <bbeausej@pobox.com>
752           (Parts of the timezone code is borrowed from his Date::Handler module)
753

SEE ALSO

755       perl(1).  Date::Calc(3pm).  Time::Object(3pm).  Date::Handler(3pm).
756

AUTHORS

758       •   dLux (Szabó, Balázs) <dlux@dlux.hu>
759
760       •   Gabor Szabo <szabgab@gmail.com>
761
762       •   Yanick Champoux <yanick@cpan.org>
763
765       This software is copyright (c) 2018, 2014, 2010, 2003 by Balázs Szabó.
766
767       This is free software; you can redistribute it and/or modify it under
768       the same terms as the Perl 5 programming language system itself.
769
770
771
772perl v5.34.0                      2022-01-21                    Class::Date(3)
Impressum