view release on metacpan or  search on metacpan

lib/Date/Manip/DM5.pod  view on Meta::CPAN

Events given by "Date ; Date", "Date ; Delta", and "Recur ; Delta"
contain both the starting date and either ending date or duration.

Events given as three elements "Date ; Delta ; Delta" or "Recur ; Delta ;
Delta" take a date and add both deltas to it to give the starting and
ending time of the event.  The order and sign of the deltas is
unimportant (and both can be the same sign to give a range of times
which does not contain the base date).

=head1 KNOWN PROBLEMS

The following are not bugs in Date::Manip, but they may give some people
problems.

=over 4

=item B<Unable to determine Time Zone>

Perhaps the most common problem occurs when you get the error:

   Error: Date::Manip unable to determine Time Zone.

Date::Manip tries hard to determine the local time zone, but on some
machines, it cannot do this (especially non-Unix systems).  To fix this,
just set the TZ variable, either at the top of the Manip.pm file, in the
DateManip.cnf file, or in a call to Date_Init.  I suggest using the form
"EST5EDT" so you don't have to change it every 6 months when going to or
from daylight saving time.

Windows NT does not seem to set the time zone by default.  From the
Perl-Win32-Users mailing list:

   > How do I get the TimeZone on my NT?
   >
   >      $time_zone = $ENV{'TZ'};
   >
   You have to set the variable before, WinNT doesn't set it by
   default.  Open the properties of "My Computer" and set a SYSTEM
   variable TZ to your time zone.   Jenda@Krynicky.cz

This might help out some NT users.

A minor (false) assumption that some users might make is that since
Date::Manip passed all of its tests at install time, this should not occur
and are surprised when it does.

Some of the tests are time zone dependent.  Since the tests all include
input and expected output, I needed to know in advance what time zone they
would be run in.  So, the tests all explicitly set the time zone using the
TZ configuration variable passed into Date_Init.  Since this overrides any
other method of determining the time zone, Date::Manip uses this and doesn't
have to look elsewhere for the time zone.

When running outside the tests, Date::Manip has to rely on its other
methods for determining the time zone.

=item B<Missing date formats>

Please see the Date::Manip::Problems document for a discussion.

=item B<Complaining about getpwnam/getpwuid>

Another problem is when running on Micro$oft OS's.  I have added many
tests to catch them, but they still slip through occasionally.  If any ever
complain about getpwnam/getpwuid, simply add one of the lines:

  $ENV{OS} = Windows_NT
  $ENV{OS} = Windows_95

to your script before

  use Date::Manip

=item B<Date::Manip is slow>

The reasons for this are covered in the SHOULD I USE DATE::MANIP section
above.

Some things that will definitely help:

Version 5.21 does run noticeably faster than earlier versions due to
rethinking some of the initialization, so at the very least, make sure you
are running this version or later.

ISO-8601 dates are parsed first and fastest.  Use them whenever possible.

Avoid parsing dates that are referenced against the current time (in 2
days, today at noon, etc.).  These take a lot longer to parse.

   Example:  parsing 1065 dates with version 5.11 took 48.6 seconds, 36.2
   seconds with version 5.21, and parsing 1065 ISO-8601 dates with version
   5.21 took 29.1 seconds (these were run on a slow, overloaded computer with
   little memory... but the ratios should be reliable on a faster computer).

Business date calculations are extremely slow.  You should consider
alternatives if possible (i.e. doing the calculation in exact mode and
then multiplying by 5/7).  Who needs a business date more accurate
than "6 to 8 weeks" anyway, right :-)

Never call Date_Init more than once.  Unless you're doing something very
strange, there should never be a reason to anyway.

=item B<Sorting Problems>

If you use Date::Manip to sort a number of dates, you must call Date_Init
either explicitly, or by way of some other Date::Manip routine before it
is used in the sort.  For example, the following code fails:

   use Date::Manip;
   # Date_Init;
   sub sortDate {
       my($date1, $date2);
       $date1 = ParseDate($a);
       $date2 = ParseDate($b);
       return (Date_Cmp($date1,$date2));
   }
   @dates = ("Fri 16 Aug 96",
            "Mon 19 Aug 96",
            "Thu 15 Aug 96");
   @i=sort sortDate @dates;

but if you uncomment the Date_Init line, it works.  The reason for this is
that the first time you call Date_Init, it initializes a number of items
used by Date::Manip.  Some of these have to be sorted (regular expressions
sorted by length to ensure the longest match).  It turns out that Perl