1Date::Manip::Misc(3)  User Contributed Perl Documentation Date::Manip::Misc(3)
2
3
4

NAME

6       Date::Manip::Misc - Miscellaneous information about Date::Manip
7

SHOULD I USE DATE::MANIP

9       If you look in CPAN, you'll find that there are a number of Date and
10       Time packages.  Is Date::Manip the one you should be using? That isn't
11       a trivial question to answer. It depends to a large extent on what you
12       are trying to do.
13
14       Date::Manip is certainly one of the most powerful of the Date modules
15       (the other main contender being the DateTime suite of modules).  I'm
16       trying to build a library which can do _EVERY_ conceivable date/time
17       manipulation that you'll run into in everyday life dealing with the
18       Gregorian calendar.  To the best of my knowledge, it will do everything
19       that any other date module will do which work with the Gregorian
20       calendar, and there are a number of features that Date::Manip has that
21       other modules do not have.
22
23       There is a tradeoff in being able to do "everything"... and that
24       tradeoff is primarily in terms of performance.  Date::Manip is written
25       entirely in Perl and is the largest of the date modules. Other modules
26       tend to be faster than Date::Manip, and modules written in C are
27       significantly faster than their Perl counterparts (at least if they're
28       done right).  Although I am working on making Date::Manip faster, it
29       will never be as fast as other modules.  And before anyone asks,
30       Date::Manip will never be translated to C (at least by me).  I write C
31       because I have to.  I write Perl because I like to.  Date::Manip is
32       something I do because it interests me, not something I'm paid for.
33
34       If you are going to be using the module in cases where performance is
35       an important factor, and you're doing a fairly small set of simple date
36       operations over and over again, you should carefully examine the other
37       date modules to see if they will meet your needs.
38
39       Date::Manip does NOT provide functionality for working with alternate
40       calendars such as the Chinese or Hebrew calendars, so if you need that
41       functionality, you definitely need to look elsewhere (the DateTime
42       suite probably).
43
44       On the other hand, if you want one solution for all your date needs,
45       don't need peak speed, or are trying to do more exotic date operations,
46       Date::Manip is for you.  Operations on things like business dates,
47       foreign language dates, holidays and other recurring events, complete
48       timezone handling, etc. are available more-or-less exclusively in
49       Date::Manip. At the very least, if you want to be able to do these
50       operations, it will require using several other modules, each with it's
51       own interface.  Also, when you work with Date::Manip, you work with one
52       author and one module.  The DateTime suite currently consists of almost
53       100 modules and 75 authors.
54
55       In addition, I am making significant performance improvements in
56       Date::Manip.  Although it will never be as fast as some of the other
57       perl modules, I believe that it is already competitive enough for most
58       purposes, and I continue to look for places where I can improve
59       performance, so performance should improve over time.
60

YEAR 2000 AND YEAR 2007 DST CHANGE

62       Did Date::Manip have any problems with Y2K compliance? Did it have any
63       problems with the revised daylight saving time changes made in 2007?
64
65       Although Date::Manip will parse many date strings (including dates with
66       2-digit years), internally they are stored as a 4 digit year, and all
67       operations are performed using this internal representation, so
68       Date::Manip had no problems with the Y2K issue. Of course, applications
69       written which stored the year as 2 digits (whether or not it used
70       Date::Manip) may have had problems, but they were not because of this
71       module.
72
73       Similarly for the 2007 changes in daylight saving time made in the
74       United States, Date::Manip was not affected. Date::Manip makes use of
75       the current time zone, but it gets that information from the operating
76       system the application is running on. If the operating system knows
77       about the new daylight saving time rules... so does Date::Manip.
78

WHAT DATES ARE DATE::MANIP USEFUL FOR?

80       Date::Manip applies to the Gregorian calendar. It does not support
81       alternative calendars (Hebrew, Mayan, etc.) so if you want to use an
82       alternative calendar, you'll need to look elsewhere.
83
84       The Gregorian calendar is a relatively recent innovation. Prior to it,
85       the Julian calendar was in use.  The Julian calendar defined leap years
86       as every 4th year.  This led to significant calendar drift over time
87       (since a year is NOT 365.25 days long). It was replaced by the
88       Gregorian calendar which improved the definition of leap years, and at
89       that point, the calendar was adjusted appropriately.
90
91       Date::Manip extrapolates the Gregorian calendar back to the year 0001
92       AD and forward to the year 9999 AD, but that does not necessarily mean
93       that the results are useful. As the world adopted the Gregorian
94       calendar, the dates using the Julian calendar had to be changed to fit
95       to account for the drift that had occurred. As such, the dates produced
96       by Date::Manip in an era where the Julian calendar was in use do not
97       accurately reflect the dates actually in use. In historical context,
98       the Julian calendar was in use until 1582 when the Gregorian calendar
99       was adopted by the Catholic church.  Protestant countries did not
100       accept it until later; Germany and Netherlands in 1698, British Empire
101       in 1752, Russia in 1918, etc. Date::Manip is therefore not equipped to
102       truly deal with historical dates prior to about 1600, and between 1600
103       and 1900, the calendar varied from country to country.
104
105       A second problem is that the Gregorian calendar is itself imperfect and
106       at some point may need to be corrected (though it's not clear that this
107       will happen... drift may now be accounted for using leap seconds which
108       means that the Gregorian calendar may be useful indefinitely).  No
109       attempt is made to correct for the problems in the Gregorian calendar
110       for a couple reasons. First is that my great great great grandchildren
111       will be long dead before this begins to be a problem, so it's not an
112       immediate concern.  Secondly, and even more importantly, I don't know
113       what the correction will be (if any) or when it will be implemented, so
114       I can safely ignore it.
115
116       There is some limitation on how dates can be expressed such that
117       Date::Manip can handle them correctly. Date::Manip stores the year
118       internally as a 4-digit number. This is obviously not a limit due to
119       the Gregorian calendar, but I needed a way to store the dates
120       internally, and the 4-digit year was chosen. I realize that the 4-digit
121       limitation does create a time when it will break (quite similar to
122       those who chose a 2-digit representation set themselves up for the Y2K
123       problem). Frankly, I'm not too concerned about this since that date is
124       8000 years in the future! Date::Manip won't exist then.  Perl won't
125       exist then. And it's quite possible that the Gregorian calendar won't
126       exist then. That's a much different situation than the Y2K choice in
127       which programmers chose a representation that would break within the
128       lifetime of the programs they were writing.
129
130       Given the 4-digit limitation, Date::Manip definitely can't handle BC
131       dates, or dates past Dec 31, 9999.  So Date::Manip works (in theory)
132       during the period Jan 1, 0001 to Dec 31, 9999. There are a few caveats:
133
134       Gregorian calendar issue
135           In practical terms, Date::Manip deals with the Gregorian calendar,
136           and is most useful in the period that that calendar has been, or
137           will be, in effect. As explained above, the Gregorian calendar came
138           into universal acceptance in the early 1900's, and it should remain
139           in use for the foreseeable future.
140
141           So...  in practical terms, Date::Manip is probably useful from
142           around 1900 through several thousand years from now.
143
144       First/last week
145           In one part of the code (calculating week-of-year values),
146           Date::Manip references dates one week after and one week before the
147           date actually being worked on. As such, dates during the first week
148           in the year 0001 fail (because a week before is in the year 1 BC),
149           and those in the last week in the year 9999 fail (because a week
150           later is in 10,000).
151
152           No effort will be made to correct this because the added
153           functionality is simply not that important (to me), especially
154           since the Gregorian calendar doesn't really apply in either
155           instance. To be absolutely safe, I will state that Date::Manip
156           works as described in this manual during the period Feb 1, 0001 to
157           Nov 30, 9999, and I will only support dates within that range (i.e.
158           if you submit a bug using a date that is not in that range, I will
159           will consider myself free to ignore it).
160
161       Leap seconds
162           Date::Manip does NOT make use of the leap seconds in calculating
163           time intervals, so the difference between two times may not be
164           strictly accurate due to the addition of a leap second.
165
166       Three-digit years
167           Date::Manip will parse both 2- and 4-digit years, but it will NOT
168           handle 3 digit years.  So, if you store the year as an offset from
169           1900 (which is 3 digits long as of the year 2000), these will NOT
170           be parseable by Date::Manip. Since the perl functions localtime and
171           gmtime DO return the year as an offset from 1900, the output from
172           these will need to be corrected (probably by adding 1900 to the
173           result) before they can be passed to any Date::Manip routine.
174

FUTURE IDEAS

176       A number of changes are being considered for future inclusion in
177       Date::Manip.  As a rule, the changes listed below are not finalized,
178       and are open to discussion.
179
180       Rewrite parsing for better language support
181           Currently, all of Date::Manip's parsing is based on English
182           language forms of dates, even if the words have been replaced by
183           the equivalent in some other language.
184
185           I am considering rewriting the parsing routines in order to allow
186           date forms that might be used in other languages but do not have a
187           common English equivalent, and to account for the fact that some
188           English formats may not have an equivalent in another language.
189
190       Adding granularity
191           The granularity of a time basically refers to how accurate you wish
192           to treat a date.  For example, if you want to compare two dates to
193           see if they are identical at a granularity of days, then they only
194           have to occur on the same day.  At a granularity of an hour, they
195           have to occur within an hour of each other, etc.
196
197           I'm not sure how useful this would be, but it's one of the oldest
198           unimplemented ideas, so I'm not discarding it completely.
199

ACKNOWLEDGMENTS

201       There are many people who have contributed to Date::Manip over the
202       years that I'd like to thank.  The most important contributions have
203       come in the form of suggestions and bug reports by users.  I have tried
204       to include the name of every person who first suggested each
205       improvement or first reported each bug.  These are included in the
206       Date::Manip::Changes5 and Date::Manip::Changes6 documents.  The list is
207       simply too long to appear here, but I appreciate their help.
208
209       A number of people have made suggestions or reported bugs which are not
210       mentioned in these documents.  These include suggestions which have not
211       been implemented and people who have made a suggestion or bug report
212       which has already been suggested/reported by someone else.  For those
213       who's suggestions have not yet been implemented, they will be added to
214       the appropriate Changes document when (if) their suggestions are
215       implemented.  I keep every single suggestion I've ever received and
216       periodically review the unimplemented ones to see if it's something I'm
217       interested in, so even suggestions made years in the past may still
218       appear in future versions of Date::Manip, and the original requester
219       will be attributed at that point (some of the changes made to
220       Date::Manip 6.00 were based on suggestions 10 years old which never fit
221       in with version 5.xx, but which I knew I wanted to implement). For
222       those who have sent in requests/reports that had been previously made
223       by someone else, thank you too.  I'd much rather have a suggestion made
224       twice than not at all.
225
226       Thanks to Alan Cezar and Greg Schiedler for paying me to implement the
227       Events_List routine.  They gave me the idea, and were then willing to
228       pay me for my time to get it implemented quickly.
229
230       I'd also like to thank a couple of authors.  Date::Manip has gotten
231       some really good press in a couple of books.  Since no one's paying me
232       to write Date::Manip, seeing my module get a good review in a book
233       written by someone else really makes my day.  My thanks to Nate
234       Padwardhan and Clay Irving (Programming with Perl Modules -- part of
235       the O'Reilly Perl Resource Kit); and Tom Christiansen and Nathan
236       Torkington (The Perl Cookbook).  Also, thanks to any other authors
237       who've written about Date::Manip who's books I haven't seen.
238
239       I'd also like to thank the people who are maintaining the zoneinfo
240       database (and who replied quickly to several inquiries).
241
242       I have borrowed from other modules. I originally borrowed the code for
243       determining if a year was a leap year from code written by David Muir
244       Sharnoff.  I borrowed many of the original date printf formats from
245       code written by Terry McGonigal as well as the Solaris date command.
246       More recently, I borrowed the code to do time zone registry lookups on
247       Windows from the DateTime-TimeZone module, though I rewrote it to work
248       better with Date::Manip.
249

BUGS AND QUESTIONS

251       Please refer to the Date::Manip::Problems documentation for information
252       on submitting bug reports or questions to the author.
253

SEE ALSO

255       Date::Manip        - main module documentation
256

LICENSE

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

AUTHOR

262       Sullivan Beck (sbeck@cpan.org)
263
264
265
266perl v5.36.0                      2022-12-10              Date::Manip::Misc(3)
Impressum