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 Unable to determine Time Zone
13 If you ever get the message that Date::Manip was unable to
14 determine the timezone, you need to provide that information to
15 your script. Please refer to the Date::Manip::TZ documentation for
16 a discussion of this problem.
17 Calculations appear to be off by an hour
19 Due to daylight saving time (especially the spring change where the
20 time typically moves forward from 02:00 to 03:00), any date
21 calculation which would intuitively report a time in that range
22 will also move forward (or backward as the case may be).
23 *NOTE* This should be less of a problem since 6.30 with the
25 addition of semi-exact deltas.
26 Missing date formats
28 Due to the large number of date formats that Date::Manip CAN
29 process, people often assume that other formats that they want to
30 use should work as well, and when they don't, it comes as a
31 surprise.
32 With the much improved parsing of 6.00, many formats can be added
34 easily, though unless they are of general use, I'll probably
35 suggest that you use parse_format instead.
36 There is a class of formats that I do not plan to add however.
38 I have frequently been asked to add formats such as "the 15th of
40 last month", or "Monday of next week". I do not intend to add these
41 date formats to Date::Manip, but since I have received the request
42 several times, I decided to include my reasoning here.
43 Date::Manip can parse pretty much any static date format that I
45 could think of or find reference to. Dates such as "today", "Jan
46 12", or "2001-01-01" are all understood.
47 These are fairly limited however. Many very common date formats are
49 best thought of as a date plus a modification. For example,
50 "yesterday" is actually determined internally as "today" plus a
51 modification of "- 1 day". "2nd Sunday in June" is determined as
52 "June 1" modified to the 2nd Sunday.
53 As these types of formats were added over time, I quickly realized
55 that the number of possible date plus modification formats was
56 huge. The number of combinations has caused the parsing in
57 Date::Manip to be quite complex, and adding new formats
58 occasionally causes unexpected conflicts with other formats.
59 The first time I received a request similar to "the 15th of last
61 month", I intended to add it, but as I analyzed it to see what
62 changes needed to be made to support it, I realized that this
63 needed to be expressed as a date plus TWO modifications. In other
64 words, today modified to last month modified to the 15th day of the
65 month.
66 As bad as date plus modification formats are, a date plus TWO
68 modifications would be exponentially worse. On realizing that, I
69 decided that Date::Manip will not support this type of format.
70 Although I apologize for the inconvenience, I do not intend to
72 change my position on this.
73 Date::Manip is slow
75 Date::Manip is one of the slower Date/Time modules due to the fact
76 that it is huge and written entirely in perl. I have done a lot of
77 work optimizing it since 6.xx came out, and additional work is
78 planned, but even at it's best, it will probably be slower than
79 other modules.
80 Some things that will definitely help:
82 Date::Manip 5.xx was very slow. A lot of work went into speeding
84 it up as I rewrote it for the 6.xx release, and it should be noted
85 that initial tests show version 6.xx to be around twice as fast as
86 5.xx. There is one notable exception to this speedup. If you use
87 Date::Manip to parse dates from a wide variety of timezones, 6.xx
88 will be significantly slower than 5.xx. The reason for this is
89 that each time a new timezone is accessed, 6.xx does quite a bit of
90 work to initialize it. 5.xx does not have this overhead, so it can
91 parse dates from any number of timezones without a speed penalty.
92 However, 5.xx does NOT handle timezones correctly, so many of the
93 dates will be incorrect. If timezones are important to you, there
94 is no way to use 5.xx and get accurate results.
95 If you only parse dates from a single timezone (which is more often
97 what you are doing), 6.xx is significantly faster than 5.xx.
98 ISO-8601 dates are parsed first and fastest. If you have the
100 flexibility to define the date format, use ISO-8601 formats
101 whenever possible.
102 Avoid parsing dates that are referenced against the current time
104 (in 2 days, today at noon, etc.). These take a lot longer to
105 parse.
106 Business date calculations are extremely slow. You should consider
108 alternatives if possible (i.e. doing the calculation in exact mode
109 and then multiplying by 5/7). Who needs a business date more
110 accurate than "6 to 8 weeks" anyway, right :-)
111 Memory leak
113 There is a known memory leak in perl related to named regexp
114 captures that directly affects Date::Manip . The leak is in all
115 versions of perl up to (and including) the following versions:
116 5.10.1
118 5.12.5
119 5.14.3
120 5.15.5
121 The bug has been fixed in:
123 5.15.6
125 5.16.0
126 If a maintenance release is done for any of the other releases
128 (5.10, 5.12, 5.14), that includes the patch, I'll update this
129 section to include that information.
130 Date::Manip 5.xx is not susceptible, so using it may be a feasible
132 workaround, but if you need accurate timezone handling, this isn't
133 possible.
134 Simple tests estimate the leak to be about 3 MB per 10,000 dates
136 parsed, so unless you're parsing hundreds of thousands, or millions
137 of dates, the leak probably won't be a problem on systems with
138 moderate amounts of memory. And if you're parsing that many dates,
139 the relatively slow Date::Manip may not be the correct module for
140 you to use anyway.
141 Dmake error on strawberry perl
143 Users of Strawberry perl on windows may encounter an error similar
144 to the following:
145 dmake: makefile: line 3016: Error: -- Input line too long, increase MAXLINELENGTH
147 This is a known problem with some versions of strawberry perl, and
149 I can't fix it in Date::Manip. If you encounter this problem, you
150 can install the package manually using the commands:
151 c:> cpan
153 cpan> look Date::Manip::Date
154 > perl Makefile.PL
155 > dmake MAXLINELENGTH=300000 make
156 > dmake MAXLINELENGTH=300000 make test
157 > dmake MAXLINELENGTH=300000 make install
158 You can find more details here:
160 http://www.nntp.perl.org/group/perl.win32.vanilla/2011/02/msg287.html
162 Using functions/methods which are not supported
164 There have been a handful of incidents of people using a function
165 from Date::Manip which were not documented in the manual.
166 Date::Manip consists of a large number of user functions which are
168 documented in the manual. These are designed to be used by other
169 programmers, and I will not make any backwards incompatible changes
170 in them unless there is a very compelling reason to do so, and in
171 that case, the change will be clearly documented in the
172 Date::Manip::Changes6 documentation for this module.
173 Date::Manip also includes a large number of functions which are NOT
175 documented. These are for internal use only. Please do not use
176 them! I can (and do) change their functionality, and even their
177 name, without notice, and without apology! Some of these internal
178 functions even have test scripts, but that is not a guarantee that
179 they will not change, nor is any support implied. I simply like to
180 run regression tests on as much of Date::Manip as possible.
181 As of the most recent versions of Date::Manip, all internal
183 functions have names that begin with an underscore (_). If you
184 choose to use them directly, it is quite possible that new versions
185 of Date::Manip will cause your programs to break due to a change in
186 how those functions work.
187 Any changes to internal functions will not be documented, and will
189 not be regarded by me as a backwards incompatibility. Nor will I
190 (as was requested in one instance) revert to a previous version of
191 the internal function.
192 If you feel that an internal function is of more general use, feel
194 free to contact me with an argument of why it should be "promoted".
195 I welcome suggestions and will definitely consider any such
196 request.
197 RCS Control
199 If you try to put Date::Manip under RCS control, you are going to
200 have problems. Apparently, RCS replaces strings of the form
201 "$Date...$" with the current date. This form occurs all over in
202 Date::Manip. To prevent the RCS keyword expansion, checkout files
203 using:
204 co -ko
206 Since very few people will ever have a desire to do this (and I
208 don't use RCS), I have not worried about it, and I do not intend to
209 try to workaround this problem.
210
212 Date::Manip 6.xx has gotten some complaints (far more than 5.xx if the
213 truth be told), so I'd like to address a couple of them here. Perhaps
214 an understanding of why some of the changes were made will allay some
215 of the complaints. If not, people are always welcome to stick with the
216 5.xx release. I will continue to support the 5.xx releases for a couple
217 years (though I do NOT plan to add functionality to it).
218 These complaints come both from both the CPAN ratings site:
220 http://cpanratings.perl.org/dist/Date-Manip
222 and from personal email.
224 Requires perl 5.10
226 The single most controversial change made in 6.00 is that it now
227 required perl 5.10.0 or higher. Most of the negative feedback I've
228 received is due to this.
229 In the past, I've avoided using new features of perl in order to
231 allow Date::Manip to run on older versions of perl. Prior to perl
232 5.10, none of the new features would have had a major impact on how
233 Date::Manip was written so this practice was justified. That all
234 changed with the release of perl 5.10.
235 One of the aspects of Date::Manip that has received the most
237 positive response is the ability to parse almost every conceivable
238 date format. Unfortunately, as I've added formats, the parsing
239 routine became more and more complicated, and maintaining it was
240 one of the least enjoyable aspect in maintaining Date::Manip . In
241 fact, for several years I'd been extremely reluctant to add new
242 formats due to the fact that too often, adding a new format broke
243 other formats.
244 As I was rewriting Date::Manip, I was looking for ways to improve
246 the parsing and to make maintaining it easier. Perl 5.10 provides
247 the feature "named capture buffers". Named capture buffers not only
248 improves the ease of maintaining the complex regular expressions
249 used by Date::Manip, it makes it dramatically easier to add
250 additional formats in a way that is much less likely to interfere
251 with other formats. The parsing in 6.00 is so much more robust,
252 extensible, and flexible, that it will make parser maintenance
253 possible for many years to come at a fraction of the effort and
254 risk.
255 It was too much to turn down. Hopefully, since 5.10 has been out
257 for some time now, this will not prohibit too many people from
258 using the new version of Date::Manip. I realize that there are many
259 people out there using older versions of perl who do not have the
260 option of upgrading perl. The decision to use 5.10 wasn't made
261 lightly... but I don't regret making it. I apologize to users who,
262 as a result, cannot use 6.00 . Hopefully in the future you'll be
263 able to benefit from the improvements in 6.00.
264 One complaint I've received is that this in some way makes
266 Date::Manip backwards incompatible, but this is not an accurate
267 complaint. Version 6.xx DOES include some backwards
268 incompatibilities (and these are covered in the
269 Date::Manip::Migration5to6 document), however in almost all cases,
270 these incompatibilities are with infrequently used features, or
271 workarounds are in place to allow deprecated features to continue
272 functioning for some period of time.
273 Though I have no data to confirm this, I suspect that 90% or more
275 of all scripts which were written with Date::Manip 5.xx will
276 continue to work unmodified with 6.xx (of course, you should still
277 refer to the migration document to see what features are deprecated
278 or changed to make sure that you don't need to modify your script
279 so that it will continue to work in the future). Even with scripts
280 that need to be changed, the changes should be trivial.
281 So, Date::Manip 6.xx is almost entirely backward compatible with
283 5.xx (to the extent that you would expect any major version release
284 to be compatible with a previous major version).
285 The change is only in the requirements necessary to get Date::Manip
287 6.xx to run.
288 Obviously, it's not reasonable to say that Date::Manip should never
290 be allowed to switch minimum perl versions. At some point, you have
291 to let go of an old version if you want to make use of the features
292 of the newer version. The question is, did I jump to 5.10 too fast?
293 The negative ratings I see in the CPAN ratings complain that I no
295 longer support perl 5.6 and perl 5.8.
296 With respect to 5.6, perl 5.6 was released in March of 2000 (that's
298 before Windows XP which was released in 2001). Date::Manip 6.00 was
299 released at the end of 2009. To be honest, I don't really feel
300 much sympathy for this complaint. Software that is 9 years old is
301 ANCIENT. People may choose to use it... but please don't complain
302 when new software comes out that doesn't support it.
303 The argument for perl 5.8 is much more compelling. Although 5.8 was
305 released well before Date::Manip 6.00 (July of 2002), there were no
306 major perl releases until 5.10 came out in December of 2007, so 5.8
307 was state-of-the art as little as 2 years prior to the release of
308 Date::Manip 6.xx.
309 I agree completely with the argument that abandoning 5.8 only 2
311 years after it was the current version is too soon. For that
312 reason, I continued to support the Date::Manip 5.xx releases for
313 several years. As of December 2012 (5 years after the release of
314 perl 5.10), the 5.xx release is no longer supported (in that I will
315 not patch it or provide support for it's use). However, it is
316 still bundled into the Date::Manip distribution so it can still be
317 used. I do not have any plans for removing it, though I may do so
318 at some point.
319 Too many modules
321 One minor complaint is that there are too many files. One person
322 specifically objects to the fact that there are over 470 modules
323 covering non-minute offsets. This complaint is (IMO) silly.
324 Date::Manip supports ALL historical time zones, including those
326 with non-minute offsets, and so there will be information for those
327 time zones, even though they are not currently in use.
328 I could of course store all of the information in one big module,
330 but that means that you have to load all of that data every time
331 you use Date::Manip, and I find that to be a very poor solution.
332 Instead, storing the information in a per-time zone and per-offset
333 manner dramatically decreases the amount of data that has to be
334 loaded.
335 While it is true that Date::Manip includes over 900 modules for all
337 of the time zone information, most implementations of time zone
338 handling also choose to break up the data into a large number of
339 files.
340 My linux distribution (openSuSE 11.2 at the time of writing this)
342 uses the standard zoneinfo database, and at this point, there are
343 over 1700 files included in /usr/share/zoneinfo (though it does
344 appear that there is some duplication of information). Current
345 versions of RedHat also use over 1700 files, so Date::Manip isn't
346 treating the time zone data in a new or unreasonable way.
347 Objects are large
349 One complaint that was put on the CPAN ratings site was that the OO
350 interface is "a dud" due to the size of it's objects. The complaint
351 is that a Date::Manip::Date object is 115K while it should
352 (according to the complaint) only require that you need to save the
353 seconds from the epoch, zone, and a couple other pieces of
354 information, all of which could probably be stored in 100 bytes or
355 less.
356 This complaint is not accurate, and comes from a misunderstanding
358 of the objects used by Date::Manip.
359 Date::Manip is very configurable, and contains a great deal of
361 information which could theoretically be calculated on the fly, but
362 which would greatly reduce it's performance. Instead, in the
363 interest of improving performance, the data is cached, and since
364 the data is virtually all potentially object specific, it has to be
365 somehow linked to the object.
366 For example, Date::Manip allows you to parse dates in several
368 languages. Each language has a large number of regular expressions
369 which are used to do the actual parsing. Instead of recreating
370 these regular expressions each time they are needed, they are
371 created once and stored in an object (specifically, a
372 Date::Manip::Base object). The size of the Date::Manip::Base
373 object is almost 15K (due primarily to the regular expressions used
374 in parsing dates in the selected language).
375 Similarly, a description of the time zones are stored in a second
377 object (a Date::Manip::TZ object). The size of the Date::Manip::TZ
378 object starts at 100K. That may seem excessive, but you have to
379 remember that there are almost 500 time zones, and they have to be
380 indexed by name, alias, abbreviation, and offset. In addition,
381 critical dates (dates where the offset from GMT change such as
382 during a daylight saving time change) along with information such
383 as offsets, abbreviation, etc., are all cached in order to improve
384 performance. By the time you do this, it does take a fair bit of
385 space. It should also be noted that the full description of each
386 timezone is only stored in the object when the timezone is actually
387 used, so if you use a lot of timezones, this object will grow
388 slowly as new timezones are used.
389 The size of the actual Date::Manip::Date object is a little over
391 300 bytes. However, each includes a pointer to a Date::Manip::Base
392 and a Date::Manip::TZ object (and due to how the object was being
393 looked at in the complaint, they were reporting the size of all
394 three objects, NOT just the Date::Manip::Date object).
395 Both the Date::Manip::Base and Date::Manip::TZ objects are reused
397 by any number of Date::Manip::Date objects. They can almost be
398 thought of as global data, except that they are accessible in the
399 standard OO manner, and you are allowed to modify them on a per-
400 object basis which WILL mean that you have to store more data. If
401 you work with multiple configurations (see Date::Manip::Config),
402 you'll need multiple Base and TZ objects. However, most of the time
403 you will not need to do this.
404 The actual Date::Manip::Date object is a bit larger than suggested
406 in the complaint, but it should be noted that Date::Manip actually
407 stores the dates in a number of different formats (a string of the
408 form YYYYMMDDHH:MN:SS and a list [YYYY,MM,DD,HH,MN,SS] in the time
409 zone it was parsed in, the local time zone (if different) and GMT.
410 By caching this information as it is used, it has a huge impact on
411 the performance.
412 So, Date::Manip in typical usage consists of one 100K
414 Date::Manip::TZ object, one 15K Date::Manip::Base objects, and any
415 number of small 300 byte Date::Manip::Date objects.
416 Date::Manip::Delta objects are even smaller. Date::Manip::Recur
417 objects are also small, but they contain any number of Date objects
418 in them.
419 I am certainly open to suggestions as to how I can improve the OO
421 interface... but I don't believe it is a dud. While I'm not an
422 expert at OO programming, I believe that I followed pretty standard
423 and accepted procedures for accessing the data.
424 Please refer to the Date::Manip::Objects document for more
426 information.
427 Date::Manip has an inconsistent interface
429 I've gotten a few complaints that the interface to Date::Manip is
430 inconsistent... and I agree (at least when referring to the
431 functional interfaces).
432 Date::Manip was originally written in an unplanned way... as a
434 need/want came up, it was extended. That's not the way to write a
435 major package of course, but it wasn't expected to be a major
436 package at the start.
437 As it became more and more widely used, I too wished for a more
439 consistent interface, but I did not want to break backward
440 compatibility for everyone using it.
441 When 6.xx was written, I spent a good deal of time trying to make a
443 very standard OO interface, so I do not believe that this complaint
444 can be applied to the OO interface (though I'm interested in
445 suggestions for improving it of course).
446 As far as the functional interface goes, I'll continue to support
448 it in a backward compatible (and therefore inconsistent) form. I'd
449 encourage the use of the OO interface whenever possible.
450
452 If you find a bug in Date::Manip, there are three ways to send it to
453 me. In order of preference, they are:
454 GitHub
456 You can submit it as an issue on GitHub. This can be done at the
457 following URL:
458 <https://github.com/SBECK-github/Date-Manip>
460 This is the preferred method. Please submit problems requests as
462 GitHub issues if at all possible.
463 Direct email
465 You are welcome to send it directly to me by email. The email
466 address to use is: sbeck@cpan.org.
467 Please note that because cpan.org addresses are published, they are
469 used by a lot of spammers and phishers. Please include the name of
470 the perl module in the subject line of ALL messages sent to my
471 cpan.org address or it will likely be missed.
472 CPAN Bug Tracking
474 You can submit it using the CPAN tracking too. This can be done at
475 the following URL:
476 <http://rt.cpan.org/Public/Dist/Display.html?Name=Date-Manip>
478 There was discussion of halting this service a while back (though
480 it continues to function), so only use this as a last resort.
481 Please do not use other means to report bugs (such as forums for a
483 specific OS or Linux distribution) as it is impossible for me to keep
484 up with all of them.
485 When filing a bug report, please include the following information:
487 Date::Manip version
489 Please include the version of Date::Manip you are using. You can
490 get this by using the script:
491 use Date::Manip;
493 print DateManipVersion(1),"\n";
494 or
496 use Date::Manip::Date;
498 $obj = new Date::Manip::Date;
499 print $obj->version(1),"\n";
500 Perl information
502 Please include the output from "perl -V"
503 If you have a problem using Date::Manip that perhaps isn't a bug (can't
505 figure out the syntax, etc.), you're in the right place. Start by
506 reading the main Date::Manip documentation, and the other documents
507 that apply to whatever you are trying to do. If this still doesn't
508 answer your question, mail me directly.
509 I would ask that you be reasonably familiar with the documentation
511 BEFORE you choose to do this. Date::Manip is a hobby, and I simply do
512 not have time to respond to hundreds of questions which are already
513 answered in this manual.
514 If you find any problems with the documentation (errors, typos, or
516 items that are not clear), please send them to me. I welcome any
517 suggestions that will allow me to improve the documentation.
518
520 None known.
521
523 Date::Manip - main module documentation
524
526 This script is free software; you can redistribute it and/or modify it
527 under the same terms as Perl itself.
528
530 Sullivan Beck (sbeck@cpan.org)
531perl v5.36.0 2022-12-10 Date::Manip::Problems(3)