1Date::Manip::Problems(3U)ser Contributed Perl DocumentatiDoante::Manip::Problems(3)
2
6 Date::Manip::Problems - problems and bugs
7
9 The following are not bugs in Date::Manip, but they may give some
10 people problems.
11 Memory leak
13 There is a known memory leak in perl related to named regexp
14 captures that directly affects Date::Manip . The leak is in all
15 versions of perl that I have tested starting at 5.10. I have
16 submitted a bug report (perlbug #78266). Until perl is fixed, if
17 you need to use Date::Manip in a persistent environment, you should
18 be aware of this.
19 Date::Manip 5.xx is not susceptible, so using it may be a feasible
21 workaround, but if you need accurate timezone handling, this isn't
22 possible.
23 The leak is fairly small. A crude estimate is 3 MB per 10,000 dates
25 parsed, so unless you're parsing hundreds of thousands, or millions
26 of dates, the leak probably won't be a problem. And if you're
27 parsing that many dates, the relatively slow Date::Manip may not be
28 the correct module for you to use anyway.
29 Unable to determine Time Zone
31 Please refer to the Date::Manip::TZ documentation for a discussion
32 of this problem.
33 Calculations appear to be off by an hour
35 Within days of releasing 6.00, I got the following report:
36 print DateCalc(ParseDate("2009/10/31"), "+1 day"), "\n";
38 print DateCalc(ParseDate("2009/11/01"), "+1 day"), "\n";
39 print DateCalc(ParseDate("2009/11/02"), "+1 day"), "\n";
40 produced:
42 2009110100:00:00
44 2009110123:00:00
45 2009110300:00:00
46 In other words, the second calculation appears to be off by one
48 hour. In actuality, the result is correct. In the user's time
49 zone, daylight saving time ended on Nov 1, and since "+ 1 day" is
50 equivalent to "+ 24 hours", the results are correct. In
51 America/New_York time (which has the same result), the calculation
52 means that:
53 2009-11-01 00:00:00 EDT + 24 hours =
55 2009-11-01 23:00:00 EST
56 which is correct.
58 Missing date formats
60 Due to the large number of date formats that Date::Manip CAN
61 process, people often assume that other formats that they want to
62 use should work as well, and when they don't, it comes as a
63 surprise.
64 With the much improved parsing of 6.00, many formats can be added
66 easily, though unless they are of general use, I'll probably
67 suggest that you use parse_format instead.
68 There is a class of formats that I will not add however.
70 I have frequently been asked to add formats such as "the 15th of
72 last month", or "Monday of next week". I will NOT add these date
73 formats to Date::Manip. Since I have received the request several
74 times, I decided to include my reasoning here.
75 Date::Manip can parse pretty much any static date format that I
77 could think of or find reference to. Dates such as "today", "Jan
78 12", or "2001-01-01" are all understood.
79 These are fairly limited however. Many very common date formats are
81 best thought of as a date plus a modification. For example,
82 "yesterday" is actually determined internally as "today" plus a
83 modification of "- 1 day". "2nd Sunday in June" is determined as
84 "June 1" modified to the 2nd Sunday.
85 As these types of formats were added over time, I quickly realized
87 that the number of possible date plus modification formats was
88 huge. The number of combinations has caused the parsing in
89 Date::Manip to be quite complex, and adding new formats
90 occasionally causes unexpected conflicts with other formats.
91 The first time I received a request similar to "the 15th of last
93 month", I intended to add it, but as I analyzed it to see what
94 changes needed to be made to support it, I realized that this
95 needed to be expressed as a date plus TWO modifications. In other
96 words, today modified to last month modified to the 15th day of the
97 month.
98 As bad as date plus modification formats are, a date plus TWO
100 modifications would be exponentially worse. On realizing that, I
101 made a firm decision that Date::Manip will NOT support this type of
102 format now, or at any time in the future. Although I apologize for
103 the inconvenience, I do not intend to change my position on this.
104 Date::Manip is slow
106 NOTE: The following section applies primarily to 5.xx. I'm doing a
107 lot of work to optimize Date::Manip and I will rewrite this section
108 to take this into account, and to provide performance suggestions.
109 It should be noted that initial tests show version 6.xx to be
110 around twice as fast as 5.xx (though still considerably slower than
111 some of the other modules).
112 Date::Manip is probably one of the slower Date/Time modules due to
114 the fact that it is huge and written entirely in perl.
115 Some things that will definitely help:
117 ISO-8601 dates are parsed first and fastest. Use them whenever
119 possible.
120 Avoid parsing dates that are referenced against the current time
122 (in 2 days, today at noon, etc.). These take a lot longer to
123 parse.
124 Business date calculations are extremely slow. You should consider
126 alternatives if possible (i.e. doing the calculation in exact mode
127 and then multiplying by 5/7). Who needs a business date more
128 accurate than "6 to 8 weeks" anyway, right :-)
129 RCS Control
131 If you try to put Date::Manip under RCS control, you are going to
132 have problems. Apparently, RCS replaces strings of the form
133 "$Date...$" with the current date. This form occurs all over in
134 Date::Manip. To prevent the RCS keyword expansion, checkout files
135 using:
136 co -ko
138 Since very few people will ever have a desire to do this (and I
140 don't use RCS), I have not worried about it, and I do not intend to
141 try to workaround this problem.
142 Using functions/methods which are not supported
144 There have been a handful of incidents of people using a function
145 from Date::Manip which were not documented in the manual.
146 Date::Manip consists of a large number of user functions which are
148 documented in the manual. These are designed to be used by other
149 programmers, and I will not make any backwards incompatible changes
150 in them unless there is a very compelling reason to do so, and in
151 that case, the change will be clearly documented in the
152 Date::Manip::Changes6 documentation for this module.
153 Date::Manip also includes a large number of functions which are NOT
155 documented. These are for internal use only. Please do not use
156 them! I can (and do) change their use, and even their name,
157 without notice, and without apology! Some of these internal
158 functions even have test scripts, but that is not a guarantee that
159 they will not change, nor is any support implied. I simply like to
160 run regression tests on as much of Date::Manip as possible.
161 As of the most recent versions of Date::Manip, all internal
163 functions have names that begin with an underscore (_). If you
164 choose to use them directly, it is quite possible that new versions
165 of Date::Manip will cause your programs to break due to a change in
166 how those functions work.
167 Any changes to internal functions will not be documented, and will
169 not be regarded by me as a backwards incompatibility. Nor will I
170 (as was requested in one instance) revert to a previous version of
171 the internal function.
172 If you feel that an internal function is of more general use, feel
174 free to contact me with an argument of why it should be "promoted".
175 I welcome suggestions and will definitely consider any such
176 request.
177
179 Date::Manip 6.xx has gotten some complaints (far more than 5.xx if the
180 truth be told), so I'd like to address a couple of them here. Perhaps
181 an understanding of why some of the changes were made will allay some
182 of the complaints. If not, people are always welcome to stick with the
183 5.xx release. I will continue to support the 5.xx releases for a couple
184 years (though I do NOT plan to add functionality to it).
185 These complaints come both from both the CPAN ratings site:
187 http://cpanratings.perl.org/dist/Date-Manip
189 and from personal email.
191 Requires perl 5.10
193 The single most controversial change made in 6.00 is that it now
194 required perl 5.10.0 or higher. Most of the negative feedback I've
195 received is due to this.
196 In the past, I've avoided using new features of perl in order to
198 allow Date::Manip to run on older versions of perl. Prior to perl
199 5.10, none of the new features would have had a major impact on how
200 Date::Manip was written, however that changed in 5.10.
201 One of the aspects of Date::Manip that has received the most
203 positive response is the ability to parse almost every conceivable
204 date format. Unfortunately, as I've added formats, the parsing
205 routine became more and more complicated, and maintaining it was
206 one of the least enjoyable aspect in maintaining Date::Manip . For
207 several years, I've been extremely reluctant to add new formats due
208 to the fact that too often, adding a new format broke other
209 formats.
210 As I was rewriting Date::Manip, I was looking for ways to improve
212 the parsing and to make maintaining it easier. Perl 5.10 provides
213 the feature "named capture buffers". Named capture buffers not only
214 improves the ease of maintaining the complex regular expressions
215 used by Date::Manip, it makes it dramatically easier to add
216 additional formats in a way that is much less likely to interfere
217 with other formats. The parsing in 6.00 is so much more robust,
218 extensible, and flexible, that it will make parser maintenance
219 possible for many years to come at a fraction of the effort and
220 risk.
221 It was too much to turn down. Hopefully, since 5.10 has been out
223 for some time now, this will not prohibit too many people from
224 using the new version of Date::Manip. I realize that there are many
225 people out there using older versions of perl who do not have the
226 option of upgrading perl. The decision to use 5.10 wasn't made
227 lightly... but I don't regret making it. I apologize to users who,
228 as a result, cannot use 6.00 . Hopefully in the future you'll be
229 able to benefit from the improvements in 6.00.
230 One complaint I've received is that this in some way makes
232 Date::Manip backwards incompatible, but this is not an accurate
233 complaint. Version 6.xx DOES include some backwards
234 incompatibilities (and these are covered in the
235 Date::Manip::Migration5to6 document), however in almost all cases,
236 these incompatibilities are with infrequently used features, or
237 workarounds are in place to allow deprecated features to continue
238 functioning for some period of time.
239 Though I have no data to confirm this, I suspect that 90% or more
241 of all scripts which were written with Date::Manip 5.xx will
242 continue to work unmodified with 6.xx (of course, you should still
243 refer to the migration document to see what features are deprecated
244 or changed to make sure that you don't need to modify your script
245 so that it will continue to work in the future). Even with scripts
246 that need to be changed, those changes should be trivial.
247 So, Date::Manip 6.xx is almost entirely backward compatible with
249 5.xx (to the extent that you would expect any major version release
250 to be compatible with a previous major version).
251 The change is only in the requirements necessary to get Date::Manip
253 6.xx to run.
254 Obviously, it's not reasonable to say that Date::Manip should never
256 be allowed to switch minimum perl versions. At some point, you have
257 to let go of an old version if you want to make use of the features
258 of the newer version. The question is, did I jump to 5.10 too fast?
259 The complaints I see on the CPAN ratings complain that I no longer
261 support perl 5.6 and perl 5.8.
262 With respect to 5.6, perl 5.6 was released in March of 2000 (that's
264 before Windows XP which was released in 2001). To be honest, I
265 don't really feel much sympathy for this complaint. Software that
266 is 9 years old is ANCIENT. People may choose to use it... but
267 please don't complain when new software comes out that doesn't
268 support it.
269 The argument for perl 5.8 is much more compelling. Although 5.8 was
271 released quite some time ago (July of 2002), there were no major
272 perl releases until 5.10 came out in December of 2007, so 5.8 was
273 state-of-the art as little as 2 years prior to the release of
274 Date::Manip 6.xx.
275 I agree completely with the argument that abandoning 5.8 only 2
277 years after it was the current version is too soon. For that
278 reason, I will continue to support the Date::Manip 5.xx releases
279 for some years to come. I don't know exactly how long I'll continue
280 to support them, but it'll be at least 2-3 years. Once perl 5.10 is
281 5 years old, I'll be much more likely to drop support for the 5.xx
282 releases, but I DO want to make use of the features of 5.10 for
283 future development. They make development so much easier, and the
284 parsing so much more robust (something I've wanted for years), that
285 I'm not willing to give up the advantages of 5.10.
286 But the next complaint is relevant.
288 Automatic installs break
290 A more important problem is that versions 6.01 through 6.07 broke
291 automatic installs for older perl installations. If you try to
292 install Date::Manip using the automatic tools (cpan/cpanp), they
293 will look for the most recent version. If you are using a version
294 of perl older than 5.10, this fails, and rather than looking for an
295 older version, the tool simply reports a failure in installing
296 Date::Manip. Technically, the problem is not due to Date::Manip
297 itself, but is a result of how perl modules are currently managed.
298 However, since Date::Manip is managed by then, it's important to
299 avoid causing this type of problem (which I clearly failed to do).
300 As of Date::Manip 6.10, this problem should no longer occur.
302 Starting with version 6.10, both the 5.xx and 6.xx versions of
303 Date::Manip have been combined into a single distribution (so
304 Date-Manip-6.10 contained both Date::Manip 6.10 and Date::Manip
305 5.57). From Date::Manip 6.10 to 6.13, the perl version was
306 determined at install time and either the 5.xx or 6.xx version was
307 installed. From Date::Manip 6.14 on, both versions are installed,
308 and at run time, the correct version will be chosen (and if you're
309 running a recent version of perl, you can select to run the old or
310 new version).
311 All future version (for as long as 5.xx is supported) will include
313 both the most current 5.xx and 6.xx releases of Date::Manip. In
314 this way, automatic install tools will be able to install
315 Date::Manip regardless of which version of perl you are running.
316 Too many modules
318 One minor complaint is that there are too many files. One person
319 specifically objects to the fact that there are over 470 modules
320 covering non-minute offsets. This complaint is (IMO) absurd.
321 Date::Manip supports ALL historical time zones, including those
322 with non-minute offsets, and so there will be information for those
323 time zones, even though they are not currently in use.
324 I could of course store all of the information in one big module,
326 but that means that you have to load all of that data every time
327 you use Date::Manip, and I find that to be a very poor solution.
328 Instead, storing the information in a per-time zone and per-offset
329 manner dramatically decreases the amount of data that has to be
330 loaded.
331 While it is true that Date::Manip includes over 900 modules for all
333 of the time zone information, most implementations of time zone
334 handling also choose to break up the data into a large number of
335 files.
336 My linux distribution (openSuSE 11.2 at the time of writing this)
338 uses the standard zoneinfo database, and at this point, there are
339 over 1700 files included in /usr/share/zoneinfo (though it does
340 appear that there is some duplication of information). Current
341 versions of RedHat also use over 1700 files, so Date::Manip isn't
342 treating the time zone problem in a new or unreasonable way.
343 Objects are large
345 One complaint that was put on the CPAN ratings site was that the OO
346 interface is "a dud" due to the size of it's objects. The complaint
347 is that a Date::Manip::Date object is 115K while it should
348 (according to the complaint) only require that you need to save the
349 seconds from the epoch, zone, and a couple other pieces of
350 information, all of which could probably be stored in 100 bytes or
351 less.
352 Date::Manip is very configurable, and contains a great deal of
354 information which could theoretically be calculated on the fly, but
355 which would greatly reduce it's performance. Instead, the data is
356 cached, and since the data is virtually all potentially object
357 specific, it has to be somehow linked to the object.
358 For example, Date::Manip allows you to parse dates in several
360 languages. Each language has a large number of regular expressions
361 which are used to to the actual parsing. Instead of recreating
362 these regular expressions each time they are needed, they are
363 created once and stored in an object (specifically, a
364 Date::Manip::Base object).
365 Similarly, a description of the time zones are stored in a second
367 object (a Date::Manip::TZ object).
368 The size of the Date::Manip::Base object is almost 15K. The size of
370 the Date::Manip::TZ object is 100K. That may seem excessive, but
371 you have to remember that there are almost 500 time zones, and they
372 have to be indexed by name, alias, abbreviation, and offset, and by
373 the time you do this, it does take a fair bit of space. The size
374 of the actual Date::Manip::Date object is a little over 300 bytes.
375 Both the Date::Manip::Base and Date::Manip::TZ objects are reused
377 by any number of Date::Manip::Date objects. They can almost be
378 thought of as global data, except that they are accessible in the
379 standard OO manner, and you are allowed to modify them on a per-
380 object basis which WILL mean that you have to store more data. If
381 you work with multiple configurations (see Date::Manip::Config),
382 you'll need multiple Base and TZ objects. However, most of the time
383 you will not need to do this.
384 The Date::Manip::Date object is a bit larger than suggested in the
386 complaint, but it should be noted that Date::Manip actually stores
387 the dates in a number of different formats (a string of the form
388 YYYYMMDDHH:MN:SS and a list [YYYY,MM,DD,HH,MN,SS] in the time zone
389 it was parsed in, the local time zone (if different) and GMT. By
390 caching this information as it is used, it has a huge impact on the
391 performance.
392 So, Date::Manip in typical usage consists of one 100K
394 Date::Manip::TZ object, one 15K Date::Manip::Base objects, and any
395 number of small 300 byte Date::Manip::Date objects.
396 Date::Manip::Delta objects are even smaller. Date::Manip::Recur
397 objects are also small, but they contain any number of Date objects
398 in them.
399 I am certainly open to suggestions as to how I can improve the OO
401 interface... but I don't believe it is a dud. While I'm not an
402 expert at OO programming, I believe that I followed pretty standard
403 and accepted procedures for accessing the data.
404 Please refer to the Date::Manip::Objects document for more
406 information.
407 Date::Manip has an inconsistent interface
409 I've gotten a few complaints that the interface to Date::Manip is
410 inconsistent... and I agree (at least when using the functional
411 interfaces).
412 Date::Manip was originally written in an unplanned way... as a
414 need/want came up, it was extended. That's not the way to write a
415 major package of course, but it wasn't expected to be a major
416 package at the start.
417 As it became more and more widely used, I too wished for a more
419 consistent interface, but I did not want to break backward
420 compatibility for everyone using it.
421 When 6.xx was written, I spent a good deal of time trying to make a
423 very standard interface, so I do not believe that this complaint
424 can be applied to the OO interface (though I'm interested in
425 suggestions for improving it of course).
426 As far as the functional interface goes, I'll continue to support
428 it in a backward compatible (and therefore inconsistent) form. I'd
429 encourage the use of the OO interface whenever possible.
430
432 If you find a bug in Date::Manip, please send it directly to me (see
433 the AUTHOR section below). Alternately, you can submit it on CPAN.
434 This can be done at the following URL:
435 http://rt.cpan.org/Public/Dist/Display.html?Name=Date-Manip
437 Please do not use other means to report bugs (such as Usenet
439 newsgroups, or forums for a specific OS or Linux distribution) as it is
440 impossible for me to keep up with all of them.
441 When filing a bug report, please include the following information:
443 Date::Manip version
445 Please include the version of Date::Manip you are using. You can
446 get this by using the script:
447 use Date::Manip;
449 print DateManipVersion(1),"\n";
450 or
452 use Date::Manip::Date;
454 $obj = new Date::Manip::Date;
455 print $obj->version(1),"\n";
456 Perl information
458 Please include the output from "perl -V"
459 If you have a problem using Date::Manip that perhaps isn't a bug (can't
461 figure out the syntax, etc.), you're in the right place. Start by
462 reading the main Date::Manip documentation, and the other documents
463 that apply to whatever you are trying to do. If this still doesn't
464 answer your question, mail me directly.
465 I would ask that you be reasonably familiar with the documentation
467 BEFORE you choose to do this. Date::Manip is a hobby, and I simply do
468 not have time to respond to hundreds of questions which are already
469 answered in this manual.
470 If you find any problems with the documentation (errors, typos, or
472 items that are not clear), please send them to me. I welcome any
473 suggestions that will allow me to improve the documentation.
474
476 None known.
477
479 Date::Manip - main module documentation
480
482 This script is free software; you can redistribute it and/or modify it
483 under the same terms as Perl itself.
484
486 Sullivan Beck (sbeck@cpan.org)
487perl v5.10.1 2011-12-07 Date::Manip::Problems(3)