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 the most powerful of the Date modules. I'm
15 trying to build a library which can do _EVERY_ conceivable date/time
16 manipulation that you'll run into in everyday life dealing with the
17 Gregorian calendar. To the best of my knowledge, it will do everything
18 that any other date module will do which work with the Gregorian
19 calendar (Date::Manip does NOT provide functionality for working with
20 alternate calendars such as the Chinese or Hebrew calendars, so if you
21 need that functionality, you definitely need to look elsewhere). There
22 are a number of features that Date::Manip has that none of the other
23 modules have. Date::Manip is the "Swiss Army Knife" of Date modules.
24 There is a tradeoff in being able to do "everything"... and that
26 tradeoff is primarily in terms of performance. Date::Manip is written
27 entirely in Perl and is the largest of the date modules. Other modules
28 tend to be faster than Date::Manip, and modules written in C are
29 significantly faster than their Perl counterparts (at least if they're
30 done right). Although I am working on making Date::Manip faster, it
31 will never be as fast as other modules. And before anyone asks,
32 Date::Manip will never be translated to C (at least by me). I write C
33 because I have to. I write Perl because I like to. Date::Manip is
34 something I do because it interests me, not something I'm paid for.
35 If you are going to be using the module in cases where performance is
37 an important factor, and you're doing a fairly small set of simple date
38 operations over and over again, you should carefully examine the other
39 date modules to see if they will meet your needs.
40 On the other hand, if you want one solution for all your date needs,
42 don't need peak speed, or are trying to do more exotic date operations,
43 Date::Manip is for you. Operations on things like business dates,
44 foreign language dates, holidays and other recurring events, complete
45 timezone handling, etc. are available more-or-less exclusively in
46 Date::Manip. At the very least, if you want to be able to do these
47 operations, it will require using several other modules, each with it's
48 own interface.
49 In addition, I am making significant performance improvements in
51 Date::Manip. Although it will never be as fast as some of the other
52 perl modules, I believe that it is already competitive enough for most
53 purposes, and I continue to look for places where I can improve
54 performance, so performance should improve over time.
55
57 Did Date::Manip have any problems with Y2K compliance? Did it have any
58 problems with the revised daylight savings time changes made in 2007?
59 Date::Manip is basically just a parser. You give it a date and it'll
61 manipulate it. Date::Manip does store the date internally as a 4 digit
62 year, and performs all operations using this internal representation,
63 so Date::Manip had no problems with the Y2K issue. Of course,
64 applications written which stored the year as 2 digits (whether or not
65 it used Date::Manip) may have had problems, but they were not because
66 of this module.
67 Similarly for the 2007 changes in daylight savings time made in the
69 United States, Date::Manip was not affected. Date::Manip makes use of
70 the current time zone, but it gets that information from the operating
71 system the application is running on. If the operating system knows
72 about the new daylight saving time rules... so does Date::Manip.
73
75 Date::Manip applies to the Gregorian calendar. It does not support
76 alternative calendars (Hebrew, Mayan, etc.) so if you want to use an
77 alternative calendar, you'll need to look elsewhere.
78 The Gregorian calendar is a relatively recent innovation. Prior to it,
80 the Julian calendar was in use. The Julian calendar defined leap years
81 as every 4th year. This led to significant calendar drift over time
82 (since a year is NOT 365.24 days long). It was replaced by the
83 Gregorian calendar which improved the definition of leap years, and at
84 that point, the calendar was adjusted appropriately.
85 Date::Manip extrapolates the Gregorian calendar back to the year 0001
87 AD and forward to the year 9999 AD, but that does not necessarily mean
88 that the results are useful. As the world adopted the Gregorian
89 calendar, the dates using the Julian calendar had to be changed to fit
90 to account for the drift that had occurred. As such, the dates produced
91 by Date::Manip in an era where the Julian calendar was in use do not
92 accurately reflect the dates actually in use. In historical context,
93 the Julian calendar was in use until 1582 when the Gregorian calendar
94 was adopted by the Catholic church. Protestant countries did not
95 accept it until later; Germany and Netherlands in 1698, British Empire
96 in 1752, Russia in 1918, etc. Date::Manip is therefore not equipped to
97 truly deal with historical dates prior to about 1600, and between 1600
98 and 1900, the calendar varied from country to country.
99 A second problem is that the Gregorian calendar is itself imperfect and
101 at some point may need to be corrected (though it's not clear that this
102 will happen... drift may now be accounted for using leap seconds which
103 means that the Gregorian calendar may be useful indefinitely). No
104 attempt is made to correct for the problems in the Gregorian calendar
105 for a couple reasons. First is that my great great great grandchildren
106 will be long dead before this begins to be a problem, so it's not an
107 immediate concern. Secondly, and even more importantly, I don't know
108 what the correction will be (if any) or when it will be implemented, so
109 I can safely ignore it.
110 There is some limitation on how dates can be expressed such that
112 Date::Manip can handle them correctly. Date::Manip stores the year
113 internally as a 4-digit number. This is obviously not a limit due to
114 the Gregorian calendar, but I needed a way to store the dates
115 internally, and the 4-digit year was chosen. I realize that the 4-digit
116 limitation does create a time when it will break (quite similar to
117 those who chose a 2-digit representation set themselves up for the Y2K
118 problem). Frankly, I'm not too concerned about this since that date is
119 8000 years in the future! Date::Manip won't exist then. Perl won't
120 exist then. And it's quite possible that the Gregorian calendar won't
121 exist then. That's a much different situation than the Y2K choice in
122 which programmers chose a representation that would break within the
123 lifetime of the programs they were writing.
124 Given the 4-digit limitation, Date::Manip definitely can't handle BC
126 dates, or dates past Dec 31, 9999. So Date::Manip works (in theory)
127 during the period Jan 1, 0001 to Dec 31, 9999. There are a few caveats:
128 Gregorian calendar issue
130 In practical terms, Date::Manip deals with the Gregorian calendar,
131 and is most useful in the period that that calendar has been, or
132 will be, in effect. As explained above, the Gregorian calendar came
133 into universal acceptance in the early 1900's, and it should remain
134 in use for the foreseeable future.
135 So... in practical terms, Date::Manip is probably useful from
137 around 1900 through several thousand years from now.
138 First/last week
140 In one part of the code (calculating week-of-year values),
141 Date::Manip references dates one week after and one week before the
142 date actually being worked on. As such, the first week in the year
143 0001 fail (because a week before is in the year 1 BC), and the last
144 week in the year 9999 fail (because a week later is in 10,000).
145 No effort will be made to correct this because the added
147 functionality is simply not that important (to me), especially
148 since the Gregorian calendar doesn't really apply in either
149 instance. To be absolutely safe, I will state that Date::Manip
150 works as described in this manual during the period Feb 1, 0001 to
151 Nov 30, 9999, and I will only support dates within that range (i.e.
152 if you submit a bug using a date that is not in that range, I will
153 will consider myself free to ignore it).
154 Leap seconds
156 Date::Manip does NOT make use of the leap seconds in calculating
157 time intervals, so the difference between two times may not be
158 strictly accurate due to the addition of a leap second.
159 Three-digit years
161 Date::Manip will parse both 2- and 4-digit years, but it will NOT
162 handle 3 digit years. So, if you store the year as an offset from
163 1900 (which is 3 digits long as of the year 2000), these will NOT
164 be parseable by Date::Manip. Since the perl functions localtime and
165 gmtime DO return the year as an offset from 1900, the output from
166 these will need to be corrected (probably by adding 1900 to the
167 result) before they can be passed to any Date::Manip routine.
168
170 A note about version numbers.
171 Prior to version 5.00, Date::Manip was distributed as a perl4 library.
173 There were no numbering conventions in place, so I used a simple
174 MAJOR.MINOR numbering scheme.
175 With version 5.00, I switched to a perl5 module and at that time
177 switched to the perl5 numbering convention of a major version followed
178 by a 2 digit minor version.
179 As of 5.41/5.42, all versions released to CPAN were even numbered. Odd
181 numbered were development versions available from my web site. For
182 example, after 5.40 was released, I started making changes, and called
183 the development version 5.41. When released to CPAN, it was called
184 5.42.
185 As of 5.55/6.00, I'm abandoning the even/odd behavior started in 5.41.
187 Every release meant changing the version number twice. I had to change
188 it from the odd (development version) to the even (release version).
189 Then I had to package it up. Then I had to change it to the next odd
190 (development version). It's more error prone, and more of a nuisance,
191 and I've seen no benefit from it.
192
194 A number of changes are being considered for future inclusion in
195 Date::Manip. As a rule, the changes listed below are not finalized,
196 and are open to discussion.
197 Rewrite parsing for better language support
199 Currently, all of Date::Manip's parsing is based on English
200 language forms of dates, even if the words have been replaced by
201 the equivalent in some other language.
202 I am considering rewriting the parsing routines in order to allow
204 date forms that might be used in other languages but do not have a
205 common English equivalent, and to account for the fact that some
206 English formats may not have an equivalent in another language.
207 Making the primary interface OO
209 Currently, the Date::Manip module is the original functional
210 interface (though it now uses all of the OO modules to do the
211 actual work).
212 I am considering writing a primary OO interface. In this case, the
214 functional interface will still be available, perhaps as
215 Date::Manip::Compat.
216 When (and if) I do this, it will be in a new major-number release
218 (i.e. Date::Manip 7.00 or higher).
219 I keep going back and forth on whether this would be useful, so at
221 this point, there is no definite plan to make this change.
222 Adding granularity
224 The granularity of a time basically refers to how accurate you wish
225 to treat a date. For example, if you want to compare two dates to
226 see if they are identical at a granularity of days, then they only
227 have to occur on the same day. At a granularity of an hour, they
228 have to occur within an hour of each other, etc.
229 I'm not sure how useful this would be, but it's one of the oldest
231 unimplemented ideas, so I'm not discarding it completely.
232
234 There are many people who have contributed to Date::Manip over the
235 years that I'd like to thank. The most important contributions have
236 come in the form of suggestions and bug reports by users. I have tried
237 to include the name of every person who first suggested each
238 improvement or first reported each bug. These are included in the
239 HISTORY file in the Date::Manip distribution in the order the changes
240 are made. The list is simply too long to appear here, but I appreciate
241 their help.
242 A number of people have made suggestions or reported bugs which are not
244 mentioned in the HISTORY file. These include suggestions which have
245 not been implemented and people who have made a suggestion or bug
246 report which has already been suggested/reported by someone else. For
247 those who's suggestions have not yet been implemented, they will be
248 added to the HISTORY file when (if) their suggestions are implemented.
249 I keep every single suggestion I've ever received and periodically
250 review the unimplemented ones to see if it's something I'm interested
251 in, so even suggestions made years in the past may still appear in
252 future versions of Date::Manip, and the original requester will be
253 attributed at that point. For those who have sent in requests/reports
254 that had been previously made by someone else, thank you too. I'd much
255 rather have a suggestion made twice than not at all.
256 Thanks to Alan Cezar and Greg Schiedler for paying me to implement the
258 Events_List routine. They gave me the idea, and were then willing to
259 pay me for my time to get it implemented quickly.
260 I'd also like to thank a couple of authors. Date::Manip has gotten
262 some really good press in a couple of books. Since no one's paying me
263 to write Date::Manip, seeing my module get a good review in a book
264 written by someone else really makes my day. My thanks to Nate
265 Padwardhan and Clay Irving (Programming with Perl Modules -- part of
266 the O'Reilly Perl Resource Kit); and Tom Christiansen and Nathan
267 Torkington (The Perl Cookbook). Also, thanks to any other authors
268 who've written about Date::Manip who's books I haven't seen.
269 I'd also like to thank the people who are maintaining the zoneinfo
271 database (and who replied quickly to several inquiries).
272 I have borrowed from other modules. I originally borrowed the code for
274 determining if a year was a leap year from code written by David Muir
275 Sharnoff. I borrowed many of the original date printf formats from
276 code written by Terry McGonigal as well as the Solaris date command.
277 More recently, I borrowed the code to do time zone registry lookups on
278 Windows from the DateTime-TimeZone module, though I rewrote it to work
279 better with Date::Manip.
280
282 Please refer to the Date::Manip::Problems documentation for information
283 on submitting bug reports or questions to the author.
284
286 Date::Manip - main module documentation
287
289 This script is free software; you can redistribute it and/or modify it
290 under the same terms as Perl itself.
291
293 Sullivan Beck (sbeck@cpan.org)
294perl v5.12.0 2010-04-27 Date::Manip::Misc(3)