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 Requires perl 5.10
220 The single most controversial change made in 6.00 is that it now
221 required perl 5.10.0 or higher. Most of the negative feedback I've
222 received is due to this.
223 In the past, I've avoided using new features of perl in order to
225 allow Date::Manip to run on older versions of perl. Prior to perl
226 5.10, none of the new features would have had a major impact on how
227 Date::Manip was written so this practice was justified. That all
228 changed with the release of perl 5.10.
229 One of the aspects of Date::Manip that has received the most
231 positive response is the ability to parse almost every conceivable
232 date format. Unfortunately, as I've added formats, the parsing
233 routine became more and more complicated, and maintaining it was
234 one of the least enjoyable aspect in maintaining Date::Manip . In
235 fact, for several years I'd been extremely reluctant to add new
236 formats due to the fact that too often, adding a new format broke
237 other formats.
238 As I was rewriting Date::Manip, I was looking for ways to improve
240 the parsing and to make maintaining it easier. Perl 5.10 provides
241 the feature "named capture buffers". Named capture buffers not only
242 improves the ease of maintaining the complex regular expressions
243 used by Date::Manip, it makes it dramatically easier to add
244 additional formats in a way that is much less likely to interfere
245 with other formats. The parsing in 6.00 is so much more robust,
246 extensible, and flexible, that it will make parser maintenance
247 possible for many years to come at a fraction of the effort and
248 risk.
249 It was too much to turn down. Hopefully, since 5.10 has been out
251 for some time now, this will not prohibit too many people from
252 using the new version of Date::Manip. I realize that there are many
253 people out there using older versions of perl who do not have the
254 option of upgrading perl. The decision to use 5.10 wasn't made
255 lightly... but I don't regret making it. I apologize to users who,
256 as a result, cannot use 6.00 . Hopefully in the future you'll be
257 able to benefit from the improvements in 6.00.
258 One complaint I've received is that this in some way makes
260 Date::Manip backwards incompatible, but this is not an accurate
261 complaint. Version 6.xx DOES include some backwards
262 incompatibilities (and these are covered in the
263 Date::Manip::Migration5to6 document), however in almost all cases,
264 these incompatibilities are with infrequently used features, or
265 workarounds are in place to allow deprecated features to continue
266 functioning for some period of time.
267 Though I have no data to confirm this, I suspect that 90% or more
269 of all scripts which were written with Date::Manip 5.xx will
270 continue to work unmodified with 6.xx (of course, you should still
271 refer to the migration document to see what features are deprecated
272 or changed to make sure that you don't need to modify your script
273 so that it will continue to work in the future). Even with scripts
274 that need to be changed, the changes should be trivial.
275 So, Date::Manip 6.xx is almost entirely backward compatible with
277 5.xx (to the extent that you would expect any major version release
278 to be compatible with a previous major version).
279 The change is only in the requirements necessary to get Date::Manip
281 6.xx to run.
282 Obviously, it's not reasonable to say that Date::Manip should never
284 be allowed to switch minimum perl versions. At some point, you have
285 to let go of an old version if you want to make use of the features
286 of the newer version. The question is, did I jump to 5.10 too fast?
287 The negative ratings I see in the CPAN ratings complain that I no
289 longer support perl 5.6 and perl 5.8.
290 With respect to 5.6, perl 5.6 was released in March of 2000 (that's
292 before Windows XP which was released in 2001). Date::Manip 6.00 was
293 released at the end of 2009. To be honest, I don't really feel
294 much sympathy for this complaint. Software that is 9 years old is
295 ANCIENT. People may choose to use it... but please don't complain
296 when new software comes out that doesn't support it.
297 The argument for perl 5.8 is much more compelling. Although 5.8 was
299 released well before Date::Manip 6.00 (July of 2002), there were no
300 major perl releases until 5.10 came out in December of 2007, so 5.8
301 was state-of-the art as little as 2 years prior to the release of
302 Date::Manip 6.xx.
303 I agree completely with the argument that abandoning 5.8 only 2
305 years after it was the current version is too soon. For that
306 reason, I continued to support the Date::Manip 5.xx releases for
307 several years. As of December 2012 (5 years after the release of
308 perl 5.10), the 5.xx release is no longer supported (in that I will
309 not patch it or provide support for it's use). However, it is
310 still bundled into the Date::Manip distribution so it can still be
311 used. I do not have any plans for removing it, though I may do so
312 at some point.
313 Too many modules
315 One minor complaint is that there are too many files. One person
316 specifically objects to the fact that there are over 470 modules
317 covering non-minute offsets. This complaint is (IMO) silly.
318 Date::Manip supports ALL historical time zones, including those
320 with non-minute offsets, and so there will be information for those
321 time zones, even though they are not currently in use.
322 I could of course store all of the information in one big module,
324 but that means that you have to load all of that data every time
325 you use Date::Manip, and I find that to be a very poor solution.
326 Instead, storing the information in a per-time zone and per-offset
327 manner dramatically decreases the amount of data that has to be
328 loaded.
329 While it is true that Date::Manip includes over 900 modules for all
331 of the time zone information, most implementations of time zone
332 handling also choose to break up the data into a large number of
333 files.
334 My linux distribution (openSuSE 11.2 at the time of writing this)
336 uses the standard zoneinfo database, and at this point, there are
337 over 1700 files included in /usr/share/zoneinfo (though it does
338 appear that there is some duplication of information). Current
339 versions of RedHat also use over 1700 files, so Date::Manip isn't
340 treating the time zone data in a new or unreasonable way.
341 Objects are large
343 One complaint that was put on the CPAN ratings site was that the OO
344 interface is "a dud" due to the size of it's objects. The complaint
345 is that a Date::Manip::Date object is 115K while it should
346 (according to the complaint) only require that you need to save the
347 seconds from the epoch, zone, and a couple other pieces of
348 information, all of which could probably be stored in 100 bytes or
349 less.
350 This complaint is not accurate, and comes from a misunderstanding
352 of the objects used by Date::Manip.
353 Date::Manip is very configurable, and contains a great deal of
355 information which could theoretically be calculated on the fly, but
356 which would greatly reduce it's performance. Instead, in the
357 interest of improving performance, the data is cached, and since
358 the data is virtually all potentially object specific, it has to be
359 somehow linked to the object.
360 For example, Date::Manip allows you to parse dates in several
362 languages. Each language has a large number of regular expressions
363 which are used to do the actual parsing. Instead of recreating
364 these regular expressions each time they are needed, they are
365 created once and stored in an object (specifically, a
366 Date::Manip::Base object). The size of the Date::Manip::Base
367 object is almost 15K (due primarily to the regular expressions used
368 in parsing dates in the selected language).
369 Similarly, a description of the time zones are stored in a second
371 object (a Date::Manip::TZ object). The size of the Date::Manip::TZ
372 object starts at 100K. That may seem excessive, but you have to
373 remember that there are almost 500 time zones, and they have to be
374 indexed by name, alias, abbreviation, and offset. In addition,
375 critical dates (dates where the offset from GMT change such as
376 during a daylight saving time change) along with information such
377 as offsets, abbreviation, etc., are all cached in order to improve
378 performance. By the time you do this, it does take a fair bit of
379 space. It should also be noted that the full description of each
380 timezone is only stored in the object when the timezone is actually
381 used, so if you use a lot of timezones, this object will grow
382 slowly as new timezones are used.
383 The size of the actual Date::Manip::Date object is a little over
385 300 bytes. However, each includes a pointer to a Date::Manip::Base
386 and a Date::Manip::TZ object (and due to how the object was being
387 looked at in the complaint, they were reporting the size of all
388 three objects, NOT just the Date::Manip::Date object).
389 Both the Date::Manip::Base and Date::Manip::TZ objects are reused
391 by any number of Date::Manip::Date objects. They can almost be
392 thought of as global data, except that they are accessible in the
393 standard OO manner, and you are allowed to modify them on a per-
394 object basis which WILL mean that you have to store more data. If
395 you work with multiple configurations (see Date::Manip::Config),
396 you'll need multiple Base and TZ objects. However, most of the time
397 you will not need to do this.
398 The actual Date::Manip::Date object is a bit larger than suggested
400 in the complaint, but it should be noted that Date::Manip actually
401 stores the dates in a number of different formats (a string of the
402 form YYYYMMDDHH:MN:SS and a list [YYYY,MM,DD,HH,MN,SS] in the time
403 zone it was parsed in, the local time zone (if different) and GMT.
404 By caching this information as it is used, it has a huge impact on
405 the performance.
406 So, Date::Manip in typical usage consists of one 100K
408 Date::Manip::TZ object, one 15K Date::Manip::Base objects, and any
409 number of small 300 byte Date::Manip::Date objects.
410 Date::Manip::Delta objects are even smaller. Date::Manip::Recur
411 objects are also small, but they contain any number of Date objects
412 in them.
413 I am certainly open to suggestions as to how I can improve the OO
415 interface... but I don't believe it is a dud. While I'm not an
416 expert at OO programming, I believe that I followed pretty standard
417 and accepted procedures for accessing the data.
418 Please refer to the Date::Manip::Objects document for more
420 information.
421 Date::Manip has an inconsistent interface
423 I've gotten a few complaints that the interface to Date::Manip is
424 inconsistent... and I agree (at least when referring to the
425 functional interfaces).
426 Date::Manip was originally written in an unplanned way... as a
428 need/want came up, it was extended. That's not the way to write a
429 major package of course, but it wasn't expected to be a major
430 package at the start.
431 As it became more and more widely used, I too wished for a more
433 consistent interface, but I did not want to break backward
434 compatibility for everyone using it.
435 When 6.xx was written, I spent a good deal of time trying to make a
437 very standard OO interface, so I do not believe that this complaint
438 can be applied to the OO interface (though I'm interested in
439 suggestions for improving it of course).
440 As far as the functional interface goes, I'll continue to support
442 it in a backward compatible (and therefore inconsistent) form. I'd
443 encourage the use of the OO interface whenever possible.
444
446 If you find a bug in Date::Manip, there are three ways to send it to
447 me. In order of preference, they are:
448 GitHub
450 You can submit it as an issue on GitHub. This can be done at the
451 following URL:
452 <https://github.com/SBECK-github/Date-Manip>
454 This is the preferred method. Please submit problems requests as
456 GitHub issues if at all possible.
457 Direct email
459 You are welcome to send it directly to me by email. The email
460 address to use is: sbeck@cpan.org.
461 Please note that because cpan.org addresses are published, they are
463 used by a lot of spammers and phishers. Please include the name of
464 the perl module in the subject line of ALL messages sent to my
465 cpan.org address or it will likely be missed.
466 CPAN Bug Tracking
468 You can submit it using the CPAN tracking too. This can be done at
469 the following URL:
470 <http://rt.cpan.org/Public/Dist/Display.html?Name=Date-Manip>
472 There was discussion of halting this service a while back (though
474 it continues to function), so only use this as a last resort.
475 Please do not use other means to report bugs (such as forums for a
477 specific OS or Linux distribution) as it is impossible for me to keep
478 up with all of them.
479 When filing a bug report, please include the following information:
481 Date::Manip version
483 Please include the version of Date::Manip you are using. You can
484 get this by using the script:
485 use Date::Manip;
487 print DateManipVersion(1),"\n";
488 or
490 use Date::Manip::Date;
492 $obj = new Date::Manip::Date;
493 print $obj->version(1),"\n";
494 Perl information
496 Please include the output from "perl -V"
497 If you have a problem using Date::Manip that perhaps isn't a bug (can't
499 figure out the syntax, etc.), you're in the right place. Start by
500 reading the main Date::Manip documentation, and the other documents
501 that apply to whatever you are trying to do. If this still doesn't
502 answer your question, mail me directly.
503 I would ask that you be reasonably familiar with the documentation
505 BEFORE you choose to do this. Date::Manip is a hobby, and I simply do
506 not have time to respond to hundreds of questions which are already
507 answered in this manual.
508 If you find any problems with the documentation (errors, typos, or
510 items that are not clear), please send them to me. I welcome any
511 suggestions that will allow me to improve the documentation.
512
514 None known.
515
517 Date::Manip - main module documentation
518
520 This script is free software; you can redistribute it and/or modify it
521 under the same terms as Perl itself.
522
524 Sullivan Beck (sbeck@cpan.org)
525perl v5.38.0 2023-07-20 Date::Manip::Problems(3)