1Date::Manip::Problems(3U)ser Contributed Perl DocumentatiDoante::Manip::Problems(3)
2
3
4

NAME

6       Date::Manip::Problems - problems and bugs
7

KNOWN PROBLEMS

9       The following are not bugs in Date::Manip, but they may give some
10       people problems.
11
12       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
18       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
24           *NOTE* This should be less of a problem since 6.30 with the
25           addition of semi-exact deltas.
26
27       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
33           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
37           There is a class of formats that I do not plan to add however.
38
39           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
44           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
48           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
54           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
60           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
67           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
71           Although I apologize for the inconvenience, I do not intend to
72           change my position on this.
73
74       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
81           Some things that will definitely help:
82
83           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
96           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
99           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
103           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
107           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
112       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
117              5.10.1
118              5.12.5
119              5.14.3
120              5.15.5
121
122           The bug has been fixed in:
123
124              5.15.6
125              5.16.0
126
127           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
131           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
135           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
142       Dmake error on strawberry perl
143           Users of Strawberry perl on windows may encounter an error similar
144           to the following:
145
146              dmake: makefile: line 3016: Error: -- Input line too long, increase MAXLINELENGTH
147
148           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
152              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
159           You can find more details here:
160
161              http://www.nntp.perl.org/group/perl.win32.vanilla/2011/02/msg287.html
162
163       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
167           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
174           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
182           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
188           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
193           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
198       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
205              co -ko
206
207           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

KNOWN COMPLAINTS

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
219       These complaints come both from both the CPAN ratings site:
220
221          http://cpanratings.perl.org/dist/Date-Manip
222
223       and from personal email.
224
225       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
230           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
236           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
245           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
256           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
265           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
274           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
282           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
286           The change is only in the requirements necessary to get Date::Manip
287           6.xx to run.
288
289           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
294           The negative ratings I see in the CPAN ratings complain that I no
295           longer support perl 5.6 and perl 5.8.
296
297           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
304           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
310           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
320       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
325           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
329           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
336           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
341           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
348       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
357           This complaint is not accurate, and comes from a misunderstanding
358           of the objects used by Date::Manip.
359
360           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
367           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
376           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
390           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
396           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
405           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
413           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
420           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
425           Please refer to the Date::Manip::Objects document for more
426           information.
427
428       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
433           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
438           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
442           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
447           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

BUGS AND QUESTIONS

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
455       GitHub
456           You can submit it as an issue on GitHub.  This can be done at the
457           following URL:
458
459           <https://github.com/SBECK-github/Date-Manip>
460
461           This is the preferred method.  Please submit problems requests as
462           GitHub issues if at all possible.
463
464       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
468           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
473       CPAN Bug Tracking
474           You can submit it using the CPAN tracking too.  This can be done at
475           the following URL:
476
477           <http://rt.cpan.org/Public/Dist/Display.html?Name=Date-Manip>
478
479           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
482       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
486       When filing a bug report, please include the following information:
487
488       Date::Manip version
489           Please include the version of Date::Manip you are using.  You can
490           get this by using the script:
491
492              use Date::Manip;
493              print DateManipVersion(1),"\n";
494
495           or
496
497              use Date::Manip::Date;
498              $obj = new Date::Manip::Date;
499              print $obj->version(1),"\n";
500
501       Perl information
502           Please include the output from "perl -V"
503
504       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
510       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
515       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

KNOWN BUGS

520       None known.
521

SEE ALSO

523       Date::Manip        - main module documentation
524

LICENSE

526       This script is free software; you can redistribute it and/or modify it
527       under the same terms as Perl itself.
528

AUTHOR

530       Sullivan Beck (sbeck@cpan.org)
531
532
533
534perl v5.36.0                      2022-12-10          Date::Manip::Problems(3)
Impressum