|
Packit |
95306a |
# Copyright (c) 1995-2017 Sullivan Beck. All rights reserved.
|
|
Packit |
95306a |
# This program is free software; you can redistribute it and/or modify it
|
|
Packit |
95306a |
# under the same terms as Perl itself.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=pod
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 NAME
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip::Misc - Miscellaneous information about Date::Manip
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 SHOULD I USE DATE::MANIP
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If you look in CPAN, you'll find that there are a number of Date and
|
|
Packit |
95306a |
Time packages. Is Date::Manip the one you should be using? That isn't
|
|
Packit |
95306a |
a trivial question to answer. It depends to a large extent on what you
|
|
Packit |
95306a |
are trying to do.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip is certainly one of the most powerful of the Date modules
|
|
Packit |
95306a |
(the other main contender being the DateTime suite of modules). I'm
|
|
Packit |
95306a |
trying to build a library which can do _EVERY_ conceivable
|
|
Packit |
95306a |
date/time manipulation that you'll run into in everyday life dealing with
|
|
Packit |
95306a |
the Gregorian calendar. To the best of my knowledge, it will do
|
|
Packit |
95306a |
everything that any other date module will do which work with the
|
|
Packit |
95306a |
Gregorian calendar, and there are a number of features that Date::Manip
|
|
Packit |
95306a |
has that other modules do not have.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
There is a tradeoff in being able to do "everything"... and that
|
|
Packit |
95306a |
tradeoff is primarily in terms of performance. Date::Manip is written
|
|
Packit |
95306a |
entirely in Perl and is the largest of the date modules. Other modules
|
|
Packit |
95306a |
tend to be faster than Date::Manip, and modules written in C are
|
|
Packit |
95306a |
significantly faster than their Perl counterparts (at least if they're
|
|
Packit |
95306a |
done right). Although I am working on making Date::Manip faster, it
|
|
Packit |
95306a |
will never be as fast as other modules. And before anyone asks,
|
|
Packit |
95306a |
Date::Manip will never be translated to C (at least by me). I write C
|
|
Packit |
95306a |
because I have to. I write Perl because I like to. Date::Manip is
|
|
Packit |
95306a |
something I do because it interests me, not something I'm paid for.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If you are going to be using the module in cases where performance is
|
|
Packit |
95306a |
an important factor, and you're doing a fairly small set of simple
|
|
Packit |
95306a |
date operations over and over again, you should carefully examine the
|
|
Packit |
95306a |
other date modules to see if they will meet your needs.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip does NOT provide functionality for working with alternate
|
|
Packit |
95306a |
calendars such as the Chinese or Hebrew calendars, so if you need that
|
|
Packit |
95306a |
functionality, you definitely need to look elsewhere (the DateTime suite
|
|
Packit |
95306a |
probably).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
On the other hand, if you want one solution for all your date needs,
|
|
Packit |
95306a |
don't need peak speed, or are trying to do more exotic date
|
|
Packit |
95306a |
operations, Date::Manip is for you. Operations on things like
|
|
Packit |
95306a |
business dates, foreign language dates, holidays and other recurring
|
|
Packit |
95306a |
events, complete timezone handling, etc. are available more-or-less
|
|
Packit |
95306a |
exclusively in Date::Manip. At the very least, if you want to be able
|
|
Packit |
95306a |
to do these operations, it will require using several other modules,
|
|
Packit |
95306a |
each with it's own interface. Also, when you work with Date::Manip,
|
|
Packit |
95306a |
you work with one author and one module. The DateTime suite
|
|
Packit |
95306a |
currently consists of almost 100 modules and 75 authors.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In addition, I am making significant performance improvements in
|
|
Packit |
95306a |
Date::Manip. Although it will never be as fast as some of the other
|
|
Packit |
95306a |
perl modules, I believe that it is already competitive enough for most
|
|
Packit |
95306a |
purposes, and I continue to look for places where I can improve
|
|
Packit |
95306a |
performance, so performance should improve over time.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 YEAR 2000 AND YEAR 2007 DST CHANGE
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Did Date::Manip have any problems with Y2K compliance? Did it have any
|
|
Packit |
95306a |
problems with the revised daylight saving time changes made in 2007?
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Although Date::Manip will parse many date strings (including dates
|
|
Packit |
95306a |
with 2-digit years), internally they are stored as a 4 digit year, and
|
|
Packit |
95306a |
all operations are performed using this internal representation, so
|
|
Packit |
95306a |
Date::Manip had no problems with the Y2K issue. Of course,
|
|
Packit |
95306a |
applications written which stored the year as 2 digits (whether or not
|
|
Packit |
95306a |
it used Date::Manip) may have had problems, but they were not because
|
|
Packit |
95306a |
of this module.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Similarly for the 2007 changes in daylight saving time made in the United
|
|
Packit |
95306a |
States, Date::Manip was not affected. Date::Manip makes use of the
|
|
Packit |
95306a |
current time zone, but it gets that information from the operating system
|
|
Packit |
95306a |
the application is running on. If the operating system knows about the
|
|
Packit |
95306a |
new daylight saving time rules... so does Date::Manip.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 WHAT DATES ARE DATE::MANIP USEFUL FOR?
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip applies to the Gregorian calendar. It does not support
|
|
Packit |
95306a |
alternative calendars (Hebrew, Mayan, etc.) so if you want to use
|
|
Packit |
95306a |
an alternative calendar, you'll need to look elsewhere.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The Gregorian calendar is a relatively recent innovation. Prior to it,
|
|
Packit |
95306a |
the Julian calendar was in use. The Julian calendar defined leap years as
|
|
Packit |
95306a |
every 4th year. This led to significant calendar drift over time (since
|
|
Packit |
95306a |
a year is NOT 365.25 days long). It was replaced by the Gregorian
|
|
Packit |
95306a |
calendar which improved the definition of leap years, and at that point,
|
|
Packit |
95306a |
the calendar was adjusted appropriately.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip extrapolates the Gregorian calendar back to the year 0001
|
|
Packit |
95306a |
AD and forward to the year 9999 AD, but that does not necessarily mean
|
|
Packit |
95306a |
that the results are useful. As the world adopted the Gregorian
|
|
Packit |
95306a |
calendar, the dates using the Julian calendar had to be changed to fit
|
|
Packit |
95306a |
to account for the drift that had occurred. As such, the dates
|
|
Packit |
95306a |
produced by Date::Manip in an era where the Julian calendar was in use
|
|
Packit |
95306a |
do not accurately reflect the dates actually in use. In historical
|
|
Packit |
95306a |
context, the Julian calendar was in use until 1582 when the Gregorian
|
|
Packit |
95306a |
calendar was adopted by the Catholic church. Protestant countries did
|
|
Packit |
95306a |
not accept it until later; Germany and Netherlands in 1698, British
|
|
Packit |
95306a |
Empire in 1752, Russia in 1918, etc. Date::Manip is therefore not
|
|
Packit |
95306a |
equipped to truly deal with historical dates prior to about 1600, and
|
|
Packit |
95306a |
between 1600 and 1900, the calendar varied from country to country.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
A second problem is that the Gregorian calendar is itself imperfect
|
|
Packit |
95306a |
and at some point may need to be corrected (though it's not clear that
|
|
Packit |
95306a |
this will happen... drift may now be accounted for using leap seconds
|
|
Packit |
95306a |
which means that the Gregorian calendar may be useful indefinitely).
|
|
Packit |
95306a |
No attempt is made to correct for the problems in the Gregorian
|
|
Packit |
95306a |
calendar for a couple reasons. First is that my great great great
|
|
Packit |
95306a |
grandchildren will be long dead before this begins to be a problem, so
|
|
Packit |
95306a |
it's not an immediate concern. Secondly, and even more importantly, I
|
|
Packit |
95306a |
don't know what the correction will be (if any) or when it will be
|
|
Packit |
95306a |
implemented, so I can safely ignore it.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
There is some limitation on how dates can be expressed such that
|
|
Packit |
95306a |
Date::Manip can handle them correctly. Date::Manip stores the year
|
|
Packit |
95306a |
internally as a 4-digit number. This is obviously not a limit due to
|
|
Packit |
95306a |
the Gregorian calendar, but I needed a way to store the dates
|
|
Packit |
95306a |
internally, and the 4-digit year was chosen. I realize that the
|
|
Packit |
95306a |
4-digit limitation does create a time when it will break (quite
|
|
Packit |
95306a |
similar to those who chose a 2-digit representation set themselves up
|
|
Packit |
95306a |
for the Y2K problem). Frankly, I'm not too concerned about this since
|
|
Packit |
95306a |
that date is 8000 years in the future! Date::Manip won't exist then.
|
|
Packit |
95306a |
Perl won't exist then. And it's quite possible that the Gregorian
|
|
Packit |
95306a |
calendar won't exist then. That's a much different situation than the
|
|
Packit |
95306a |
Y2K choice in which programmers chose a representation that would
|
|
Packit |
95306a |
break within the lifetime of the programs they were writing.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Given the 4-digit limitation, Date::Manip definitely can't handle BC
|
|
Packit |
95306a |
dates, or dates past Dec 31, 9999. So Date::Manip works (in theory)
|
|
Packit |
95306a |
during the period Jan 1, 0001 to Dec 31, 9999. There are a few
|
|
Packit |
95306a |
caveats:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Gregorian calendar issue>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In practical terms, Date::Manip deals with the Gregorian calendar, and
|
|
Packit |
95306a |
is most useful in the period that that calendar has been, or will be,
|
|
Packit |
95306a |
in effect. As explained above, the Gregorian calendar came into universal
|
|
Packit |
95306a |
acceptance in the early 1900's, and it should remain in use for the
|
|
Packit |
95306a |
foreseeable future.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
So... in practical terms, Date::Manip is probably useful from
|
|
Packit |
95306a |
around 1900 through several thousand years from now.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<First/last week>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In one part of the code (calculating week-of-year values), Date::Manip
|
|
Packit |
95306a |
references dates one week after and one week before the date actually
|
|
Packit |
95306a |
being worked on. As such, dates during the first week in the year 0001
|
|
Packit |
95306a |
fail (because a week before is in the year 1 BC), and those in the last
|
|
Packit |
95306a |
week in the year 9999 fail (because a week later is in 10,000).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
No effort will be made to correct this because the added functionality
|
|
Packit |
95306a |
is simply not that important (to me), especially since the Gregorian
|
|
Packit |
95306a |
calendar doesn't really apply in either instance. To be absolutely
|
|
Packit |
95306a |
safe, I will state that Date::Manip works as described in this manual
|
|
Packit |
95306a |
during the period Feb 1, 0001 to Nov 30, 9999, and I will only support
|
|
Packit |
95306a |
dates within that range (i.e. if you submit a bug using a date that is
|
|
Packit |
95306a |
not in that range, I will will consider myself free to ignore it).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Leap seconds>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip does NOT make use of the leap seconds in calculating time
|
|
Packit |
95306a |
intervals, so the difference between two times may not be strictly
|
|
Packit |
95306a |
accurate due to the addition of a leap second.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Three-digit years>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip will parse both 2- and 4-digit years, but it will NOT
|
|
Packit |
95306a |
handle 3 digit years. So, if you store the year as an offset from
|
|
Packit |
95306a |
1900 (which is 3 digits long as of the year 2000), these will NOT be
|
|
Packit |
95306a |
parseable by Date::Manip. Since the perl functions localtime and gmtime
|
|
Packit |
95306a |
DO return the year as an offset from 1900, the output from these will
|
|
Packit |
95306a |
need to be corrected (probably by adding 1900 to the result) before
|
|
Packit |
95306a |
they can be passed to any Date::Manip routine.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 FUTURE IDEAS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
A number of changes are being considered for future inclusion in
|
|
Packit |
95306a |
Date::Manip. As a rule, the changes listed below are not finalized,
|
|
Packit |
95306a |
and are open to discussion.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Rewrite parsing for better language support>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Currently, all of Date::Manip's parsing is based on English language
|
|
Packit |
95306a |
forms of dates, even if the words have been replaced by the equivalent
|
|
Packit |
95306a |
in some other language.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
I am considering rewriting the parsing routines in order to allow
|
|
Packit |
95306a |
date forms that might be used in other languages but do not have a
|
|
Packit |
95306a |
common English equivalent, and to account for the fact that some
|
|
Packit |
95306a |
English formats may not have an equivalent in another language.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Adding granularity>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The granularity of a time basically refers to how accurate you wish to
|
|
Packit |
95306a |
treat a date. For example, if you want to compare two dates to see if
|
|
Packit |
95306a |
they are identical at a granularity of days, then they only have to occur
|
|
Packit |
95306a |
on the same day. At a granularity of an hour, they have to occur within
|
|
Packit |
95306a |
an hour of each other, etc.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
I'm not sure how useful this would be, but it's one of the oldest
|
|
Packit |
95306a |
unimplemented ideas, so I'm not discarding it completely.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 ACKNOWLEDGMENTS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
There are many people who have contributed to Date::Manip over the
|
|
Packit |
95306a |
years that I'd like to thank. The most important contributions have
|
|
Packit |
95306a |
come in the form of suggestions and bug reports by users. I have
|
|
Packit |
95306a |
tried to include the name of every person who first suggested each
|
|
Packit |
95306a |
improvement or first reported each bug. These are included in the
|
|
Packit |
95306a |
L<Date::Manip::Changes5> and L<Date::Manip::Changes6> documents. The list
|
|
Packit |
95306a |
is simply too long to appear here, but I appreciate their help.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
A number of people have made suggestions or reported bugs which are
|
|
Packit |
95306a |
not mentioned in these documents. These include suggestions which
|
|
Packit |
95306a |
have not been implemented and people who have made a suggestion or bug
|
|
Packit |
95306a |
report which has already been suggested/reported by someone else. For
|
|
Packit |
95306a |
those who's suggestions have not yet been implemented, they will be
|
|
Packit |
95306a |
added to the appropriate Changes document when (if) their suggestions
|
|
Packit |
95306a |
are implemented. I keep every single suggestion I've ever received
|
|
Packit |
95306a |
and periodically review the unimplemented ones to see if it's
|
|
Packit |
95306a |
something I'm interested in, so even suggestions made years in the
|
|
Packit |
95306a |
past may still appear in future versions of Date::Manip, and the
|
|
Packit |
95306a |
original requester will be attributed at that point (some of the
|
|
Packit |
95306a |
changes made to Date::Manip 6.00 were based on suggestions 10 years
|
|
Packit |
95306a |
old which never fit in with version 5.xx, but which I knew I wanted to
|
|
Packit |
95306a |
implement). For those who have sent in requests/reports that had been
|
|
Packit |
95306a |
previously made by someone else, thank you too. I'd much rather have
|
|
Packit |
95306a |
a suggestion made twice than not at all.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Thanks to Alan Cezar and Greg Schiedler for paying me to implement the
|
|
Packit |
95306a |
Events_List routine. They gave me the idea, and were then willing to pay
|
|
Packit |
95306a |
me for my time to get it implemented quickly.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
I'd also like to thank a couple of authors. Date::Manip has gotten
|
|
Packit |
95306a |
some really good press in a couple of books. Since no one's paying me
|
|
Packit |
95306a |
to write Date::Manip, seeing my module get a good review in a book
|
|
Packit |
95306a |
written by someone else really makes my day. My thanks to Nate
|
|
Packit |
95306a |
Padwardhan and Clay Irving (Programming with Perl Modules -- part of
|
|
Packit |
95306a |
the O'Reilly Perl Resource Kit); and Tom Christiansen and Nathan
|
|
Packit |
95306a |
Torkington (The Perl Cookbook). Also, thanks to any other authors
|
|
Packit |
95306a |
who've written about Date::Manip who's books I haven't seen.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
I'd also like to thank the people who are maintaining the zoneinfo
|
|
Packit |
95306a |
database (and who replied quickly to several inquiries).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
I have borrowed from other modules. I originally borrowed the code for
|
|
Packit |
95306a |
determining if a year was a leap year from code written by David Muir
|
|
Packit |
95306a |
Sharnoff. I borrowed many of the original date printf formats from
|
|
Packit |
95306a |
code written by Terry McGonigal as well as the Solaris date command.
|
|
Packit |
95306a |
More recently, I borrowed the code to do time zone registry lookups on
|
|
Packit |
95306a |
Windows from the DateTime-TimeZone module, though I rewrote it to work
|
|
Packit |
95306a |
better with Date::Manip.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 BUGS AND QUESTIONS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Please refer to the L<Date::Manip::Problems> documentation for
|
|
Packit |
95306a |
information on submitting bug reports or questions to the author.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 SEE ALSO
|
|
Packit |
95306a |
|
|
Packit |
95306a |
L<Date::Manip> - main module documentation
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 LICENSE
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This script is free software; you can redistribute it and/or
|
|
Packit |
95306a |
modify it under the same terms as Perl itself.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 AUTHOR
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Sullivan Beck (sbeck@cpan.org)
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=cut
|