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