# Copyright (c) 1995-2017 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<Unable to determine Time Zone>

If you ever get the message that Date::Manip was unable to determine the

timezone, you need to provide that information to your script.

Please refer to the L<Date::Manip::TZ> documentation for a discussion

of this problem.

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

Due to daylight saving time (especially the spring change where

the time typically moves forward from 02:00 to 03:00), any date

calculation which would intuitively report a time in that range

will also move forward (or backward as the case may be).

*NOTE* This should be less of a problem since 6.30 with the addition

of semi-exact deltas.

=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 do not plan to add however.

I have frequently been asked to add formats such as "the 15th of last

month", or "Monday of next week". I do not intend to add these date

formats to Date::Manip, but 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

decided that Date::Manip will not support this type of format.

Although I apologize for the inconvenience, I do not intend to change

my position on this.

=item B<Date::Manip is slow>

Date::Manip is one of the slower Date/Time modules due to the fact that

it is huge and written entirely in perl.  I have done a lot of work

optimizing it since 6.xx came out, and additional work is planned,

but even at it's best, it will probably be slower than other modules.

Some things that will definitely help:

Date::Manip 5.xx was very slow.  A lot of work went into speeding it up

as I rewrote it for the 6.xx release, and it should be noted that

initial tests show version 6.xx to be around twice as fast as 5.xx.

There is one notable exception to this speedup.  If you use Date::Manip

to parse dates from a wide variety of timezones, 6.xx will be significantly

slower than 5.xx.  The reason for this is that each time a new timezone is

accessed, 6.xx does quite a bit of work to initialize it.  5.xx does not

have this overhead, so it can parse dates from any number of timezones

without a speed penalty.  However, 5.xx does NOT handle timezones correctly,

so many of the dates will be incorrect.  If timezones are important to you,

there is no way to use 5.xx and get accurate results.

If you only parse dates from a single timezone (which is more often what

you are doing), 6.xx is significantly faster than 5.xx.

ISO-8601 dates are parsed first and fastest.  If you have the flexibility

to define the date format, use ISO-8601 formats 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<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 up to (and including) the following versions:

   5.10.1

   5.12.5

   5.14.3

   5.15.5

The bug has been fixed in:

   5.15.6

   5.16.0

If a maintenance release is done for any of the other releases (5.10,

5.12, 5.14), that includes the patch, I'll update this section to

include that information.

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<Dmake error on strawberry perl>

Users of Strawberry perl on windows may encounter an error similar

to the following:

   dmake: makefile: line 3016: Error: -- Input line too long, increase MAXLINELENGTH

This is a known problem with some versions of strawberry perl, and

I can't fix it in Date::Manip.  If you encounter this problem, you

can install the package manually using the commands:

   c:> cpan

   cpan> look Date::Manip::Date

   > perl Makefile.PL

   > dmake MAXLINELENGTH=300000 make

   > dmake MAXLINELENGTH=300000 make test

   > dmake MAXLINELENGTH=300000 make install

You can find more details here:

   http://www.nntp.perl.org/group/perl.win32.vanilla/2011/02/msg287.html

=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

L<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 functionality, 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.

=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.

=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 so this practice was justified. That all

changed with the release of perl 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 . In fact, for several

years I'd 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 L<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, the 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 negative ratings I see in 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). Date::Manip 6.00 was

released at the end of 2009.  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 well before Date::Manip 6.00 (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

continued to support the Date::Manip 5.xx releases for several years.

As of December 2012 (5 years after the release of perl 5.10), the 5.xx

release is no longer supported (in that I will not patch it or provide

support for it's use).  However, it is still bundled into the Date::Manip

distribution so it can still be used.  I do not have any plans for

removing it, though I may do so at some point.

=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

data 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 L<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.

This complaint is not accurate, and comes from a misunderstanding

of the objects used by Date::Manip.

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 do 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 L<Date::Manip::Base> object).

The size of the L<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 L<Date::Manip::TZ> object).  The size of the L<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.  In addition, critical

dates (dates where the offset from GMT change such as during a daylight

saving time change) along with information such as offsets, abbreviation,

etc., are all cached in order to improve performance.  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 L<Date::Manip::Date> object is a little over 300

bytes.  However, each includes a pointer to a L<Date::Manip::Base> and

a L<Date::Manip::TZ> object (and due to how the object was being looked

at in the complaint, they were reporting the size of all three objects,

NOT just the L<Date::Manip::Date> object).

Both the L<Date::Manip::Base> and L<Date::Manip::TZ> objects are reused by

any number of L<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 L<Date::Manip::Config>), you'll need multiple Base

and TZ objects. However, most of the time you will not need to do

this.

The actual L<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 L<Date::Manip::TZ>

object, one 15K L<Date::Manip::Base> objects, and any number of small 300

byte L<Date::Manip::Date> objects.  L<Date::Manip::Delta> objects are even

smaller. L<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 L<Date::Manip::Objects> document for more

information.

=item B<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 referring to 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 OO 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, there are three ways to send it to me.

Any of them are fine, so use the method that is easiest for you.

=over 4

=item Direct email

You are welcome to send it directly to me by email.  The email address

to use is:  sbeck@cpan.org.

=item CPAN Bug Tracking

You can submit it using the CPAN tracking too.  This can be done at the

following URL:

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

=item GitHub

You can submit it as an issue on GitHub.  This can be done at the following

URL:

L<https://github.com/SBECK-github/Date-Manip>

=back

Please do not use other means to report bugs (such as 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

L<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