libdate-manip-perl 6.25-1 / usr / share / perl5 / Date / Manip / Problems.pod

# Copyright (c) 1995-2011 Sullivan Beck. All rights reserved.
# This program is free software; you can redistribute it and/or modify it
# under the same terms as Perl itself.

=pod

=head1 NAME

Date::Manip::Problems - problems and bugs

=head1 KNOWN PROBLEMS

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

=over 4

=item B<Memory leak>

There is a known memory leak in perl related to named regexp captures
that directly affects Date::Manip . The leak is in all versions of
perl that I have tested starting at 5.10.  It has been tested on:

   5.10.1
   5.12.4
   5.14.1
   5.15.0

I have submitted a bug report (perlbug #78266). Until perl is fixed,
if you need to use Date::Manip in a persistent environment, you should
be aware of this.

Date::Manip 5.xx is not susceptible, so using it may be a feasible
workaround, but if you need accurate timezone handling, this isn't
possible.

Simple tests estimate the leak to be about 3 MB per 10,000 dates
parsed, so unless you're parsing hundreds of thousands, or millions of
dates, the leak probably won't be a problem on systems with moderate
amounts of memory. And if you're parsing that many dates, the
relatively slow Date::Manip may not be the correct module for you to
use anyway.

=item B<Unable to determine Time Zone>

Please refer to the Date::Manip::TZ documentation for a discussion
of this problem.

=item B<Calculations appear to be off by an hour>

Within days of releasing 6.00, I got the following report:

   print DateCalc(ParseDate("2009/10/31"), "+1 day"), "\n";
   print DateCalc(ParseDate("2009/11/01"), "+1 day"), "\n";
   print DateCalc(ParseDate("2009/11/02"), "+1 day"), "\n";

produced:

   2009110100:00:00
   2009110123:00:00
   2009110300:00:00

In other words, the second calculation appears to be off by one hour.
In actuality, the result is correct. In the user's time zone, daylight
saving time ended on Nov 1, and since "+ 1 day" is equivalent to "+ 24
hours", the results are correct. In America/New_York time (which has
the same result), the calculation means that:

   2009-11-01 00:00:00 EDT + 24 hours =
   2009-11-01 23:00:00 EST

which is correct.

=item B<Missing date formats>

Due to the large number of date formats that Date::Manip CAN process,
people often assume that other formats that they want to use should
work as well, and when they don't, it comes as a surprise.

With the much improved parsing of 6.00, many formats can be added
easily, though unless they are of general use, I'll probably suggest
that you use parse_format instead.

There is a class of formats that I will not add however.

I have frequently been asked to add formats such as "the 15th of last
month", or "Monday of next week". I will NOT add these date formats to
Date::Manip. Since I have received the request several times, I
decided to include my reasoning here.

Date::Manip can parse pretty much any static date format that I could
think of or find reference to. Dates such as "today", "Jan 12", or
"2001-01-01" are all understood.

These are fairly limited however. Many very common date formats are
best thought of as a date plus a modification. For example,
"yesterday" is actually determined internally as "today" plus a
modification of "- 1 day".  "2nd Sunday in June" is determined as
"June 1" modified to the 2nd Sunday.

As these types of formats were added over time, I quickly realized
that the number of possible date plus modification formats was
huge. The number of combinations has caused the parsing in Date::Manip
to be quite complex, and adding new formats occasionally causes
unexpected conflicts with other formats.

The first time I received a request similar to "the 15th of last
month", I intended to add it, but as I analyzed it to see what changes
needed to be made to support it, I realized that this needed to be
expressed as a date plus TWO modifications. In other words, today
modified to last month modified to the 15th day of the month.

As bad as date plus modification formats are, a date plus TWO
modifications would be exponentially worse. On realizing that, I made
a firm decision that Date::Manip will NOT support this type of format
now, or at any time in the future. Although I apologize for the
inconvenience, I do not intend to change my position on this.

=item B<Date::Manip is slow>

NOTE: The following section applies primarily to 5.xx. I'm doing a lot
of work to optimize Date::Manip and I will rewrite this section to
take this into account, and to provide performance suggestions. It
should be noted that initial tests show version 6.xx to be around
twice as fast as 5.xx (though still considerably slower than some
of the other modules).

Date::Manip is probably one of the slower Date/Time modules due to the
fact that it is huge and written entirely in perl.

Some things that will definitely help:

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.

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 :-)

=item B<RCS Control>

If you try to put Date::Manip under RCS control, you are going to have
problems.  Apparently, RCS replaces strings of the form "$Date...$" with
the current date.  This form occurs all over in Date::Manip.  To prevent the
RCS keyword expansion, checkout files using:

   co -ko

Since very few people will ever have a desire to do this (and I don't
use RCS), I have not worried about it, and I do not intend to try to
workaround this problem.

=item B<Using functions/methods which are not supported>

There have been a handful of incidents of people using a function from
Date::Manip which were not documented in the manual.

Date::Manip consists of a large number of user functions which are
documented in the manual. These are designed to be used by other
programmers, and I will not make any backwards incompatible changes in
them unless there is a very compelling reason to do so, and in that
case, the change will be clearly documented in the
Date::Manip::Changes6 documentation for this module.

Date::Manip also includes a large number of functions which are NOT
documented. These are for internal use only.  Please do not use them!
I can (and do) change their use, and even their name, without notice,
and without apology!  Some of these internal functions even have test
scripts, but that is not a guarantee that they will not change, nor is
any support implied. I simply like to run regression tests on as much
of Date::Manip as possible.

As of the most recent versions of Date::Manip, all internal functions
have names that begin with an underscore (_). If you choose to use
them directly, it is quite possible that new versions of Date::Manip
will cause your programs to break due to a change in how those
functions work.

Any changes to internal functions will not be documented, and will not
be regarded by me as a backwards incompatibility. Nor will I (as was
requested in one instance) revert to a previous version of the
internal function.

If you feel that an internal function is of more general use, feel
free to contact me with an argument of why it should be "promoted".  I
welcome suggestions and will definitely consider any such request.

=back

=head1 KNOWN COMPLAINTS

Date::Manip 6.xx has gotten some complaints (far more than 5.xx if the
truth be told), so I'd like to address a couple of them here.  Perhaps
an understanding of why some of the changes were made will allay some
of the complaints.  If not, people are always welcome to stick with
the 5.xx release. I will continue to support the 5.xx releases for a
couple years (though I do NOT plan to add functionality to it).

These complaints come both from both the CPAN ratings site:

   http://cpanratings.perl.org/dist/Date-Manip

and from personal email.

=over 4

=item B<Requires perl 5.10>

The single most controversial change made in 6.00 is that it now
required perl 5.10.0 or higher. Most of the negative feedback I've
received is due to this.

In the past, I've avoided using new features of perl in order to allow
Date::Manip to run on older versions of perl.  Prior to perl 5.10,
none of the new features would have had a major impact on how
Date::Manip was written, however that changed in 5.10.

One of the aspects of Date::Manip that has received the most positive
response is the ability to parse almost every conceivable date format.
Unfortunately, as I've added formats, the parsing routine became more
and more complicated, and maintaining it was one of the least
enjoyable aspect in maintaining Date::Manip . For several years, I've
been extremely reluctant to add new formats due to the fact that too
often, adding a new format broke other formats.

As I was rewriting Date::Manip, I was looking for ways to improve the
parsing and to make maintaining it easier. Perl 5.10 provides the
feature "named capture buffers". Named capture buffers not only
improves the ease of maintaining the complex regular expressions used
by Date::Manip, it makes it dramatically easier to add additional
formats in a way that is much less likely to interfere with other
formats. The parsing in 6.00 is so much more robust, extensible, and
flexible, that it will make parser maintenance possible for many years
to come at a fraction of the effort and risk.

It was too much to turn down. Hopefully, since 5.10 has been out for
some time now, this will not prohibit too many people from using the
new version of Date::Manip. I realize that there are many people out
there using older versions of perl who do not have the option of
upgrading perl.  The decision to use 5.10 wasn't made lightly... but I
don't regret making it. I apologize to users who, as a result, cannot
use 6.00 . Hopefully in the future you'll be able to benefit from the
improvements in 6.00.

One complaint I've received is that this in some way makes Date::Manip
backwards incompatible, but this is not an accurate complaint. Version
6.xx DOES include some backwards incompatibilities (and these are
covered in the Date::Manip::Migration5to6 document), however in almost
all cases, these incompatibilities are with infrequently used
features, or workarounds are in place to allow deprecated features to
continue functioning for some period of time.

Though I have no data to confirm this, I suspect that 90% or more of
all scripts which were written with Date::Manip 5.xx will continue to
work unmodified with 6.xx (of course, you should still refer to the
migration document to see what features are deprecated or changed to
make sure that you don't need to modify your script so that it will
continue to work in the future). Even with scripts that need to be
changed, those changes should be trivial.

So, Date::Manip 6.xx is almost entirely backward compatible with 5.xx
(to the extent that you would expect any major version release to be
compatible with a previous major version).

The change is only in the requirements necessary to get Date::Manip
6.xx to run.

Obviously, it's not reasonable to say that Date::Manip should never be
allowed to switch minimum perl versions. At some point, you have to
let go of an old version if you want to make use of the features of
the newer version. The question is, did I jump to 5.10 too fast?

The complaints I see on the CPAN ratings complain that I no longer
support perl 5.6 and perl 5.8.

With respect to 5.6, perl 5.6 was released in March of 2000 (that's
before Windows XP which was released in 2001). To be honest, I don't
really feel much sympathy for this complaint. Software that is 9 years
old is ANCIENT. People may choose to use it... but please don't
complain when new software comes out that doesn't support it.

The argument for perl 5.8 is much more compelling. Although 5.8 was
released quite some time ago (July of 2002), there were no major perl
releases until 5.10 came out in December of 2007, so 5.8 was
state-of-the art as little as 2 years prior to the release of
Date::Manip 6.xx.

I agree completely with the argument that abandoning 5.8 only 2 years
after it was the current version is too soon. For that reason, I will
continue to support the Date::Manip 5.xx releases for some years to
come. I don't know exactly how long I'll continue to support them,
but it'll be at least 2-3 years. Once perl 5.10 is 5 years old, I'll
be much more likely to drop support for the 5.xx releases, but I DO
want to make use of the features of 5.10 for future development.
They make development so much easier, and the parsing so much more
robust (something I've wanted for years), that I'm not willing to
give up the advantages of 5.10.

But the next complaint is relevant.

=item B<Automatic installs break>

A much more important problem is that versions 6.01 through 6.07 broke
automatic installs for older perl installations. If you try to install
Date::Manip using the automatic tools (cpan/cpanp), they will look for
the most recent version. If you are using a version of perl older than
5.10, this fails, and rather than looking for an older version, the
tool simply reports a failure in installing Date::Manip.  Technically,
the problem is not due to Date::Manip itself, but is a result of how
perl modules are currently managed.  However, since Date::Manip is
managed by then, it's important to avoid causing this type of problem
(which I clearly failed to do).

As of Date::Manip 6.10, this problem should no longer occur. Starting
with version 6.10, both the 5.xx and 6.xx versions of Date::Manip have
been combined into a single distribution (so Date-Manip-6.10 contained
both Date::Manip 6.10 and Date::Manip 5.57). From Date::Manip 6.10 to
6.13, the perl version was determined at install time and either the
5.xx or 6.xx version was installed.  From Date::Manip 6.14 on, both
versions are installed, and at run time, the correct version will be
chosen (and if you're running a recent version of perl, you can select
to run the old or new version).

All future version (for as long as 5.xx is supported) will include
both the most current 5.xx and 6.xx releases of Date::Manip. In this
way, automatic install tools will be able to install Date::Manip
regardless of which version of perl you are running.

=item B<Too many modules>

One minor complaint is that there are too many files. One person
specifically objects to the fact that there are over 470 modules
covering non-minute offsets. This complaint is (IMO) silly.

Date::Manip supports ALL historical time zones, including those with
non-minute offsets, and so there will be information for those time
zones, even though they are not currently in use.

I could of course store all of the information in one big module, but
that means that you have to load all of that data every time you use
Date::Manip, and I find that to be a very poor solution. Instead,
storing the information in a per-time zone and per-offset manner
dramatically decreases the amount of data that has to be loaded.

While it is true that Date::Manip includes over 900 modules for all of
the time zone information, most implementations of time zone handling
also choose to break up the data into a large number of files.

My linux distribution (openSuSE 11.2 at the time of writing this) uses
the standard zoneinfo database, and at this point, there are over 1700
files included in /usr/share/zoneinfo (though it does appear that
there is some duplication of information). Current versions of RedHat
also use over 1700 files, so Date::Manip isn't treating the time zone
problem in a new or unreasonable way.

=item B<Objects are large>

One complaint that was put on the CPAN ratings site was that the OO
interface is "a dud" due to the size of it's objects. The complaint is
that a Date::Manip::Date object is 115K while it should (according to
the complaint) only require that you need to save the seconds from the
epoch, zone, and a couple other pieces of information, all of which
could probably be stored in 100 bytes or less.

Date::Manip is very configurable, and contains a great deal of
information which could theoretically be calculated on the fly, but
which would greatly reduce it's performance. Instead, in the interest
of improving performance, the data is cached, and since the data is
virtually all potentially object specific, it has to be somehow linked
to the object.

For example, Date::Manip allows you to parse dates in several
languages.  Each language has a large number of regular expressions
which are used to to the actual parsing. Instead of recreating these
regular expressions each time they are needed, they are created once
and stored in an object (specifically, a Date::Manip::Base object).
The size of the Date::Manip::Base object is almost 15K (due primarily
to the regular expressions used in parsing dates in the selected
language).

Similarly, a description of the time zones are stored in a second
object (a Date::Manip::TZ object).  The size of the Date::Manip::TZ
object starts at 100K. That may seem excessive, but you have to
remember that there are almost 500 time zones, and they have to be
indexed by name, alias, abbreviation, and offset, and by the time you
do this, it does take a fair bit of space.  It should also be noted
that the full description of each timezone is only stored in the
object when the timezone is actually used, so if you use a lot of
timezones, this object will grow slowly as new timezones are used.

The size of the actual Date::Manip::Date object is a little over 300
bytes.

Both the Date::Manip::Base and Date::Manip::TZ objects are reused by
any number of Date::Manip::Date objects. They can almost be thought of
as global data, except that they are accessible in the standard OO
manner, and you are allowed to modify them on a per-object basis which
WILL mean that you have to store more data. If you work with multiple
configurations (see Date::Manip::Config), you'll need multiple Base
and TZ objects. However, most of the time you will not need to do
this.

The Date::Manip::Date object is a bit larger than suggested in the
complaint, but it should be noted that Date::Manip actually stores the
dates in a number of different formats (a string of the form
YYYYMMDDHH:MN:SS and a list [YYYY,MM,DD,HH,MN,SS] in the time zone it
was parsed in, the local time zone (if different) and GMT. By caching
this information as it is used, it has a huge impact on the
performance.

So, Date::Manip in typical usage consists of one 100K Date::Manip::TZ
object, one 15K Date::Manip::Base objects, and any number of small 300
byte Date::Manip::Date objects.  Date::Manip::Delta objects are even
smaller. Date::Manip::Recur objects are also small, but they contain
any number of Date objects in them.

I am certainly open to suggestions as to how I can improve the OO
interface... but I don't believe it is a dud. While I'm not an expert
at OO programming, I believe that I followed pretty standard and
accepted procedures for accessing the data.

Please refer to the Date::Manip::Objects document for more
information.

=item Date::Manip has an inconsistent interface

I've gotten a few complaints that the interface to Date::Manip is
inconsistent... and I agree (at least when using the functional
interfaces).

Date::Manip was originally written in an unplanned way... as a need/want
came up, it was extended. That's not the way to write a major package
of course, but it wasn't expected to be a major package at the start.

As it became more and more widely used, I too wished for a more
consistent interface, but I did not want to break backward compatibility
for everyone using it.

When 6.xx was written, I spent a good deal of time trying to make a very
standard interface, so I do not believe that this complaint can be
applied to the OO interface (though I'm interested in suggestions for
improving it of course).

As far as the functional interface goes, I'll continue to support it
in a backward compatible (and therefore inconsistent) form. I'd
encourage the use of the OO interface whenever possible.

=back

=head1 BUGS AND QUESTIONS

If you find a bug in Date::Manip, please send it directly to me (see
the AUTHOR section below).  Alternately, you can submit it on CPAN. This
can be done at the following URL:

   http://rt.cpan.org/Public/Dist/Display.html?Name=Date-Manip

Please do not use other means to report bugs (such as Usenet newsgroups,
or forums for a specific OS or Linux distribution) as it is impossible
for me to keep up with all of them.

When filing a bug report, please include the following information:

=over 4

=item B<Date::Manip version>

Please include the version of Date::Manip you are using.  You can get
this by using the script:

   use Date::Manip;
   print DateManipVersion(1),"\n";

or

   use Date::Manip::Date;
   $obj = new Date::Manip::Date;
   print $obj->version(1),"\n";

=item B<Perl information>

Please include the output from "perl -V"

=back

If you have a problem using Date::Manip that perhaps isn't a bug
(can't figure out the syntax, etc.), you're in the right place.  Start
by reading the main Date::Manip documentation, and the other documents
that apply to whatever you are trying to do.  If this still doesn't
answer your question, mail me directly.

I would ask that you be reasonably familiar with the documentation
BEFORE you choose to do this. Date::Manip is a hobby, and I simply do
not have time to respond to hundreds of questions which are already
answered in this manual.

If you find any problems with the documentation (errors, typos, or items
that are not clear), please send them to me. I welcome any suggestions
that will allow me to improve the documentation.

=head1 KNOWN BUGS

None known.

=head1 SEE ALSO

Date::Manip        - main module documentation

=head1 LICENSE

This script is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 AUTHOR

Sullivan Beck (sbeck@cpan.org)

=cut