1Date::Manip::Misc(3) User Contributed Perl Documentation Date::Manip::Misc(3)
2
6 Date::Manip::Misc - Miscellaneous information about Date::Manip
7
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 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 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 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 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 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 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
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 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 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
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 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 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 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 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 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 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 So... in practical terms, Date::Manip is probably useful from
142 around 1900 through several thousand years from now.
143 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 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 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 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
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 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 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 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 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
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 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 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 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 I'd also like to thank the people who are maintaining the zoneinfo
240 database (and who replied quickly to several inquiries).
241 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
251 Please refer to the Date::Manip::Problems documentation for information
252 on submitting bug reports or questions to the author.
253
255 Date::Manip - main module documentation
256
258 This script is free software; you can redistribute it and/or modify it
259 under the same terms as Perl itself.
260
262 Sullivan Beck (sbeck@cpan.org)
263perl v5.36.0 2022-12-10 Date::Manip::Misc(3)