view release on metacpan or  search on metacpan

lib/Class/Date.pm  view on Meta::CPAN

$DST_ADJUST is an important configuration option.

If it is set to true (default), then the module adjusts the date and time
when the operation switches the border of DST. With this setting, you are
ignoring the effect of DST.

When $DST_ADJUST is set to false, then no adjustment is done, the
calculation will be based on the exact time difference.

You will see the difference through an example:

  $Class::Date::DST_ADJUST=1;

  print date("2000-10-29", "CET") + "1D";
  # This will print 2000-10-30 00:00:00

  print date("2001-03-24 23:00:00", "CET") + "1D";
  # This will be 2001-03-25 23:00:00

  print date("2001-03-25", "CET") + "1D";
  # This will be 2001-03-26 00:00:00


  $Class::Date::DST_ADJUST=0;

  print date("2000-10-29", "CET") + "1D";
  # This will print 2000-10-29 23:00:00

  print date("2001-03-24 23:00:00", "CET") + "1D";
  # This will be 2001-03-26 00:00:00

=head1 MONTHS AND YEARS

If you add or subtract "months" and "years" to a date, you may get wrong 
dates, e.g when you add one month to 2001-01-31, you expect to get
2001-02-31, but this date is invalid and converted to 2001-03-03. Thats' why

  date("2001-01-31") + '1M' - '1M' != "2001-01-31"

This problem can occur only with months and years, because others can 
easily be converted to seconds.

=head1 MONTH_BORDER_ADJUST

$MONTH_BORDER_ADJUST variable is used to switch on or off the 
month-adjust feature. This is used only when someone adds months or years to
a date and then the resulted date became invalid. An example: adding one
month to "2001-01-31" will result "2001-02-31", and this is an invalid date.

When $MONTH_BORDER_ADJUST is false, this result simply normalized, and
becomes "2001-03-03". This is the default behaviour.

When $MONTH_BORDER_ADJUST is true, this result becomes "2001-02-28". So when
the date overflows, then it returns the last day insted.

Both settings keep the time information.

=head1 TIMEZONE SUPPORT

Since 1.0.11, Class::Date handle timezones natively on most platforms (see
the BUGS AND LIMITATIONS section for more info).

When the module is loaded, then it determines the local base timezone by
calling the Class::Date::local_timezone() function, and stores these values
into two variables, these are: $Class::Date::LOCAL_TIMEZONE and
$Class::Date::DEFAULT_TIMEZONE. The first value is used, when you call the
"localdate" function, the second value is used, when you call the "date"
function and you don't specify the timezone. There is
a $Class::Date::GMT_TIMEZONE function also, which is used by the "gmdate"
function, this is set to 'GMT'.

You can query the timezone of a date object by calling the $date->tz
method. Note this value returns the timezone as you specify, so if you
create the object with an unknown timezone, you will get this back. If you
want to query the effective timezone, you can call the $date->tzdst method.
This method returns only valid timezones, but it is not necessarily the
timezone which can be used to create a new object. For example
$date->tzdst can return 'CEST', which is not a valid base timezone, because
it contains daylight savings information also. On Linux systems, you can
see the possible base timezones in the /usr/share/zoneinfo directory.

In Class::Date 1.1.6, a new environment variable is introduced:
$Class::Date::NOTZ_TIMEZONE. This variable stores the local timezone, which
is used, when the TZ environment variable is not set. It is introduced,
because there are some systems, which cannot handle the queried timezone
well. For example the local timezone is CST, it is returned by the tzname()
perl function, but when I set the TZ environment variable to CST, it
works like it would be GMT.  The workaround is NOTZ_TIMEZONE: if a date
object has a timezone, which is the same as NOTZ_TIMEZONE, then the TZ
variable will be removed before each calculation. In normal case, it would
be the same as setting TZ to $NOTZ_TIMEZONE, but some systems don't like
it, so I decided to introduce this variable. The
$Class::Date::NOTZ_TIMEZONE variable is set in the initialization of the
module by removing the TZ variable from the environment and querying the
tzname variable.

=head1 INTERNALS

This module uses operator overloading very heavily. I've found it quite stable,
but I am afraid of it a bit.

A Class::Date object is an array reference.

A Class::Date::Rel object is an array reference, which contains month and
second information. I need to store it as an array ref, because array and month
values cannot be converted into seconds, because of our super calendar.

You can add code references to the @Class::Date::NEW_FROM_SCALAR and
@Class::Date::Rel::NEW_FROM_SCALAR. These arrays are iterated through when a
scalar-format date must be parsed. These arrays only have one or two values
at initialization. The parameters which the code references got are the same 
as the "new" method of each class. In this way, you can personalize the date
parses as you want.

As of 0.90, the Class::Date has been rewritten. A lot of code and design
decision has been borrowed from Matt Sergeant's Time::Object, and there will
be some incompatibility with the previous public version (0.5). I tried to
keep compatibility methods in Class::Date. If you have problems regarding
this, please drop me an email with the description of the problem, and I will
set the compatibility back.

Invalid dates are Class::Date::Invalid objects. Every method call on this
object and every operation with this object returns undef or 0.

=head1 DEVELOPMENT FOCUS

This module tries to be as full-featured as can be. It currently lacks
business-day calculation, which is planned to be implemented in the 1.0.x
series.

I try to keep this module not to depend on other modules and I want this
module usable without a C compiler.

Currently the module uses the POSIX localtime function very extensively.
This makes the date calculation a bit slow, but provides a rich interface,
which is not provided by any other module. When I tried to redesign the
internals to not depend on localtime, I failed, because there are no other
way to determine the daylight savings information.

=head1 SPEED ISSUES

There are two kind of adjustment in this module, DST_ADJUST and
MONTH_BORDER_ADJUST. Both of them makes the "+" and "-" operations slower. If
you don't need them, switch them off to achieve faster calculations.

In general, if you really need fast date and datetime calculation, don't use 
this module. As you see in the previous section, the focus of development is 
not the speed in 1.0.  For fast date and datetime calculations, use 
Date::Calc module instead.

=head1 THREAD SAFETY and MOD_PERL

This module is NOT thread-safe, since it uses C library functions, which
are not thread-safe. Using this module in a multi-threaded environment can
cause timezones to be messed up. I did not put any warning about it, you
have to make sure that you understand this!

Under some circumstances in a mod_perl environment, you require the Env::C
module to set the TZ variable properly before calling the time functions. I
added the -EnvC import option to automatically load this module if it is
not loaded already. Please read the mod_perl documentation about the
environment variables and mod_perl to get the idea why it is required
sometimes:

  http://perl.apache.org/docs/2.0/user/troubleshooting/troubleshooting.html#C_Libraries_Don_t_See_C__ENV__Entries_Set_by_Perl_Code

You are sure have this problem if the $Class::Date::NOTZ_TIMEZONE variable
is set to 'UTC', althought you are sure that your timezone is not that. Try
-EnvC in this case, but make sure that you are not using it in a
multi-threaded environment!

=head1 OTHER BUGS AND LIMITATIONS

=over 4

=item *

Not all date/time values can be expressed in all timezones. For example:

  print date("2010-10-03 02:00:00", "Australia/Sydney")
  # it will print 2010-10-03 03:00:00

No matter how hard you try you, you are not going to be able to express the
time in the example in that timezone. If you don't need the timezone
information and you want to make sure that the calculations are always
correct, please use GMT as a timezone (the 'gmdate' function can be a
shortcut for it). In this case, you might also consider turning off
DST_ADJUST to speed up the calculation.

=item *

I cannot manage to get the timezone code working properly on ActivePerl
5.8.0 on win XP and earlier versions possibly have this problem also. If
you have a system like this, then you will have only two timezones, the
local and the GMT. Every timezone, which is not equal to
$Class::Date::GMT_TIMEZONE is assumed to be local. This seems to be caused
by the win32 implementation of timezone routines. I don't really know how
to make this thing working, so I gave up this issue. If anyone know a
working solution, then I will integrate it into Class::Date, but until
then, the timezone support will not be available for these platforms.

=item *

Perl 5.8.0 and earlier versions has a bug in the strftime code on some
operating systems (for example Linux), which is timezone related. I
recommend using the strftime, which is provided with Class::Date, so don't
try to use the module without the compiled part. The module will not work
with a buggy strftime - the test is hardcoded into the beginning of the
code. If you anyway want to use the module, remove the hardcoded "die" from
the module, but do it for your own risk.

=item *

This module uses the POSIX functions for date and
time calculations, so it is not working for dates beyond 2038 and before 1902.

I don't know what systems support dates in 1902-1970 range, it may not work on
your system. I know it works on the Linux glibc system with perl 5.6.1
and 5.7.2. I know it does not work with perl 5.005_03 (it may be the bug of
the Time::Local module). Please report if you know any system where it does
_not_ work with perl 5.6.1 or later.

I hope that someone will fix this with new time_t in libc. If you really need
dates over 2038 and before 1902, you need to completely rewrite this module or
use Date::Calc or other date modules.

=item *

This module uses Time::Local, and when it croaks, Class::Date returns
"Invalid date or time" error message. Time::Local is different in the 5.005
and 5.6.x (and even 5.7.x) version of perl, so the following code will
return different results: