libdate-manip-perl 6.52-1 / usr / share / perl5 / Date / Manip / Misc.pod

# Copyright (c) 1995-2015 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::Misc - Miscellaneous information about Date::Manip

=head1 SHOULD I USE DATE::MANIP

If you look in CPAN, you'll find that there are a number of Date and
Time packages.  Is Date::Manip the one you should be using? That isn't
a trivial question to answer. It depends to a large extent on what you
are trying to do.

Date::Manip is certainly one of the most powerful of the Date modules
(the other main contender being the DateTime suite of modules).  I'm
trying to build a library which can do _EVERY_ conceivable
date/time manipulation that you'll run into in everyday life dealing with
the Gregorian calendar.  To the best of my knowledge, it will do
everything that any other date module will do which work with the
Gregorian calendar, and there are a number of features that Date::Manip
has that other modules do not have.

There is a tradeoff in being able to do "everything"... and that
tradeoff is primarily in terms of performance.  Date::Manip is written
entirely in Perl and is the largest of the date modules. Other modules
tend to be faster than Date::Manip, and modules written in C are
significantly faster than their Perl counterparts (at least if they're
done right).  Although I am working on making Date::Manip faster, it
will never be as fast as other modules.  And before anyone asks,
Date::Manip will never be translated to C (at least by me).  I write C
because I have to.  I write Perl because I like to.  Date::Manip is
something I do because it interests me, not something I'm paid for.

If you are going to be using the module in cases where performance is
an important factor, and you're doing a fairly small set of simple
date operations over and over again, you should carefully examine the
other date modules to see if they will meet your needs.

Date::Manip does NOT provide functionality for working with alternate
calendars such as the Chinese or Hebrew calendars, so if you need that
functionality, you definitely need to look elsewhere (the DateTime suite
probably).

On the other hand, if you want one solution for all your date needs,
don't need peak speed, or are trying to do more exotic date
operations, Date::Manip is for you.  Operations on things like
business dates, foreign language dates, holidays and other recurring
events, complete timezone handling, etc. are available more-or-less
exclusively in Date::Manip. At the very least, if you want to be able
to do these operations, it will require using several other modules,
each with it's own interface.  Also, when you work with Date::Manip,
you work with one author and one module.  The DateTime suite
currently consists of almost 100 modules and 75 authors.

In addition, I am making significant performance improvements in
Date::Manip.  Although it will never be as fast as some of the other
perl modules, I believe that it is already competitive enough for most
purposes, and I continue to look for places where I can improve
performance, so performance should improve over time.

=head1 YEAR 2000 AND YEAR 2007 DST CHANGE

Did Date::Manip have any problems with Y2K compliance? Did it have any
problems with the revised daylight saving time changes made in 2007?

Although Date::Manip will parse many date strings (including dates
with 2-digit years), internally they are stored as a 4 digit year, and
all operations are performed using this internal representation, so
Date::Manip had no problems with the Y2K issue. Of course,
applications written which stored the year as 2 digits (whether or not
it used Date::Manip) may have had problems, but they were not because
of this module.

Similarly for the 2007 changes in daylight saving time made in the United
States, Date::Manip was not affected. Date::Manip makes use of the
current time zone, but it gets that information from the operating system
the application is running on. If the operating system knows about the
new daylight saving time rules... so does Date::Manip.

=head1 WHAT DATES ARE DATE::MANIP USEFUL FOR?

Date::Manip applies to the Gregorian calendar. It does not support
alternative calendars (Hebrew, Mayan, etc.) so if you want to use
an alternative calendar, you'll need to look elsewhere.

The Gregorian calendar is a relatively recent innovation. Prior to it,
the Julian calendar was in use.  The Julian calendar defined leap years as
every 4th year.  This led to significant calendar drift over time (since
a year is NOT 365.25 days long). It was replaced by the Gregorian
calendar which improved the definition of leap years, and at that point,
the calendar was adjusted appropriately.

Date::Manip extrapolates the Gregorian calendar back to the year 0001
AD and forward to the year 9999 AD, but that does not necessarily mean
that the results are useful. As the world adopted the Gregorian
calendar, the dates using the Julian calendar had to be changed to fit
to account for the drift that had occurred. As such, the dates
produced by Date::Manip in an era where the Julian calendar was in use
do not accurately reflect the dates actually in use. In historical
context, the Julian calendar was in use until 1582 when the Gregorian
calendar was adopted by the Catholic church.  Protestant countries did
not accept it until later; Germany and Netherlands in 1698, British
Empire in 1752, Russia in 1918, etc. Date::Manip is therefore not
equipped to truly deal with historical dates prior to about 1600, and
between 1600 and 1900, the calendar varied from country to country.

A second problem is that the Gregorian calendar is itself imperfect
and at some point may need to be corrected (though it's not clear that
this will happen... drift may now be accounted for using leap seconds
which means that the Gregorian calendar may be useful indefinitely).
No attempt is made to correct for the problems in the Gregorian
calendar for a couple reasons. First is that my great great great
grandchildren will be long dead before this begins to be a problem, so
it's not an immediate concern.  Secondly, and even more importantly, I
don't know what the correction will be (if any) or when it will be
implemented, so I can safely ignore it.

There is some limitation on how dates can be expressed such that
Date::Manip can handle them correctly. Date::Manip stores the year
internally as a 4-digit number. This is obviously not a limit due to
the Gregorian calendar, but I needed a way to store the dates
internally, and the 4-digit year was chosen. I realize that the
4-digit limitation does create a time when it will break (quite
similar to those who chose a 2-digit representation set themselves up
for the Y2K problem). Frankly, I'm not too concerned about this since
that date is 8000 years in the future! Date::Manip won't exist then.
Perl won't exist then. And it's quite possible that the Gregorian
calendar won't exist then. That's a much different situation than the
Y2K choice in which programmers chose a representation that would
break within the lifetime of the programs they were writing.

Given the 4-digit limitation, Date::Manip definitely can't handle BC
dates, or dates past Dec 31, 9999.  So Date::Manip works (in theory)
during the period Jan 1, 0001 to Dec 31, 9999. There are a few
caveats:

=over 4

=item B<Gregorian calendar issue>

In practical terms, Date::Manip deals with the Gregorian calendar, and
is most useful in the period that that calendar has been, or will be,
in effect. As explained above, the Gregorian calendar came into universal
acceptance in the early 1900's, and it should remain in use for the
foreseeable future.

So...  in practical terms, Date::Manip is probably useful from
around 1900 through several thousand years from now.

=item B<First/last week>

In one part of the code (calculating week-of-year values), Date::Manip
references dates one week after and one week before the date actually
being worked on. As such, dates during the first week in the year 0001
fail (because a week before is in the year 1 BC), and those in the last
week in the year 9999 fail (because a week later is in 10,000).

No effort will be made to correct this because the added functionality
is simply not that important (to me), especially since the Gregorian
calendar doesn't really apply in either instance. To be absolutely
safe, I will state that Date::Manip works as described in this manual
during the period Feb 1, 0001 to Nov 30, 9999, and I will only support
dates within that range (i.e. if you submit a bug using a date that is
not in that range, I will will consider myself free to ignore it).

=item B<Leap seconds>

Date::Manip does NOT make use of the leap seconds in calculating time
intervals, so the difference between two times may not be strictly
accurate due to the addition of a leap second.

=item B<Three-digit years>

Date::Manip will parse both 2- and 4-digit years, but it will NOT
handle 3 digit years.  So, if you store the year as an offset from
1900 (which is 3 digits long as of the year 2000), these will NOT be
parseable by Date::Manip. Since the perl functions localtime and gmtime
DO return the year as an offset from 1900, the output from these will
need to be corrected (probably by adding 1900 to the result) before
they can be passed to any Date::Manip routine.

=back

=head1 FUTURE IDEAS

A number of changes are being considered for future inclusion in
Date::Manip.  As a rule, the changes listed below are not finalized,
and are open to discussion.

=over 4

=item B<Rewrite parsing for better language support>

Currently, all of Date::Manip's parsing is based on English language
forms of dates, even if the words have been replaced by the equivalent
in some other language.

I am considering rewriting the parsing routines in order to allow
date forms that might be used in other languages but do not have a
common English equivalent, and to account for the fact that some
English formats may not have an equivalent in another language.

=item B<Adding granularity>

The granularity of a time basically refers to how accurate you wish to
treat a date.  For example, if you want to compare two dates to see if
they are identical at a granularity of days, then they only have to occur
on the same day.  At a granularity of an hour, they have to occur within
an hour of each other, etc.

I'm not sure how useful this would be, but it's one of the oldest
unimplemented ideas, so I'm not discarding it completely.

=back

=head1 ACKNOWLEDGMENTS

There are many people who have contributed to Date::Manip over the
years that I'd like to thank.  The most important contributions have
come in the form of suggestions and bug reports by users.  I have
tried to include the name of every person who first suggested each
improvement or first reported each bug.  These are included in the
L<Date::Manip::Changes5> and L<Date::Manip::Changes6> documents.  The list
is simply too long to appear here, but I appreciate their help.

A number of people have made suggestions or reported bugs which are
not mentioned in these documents.  These include suggestions which
have not been implemented and people who have made a suggestion or bug
report which has already been suggested/reported by someone else.  For
those who's suggestions have not yet been implemented, they will be
added to the appropriate Changes document when (if) their suggestions
are implemented.  I keep every single suggestion I've ever received
and periodically review the unimplemented ones to see if it's
something I'm interested in, so even suggestions made years in the
past may still appear in future versions of Date::Manip, and the
original requester will be attributed at that point (some of the
changes made to Date::Manip 6.00 were based on suggestions 10 years
old which never fit in with version 5.xx, but which I knew I wanted to
implement). For those who have sent in requests/reports that had been
previously made by someone else, thank you too.  I'd much rather have
a suggestion made twice than not at all.

Thanks to Alan Cezar and Greg Schiedler for paying me to implement the
Events_List routine.  They gave me the idea, and were then willing to pay
me for my time to get it implemented quickly.

I'd also like to thank a couple of authors.  Date::Manip has gotten
some really good press in a couple of books.  Since no one's paying me
to write Date::Manip, seeing my module get a good review in a book
written by someone else really makes my day.  My thanks to Nate
Padwardhan and Clay Irving (Programming with Perl Modules -- part of
the O'Reilly Perl Resource Kit); and Tom Christiansen and Nathan
Torkington (The Perl Cookbook).  Also, thanks to any other authors
who've written about Date::Manip who's books I haven't seen.

I'd also like to thank the people who are maintaining the zoneinfo
database (and who replied quickly to several inquiries).

I have borrowed from other modules. I originally borrowed the code for
determining if a year was a leap year from code written by David Muir
Sharnoff.  I borrowed many of the original date printf formats from
code written by Terry McGonigal as well as the Solaris date command.
More recently, I borrowed the code to do time zone registry lookups on
Windows from the DateTime-TimeZone module, though I rewrote it to work
better with Date::Manip.

=head1 BUGS AND QUESTIONS

Please refer to the L<Date::Manip::Problems> documentation for
information on submitting bug reports or questions to the author.

=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