view release on metacpan or  search on metacpan

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

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